Lotus Domino Designer

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

COPYRIGHTUnder the copyright laws, neither the documentation nor the software may be copied, photocopied,reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the mannerdescribed in the documentation or the applicable licensing agreement governing the use of the software.

© Copyright 1985 – 1999 Lotus Development Corporation55 Cambridge ParkwayCambridge, MA 02142

All rights reserved. Printed in the United States.

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

Preface . . . . . . . . . . . . . . . . . . . xi. . .

1 Introduction to Domino Designer . . . . . . . . . . . 1. . . .Overview — applications and databases 1. . . .

Starting Designer . . . . . . . . . . . . . . . . . . 3. . . .

Exploring Designer . . . . . . . . . . . . . . . . 4. . . .

Displaying, collecting, and storinginformation — pages, forms,documents, and fields . . . . . . . . . 6. . . .

Organizing your data — views and folders . . . . . . . . . . . . . . . . . . 10. . .

Creating navigation — outlines and navigators . . . . . . . . . . . . . . . 11. . .

Structuring your display — framesets . 12. . .

Adding automation — actions, hotspots,and agents . . . . . . . . . . . . . . . . . . 13. . .

Getting database information — design synopsis . . . . . . . . . . . . . . 14. . .

2 Creating an Application . . . 15. .Domino databases . . . . . . . . . . . . . . . . . 15. . .

Creating databases . . . . . . . . . . . . . . . . 16. . .

Creating a database from a template . . . 16. . .

Copying an existing Domino database . 18. . .

Starting a database from scratch . . . . . . 20. . .

Tips for designing Web applications . . . 21. . .

Domino Applets . . . . . . . . . . . . . . . . . . 22. . .

Changing database and designproperties . . . . . . . . . . . . . . . . . . . 23. . .

Setting “Use JavaScript whengenerating pages” for a database . 23. . .

Setting database launch properties . . 25. . .

Settings for multilingual applications 27. . .

HTML tag attributes for a Domino server . . . . . . . . . . . . . . . 28. . .

Hide-when options . . . . . . . . . . . . . . 29. . .

Enabling subscriptions . . . . . . . . . . . 30. . .

Reducing database maintenance withshared resources . . . . . . . . . . . . . 30. . .

Creating an image resource . . . . . . . . . . 31. . .

Designing an application for maximumaccessibility for people with disabilities . . . . . . . . . . . . . . 35. . .

Previewing your design work . . . . . . . . 37. . .

3 Designing Outlines . . . . . . . 41. .Outlines . . . . . . . . . . . . . . . . . . . . . . . . . 41. . .

Creating an outline . . . . . . . . . . . . . . 42. . .

Embedding an outline . . . . . . . . . . . 45. . .

Outline, outline entry, and embeddedoutline properties . . . . . . . . . . . . . 46. . .

Selected outline properties . . . . . . . . 46. . .

Selected outline entry properties . . . 46. . .

Selected embedded outline properties . . . . . . . . . . . . . 47. . .

Using the outline applet . . . . . . . . . . . . 51. . .

Displaying the outline in a Frameset . . . 52. . .

4 Designing Pages . . . . . . . . . 53. .Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 53. . .

Creating a page . . . . . . . . . . . . . . . . . 55. . .

Displaying a page . . . . . . . . . . . . . . . 55. . .

Creating a home page for an application . . . . . . . . . . . . . . . 56. . .

Styling text for the Web . . . . . . . . . . 57. . .

Contents iii

Contents

CT6E2NA

Please note that the page numbers listed in the Table of Contents refer to the page numbers that appear in the footers of the printed documentation. To navigate to a specific page, select the chapter and use the scroll buttons in the tool bar to go to the page.

Creating computed text . . . . . . . . . . 58. . .

Changing all text styles . . . . . . . . . . . 58. . .

Creating and formatting horizontal rules . . . . . . . . . . . . . . 59. . .

Creating programmable tables . . . . . 60. . .

Creating sections . . . . . . . . . . . . . . . . 61. . .

Creating links . . . . . . . . . . . . . . . . . . 62. . .

Adding graphics . . . . . . . . . . . . . . . . 64. . .

Adding a background color or graphic . . . . . . . . . . . . . . . . . . . 68. . .

Creating an imagemap . . . . . . . . . . . 69. . .

Adding an applet . . . . . . . . . . . . . . . 70. . .

Creating an attachment . . . . . . . . . . . 71. . .

Embedding elements . . . . . . . . . . . . 71. . .

Importing, pasting, or entering HTML . . . . . . . . . . . . . . 73. . .

Launch properties for pages or forms . . . . . . . . . . . . . . . . . . . . 74. . .

Programming a page or form . . . . . . . . 75. . .

Adding HTML header information . 75. . .

Adding JavaScript header information . . . . . . . . . . . 75. . .

5 Designing Forms . . . . . . . . . 79. .Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 79. . .

Form Elements . . . . . . . . . . . . . . . . . . . . 80. . .

Forms and documents . . . . . . . . . . . . . . 81. . .

Creating a form . . . . . . . . . . . . . . . . . . . 84. . .

Tips for designing forms . . . . . . . . . . 85. . .

Naming forms . . . . . . . . . . . . . . . . . . 86. . .

Making a form available to Web browsers . . . . . . . . . . . . . . . 88. . .

Selected form properties . . . . . . . . . . . . 90. . .

Creating a response hierarchy . . . . . 92. . .

Version tracking . . . . . . . . . . . . . . . . 93. . .

Customizing a form’s window title . . . . 95. . .

Subforms . . . . . . . . . . . . . . . . . . . . . . . . 97. . .

Layout regions . . . . . . . . . . . . . . . . . . . . 99. . .

Aligning and rearranging elementsin a layout region . . . . . . . . . . . . . 100. .

Changing the size and style of alayout region . . . . . . . . . . . . . . . . 100. .

Adding a graphic to a layout region . 101. .

Embedded Controls . . . . . . . . . . . . . . . . 102. .

Adding a file upload control . . . . . . . 102. .

Adding a group scheduler . . . . . . . . 102. .

Profile forms . . . . . . . . . . . . . . . . . . . . . 106. .

Designing forms that prompt users for input . . . . . . . . . . . . . . . . . . . . 108. .

Designing a form that presents adialog box . . . . . . . . . . . . . . . . . . 108. .

Designing a form that prompts usersfor information . . . . . . . . . . . . . . . 109. .

Designing a form that lets usersmake selections from a view . . . . 110. .

Designing a form for a Dominobilling application . . . . . . . . . . . . 111. .

Customizing “Form processed”confirmation for the Web . . . . . . . 112. .

Customizing search forms . . . . . . . . . . . 113. .

Tips for improving document display time . . . . . . . . . . . . . . . . . 118. .

Testing a form before deploying it . . . . . 119. .

6 Designing Fields . . . . . . . . . 121.Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 121. .

Creating a shared field . . . . . . . . . . . . . 122. .

Field names and labels . . . . . . . . . . . . . 124. .

Defining field types . . . . . . . . . . . . . . . . 125. .

Text and rich text fields . . . . . . . . . . 126. .

Rich text fields on the Web . . . . . . . . 126. .

Number fields . . . . . . . . . . . . . . . . . . 128. .

Date/Time fields . . . . . . . . . . . . . . . . 129. .

Formulas for Date/Time fields . . . . . 133. .

iv Application Development with Domino Designer

Creating a graphical display forDate/Time fields . . . . . . . . . . . . . 133. .

Names fields . . . . . . . . . . . . . . . . . . . 136. .

Readers and Authors fields . . . . . . . 137. .

Creating fields to display lists of choices . . . . . . . . . . . . . . . . . . . 137. .

Generating choices for lists . . . . . . . . 139. .

Creating aliases for choices in a list . 140. .

Password fields . . . . . . . . . . . . . . . . . 142. .

Formula fields . . . . . . . . . . . . . . . . . . 144. .

Editable and computed fields . . . . . . . . 146. .

Editable field formulas . . . . . . . . . . . 148. .

Selected Field Properties . . . . . . . . . . . . 151. .

Hiding fields . . . . . . . . . . . . . . . . . . . . . 153. .

Creating a field in a layout region . . . . . 155. .

Adding HTML attributes to a field . . . . 156. .

Storing HTML in a field . . . . . . . . . . . . . 157. .

Creating fields that inherit values . . . . . 157. .

Creating a field that inherits an entire document . . . . . . . . . . . . . . 158. .

Inheriting information in a response hierarchy . . . . . . . . . . . . 159. .

Standard fields used in templates . . . . . 160. .

Predefined fields with built-in functionality . . . . . . . . . . 160. .

Fields for version tracking . . . . . . . . . . . 162. .

Fields that prompt users to select folders . . . . . . . . . . . . . . . . 164. .

7 Designing Framesets . . . . 165.Overview of framesets . . . . . . . . . . . . . . 165. .

Creating a frameset . . . . . . . . . . . . . . . . 166. .

Providing content for a frame . . . . . . . . 168. .

Setting the style for frames . . . . . . . . . . 170. .

Launching a database into a frameset . . 171. .

Launching a document or page into a frameset . . . . . . . . . . . . . . . . . . . 172. .

8 Designing Views . . . . . . . . . 173.Views . . . . . . . . . . . . . . . . . . . . . . . . . . . 173. .

Standard views . . . . . . . . . . . . . . . . . 174. .

Calendar views . . . . . . . . . . . . . . . . . 176. .

Shared and private views . . . . . . . . . . . 178. .

Creating a view . . . . . . . . . . . . . . . . . . . 179. .

Naming a view . . . . . . . . . . . . . . . . . . . 181. .

Columns . . . . . . . . . . . . . . . . . . . . . . . . 184. .

Adding titles to columns . . . . . . . . . . 184. .

Adding categories to views . . . . . . . . 185. .

Categorizing in the All by Category view . . . . . . . . . . . . . . . 186. .

Generating category names . . . . . . . 187. .

Programming which documentsdisplay in a view . . . . . . . . . . . . . 189. .

Table of document selection conditionsfor views . . . . . . . . . . . . . . . . . . . 191. .

Adding programming to columns . . . . . 194. .

Table of simple functions for columns . . 197. .

Displaying an icon in a column . . . . . . . 200. .

Sorting documents in views . . . . . . . . . 201. .

Overriding alphabetical sorting with ahidden column . . . . . . . . . . . . . . . 204. .

Customizing which column links to Web documents . . . . . . . . . . . . . . 205. .

Adding pass-thru HTML to a column . . 205. .

Using a column to switch to another view . . . . . . . . . . . . . . . . 205. .

Generating column totals, averages, and percents . . . . . . . . . . . . . . . . . 206. .

Table of view, row, and column styles . 207. .

Using HTML formatting for views and columns . . . . . . . . . . . . . . . . . 210. .

Default views . . . . . . . . . . . . . . . . . . . . . 210. .

Defining what users see when they open views . . . . . . . . . . . . . . . . . . 210. .

Contents v

Formulas that look for values incolumns and views . . . . . . . . . . . 211. .

Indenting response documents . . . . . . . 213. .

Formulas for response columns . . . . . . . 214. .

Displaying views in Web applications . . . . . . . . . . . . . 215. .

View applet . . . . . . . . . . . . . . . . . . . . . . 216. .

Creating an embedded view orembedded folder pane . . . . . . . . . 218. .

Show single category in embedded views . . . . . . . . . . . . . 220. .

Setting line counts in embedded views . . . . . . . . . . . . . 221. .

Hiding a view . . . . . . . . . . . . . . . . . . . . 221. .

Identifying unread documents . . . . . . . 222. .

Formatting date and time columns . . . . . . . . . . . . . . . . 223. .

Displaying numbers in columns . . . . . . 224. .

Refreshing view indexes . . . . . . . . . . . . 225. .

Designing folders . . . . . . . . . . . . . . . . . 227. .

Designing a form as a view or navigator template . . . . . . . . . . . . 228. .

9 Designing Navigators . . . . . 229.Navigators . . . . . . . . . . . . . . . . . . . . . . . 229. .

Creating a navigator . . . . . . . . . . . . . . . 230. .

Adding graphic objects to navigators . . 231. .

Adding and enhancing graphics in a navigator . . . . . . . . . . . . . . . . 232. .

Adding text to and highlighting anavigator object . . . . . . . . . . . . . . 233. .

Adding hotspots to navigators . . . . . 234. .

Automating navigators . . . . . . . . . . . . . 234. .

Navigators, imagemaps, and outlines . . 238. .

Displaying a navigator when users opena database . . . . . . . . . . . . . . . . . . 239. .

Hiding navigators . . . . . . . . . . . . . . . . . 239. .

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

Overriding an embedded navigatorwith a navigator template . . . . . . 241. .

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

Testing navigators . . . . . . . . . . . . . . . . . 242. .

10 Automation in Applications . . . . . . . . . . . . . 245.Automation . . . . . . . . . . . . . . . . . . . . . . 245. .

Actions . . . . . . . . . . . . . . . . . . . . . . . . . 246. .

Hotspots . . . . . . . . . . . . . . . . . . . . . . . . 247. .

Agents . . . . . . . . . . . . . . . . . . . . . . . . . . 248. .

Events . . . . . . . . . . . . . . . . . . . . . . . . . . 249. .

Creating an unshared form action orview action . . . . . . . . . . . . . . . . . . 253. .

Action bar . . . . . . . . . . . . . . . . . . . . . . . 257. .

Creating and inserting shared actions . . 258. .

Creating a link . . . . . . . . . . . . . . . . . . . . 260. .

Creating a button . . . . . . . . . . . . . . . . . . 261. .

Creating a text pop-up . . . . . . . . . . . . . . 262. .

Creating a formula pop-up . . . . . . . . . . 263. .

Creating an action hotspot . . . . . . . . . . . 265. .

Creating a program for an event . . . . . . 266. .

Building an agent . . . . . . . . . . . . . . . . . 267. .

Options for running agents . . . . . . . . . . 269. .

Selecting where to run a scheduled agent . . . . . . . . . . . . . 271. .

Examples of agents to run beforeWeb users open or savedocuments . . . . . . . . . . . . . . . . . . 272. .

Setting up agent security . . . . . . . . . . . . 273. .

vi Application Development with Domino Designer

Troubleshooting agents . . . . . . . . . . . . . 277. .

Simulating the running of an agent . 278. .

Agent Log . . . . . . . . . . . . . . . . . . . . . 279. .

Notes server console commands . . . . 280. .

Agent Manager debugging information . . . . . . . . 282. .

NotesLog Class . . . . . . . . . . . . . . . . . 283. .

AgentRunner . . . . . . . . . . . . . . . . . . 284. .

Simple actions for automation components . . . . . . . . 287. .

LotusScript for automation components . . . . . . . . . . . . . . . . . 291. .

Restricted LotusScript and Java agent operations . . . . . . . . . . . . . . 292. .

Formulas for automation components . . 294. .

JavaScript for automation components . 295. .

Table of supported JavaScript objectsfor automated components . . . . . 296. .

Importing Java programs . . . . . . . . . . . 299. .

Creating Java programs for agents . . . . 299. .

Actions and agents names . . . . . . . . . . . 300. .

Hiding automated components . . . . . . . 302. .

11 Including Java Applets in Applications . . . . . . . . . . . . 303.Java applets overview . . . . . . . . . . . . . . 303. .

Enabling Java applets . . . . . . . . . . . . . . 304. .

Importing an applet . . . . . . . . . . . . . 305. .

Linking to an applet on the Web . . . . 306. .

Setting applet parameters . . . . . . . . . . . 307. .

Setting applet parameters, attributes,and properties . . . . . . . . . . . . . . . 308. .

Setting HTML attributes . . . . . . . . . . 309. .

Setting Alternate HTML attributes . . 309. .

Setting properties . . . . . . . . . . . . . . . 310. .

Setting up shared applet resources . . 312. .

Selecting, running, deleting, and copying applets . . . . . . . . . . . . . . 313. .

Refreshing and exporting applet files . . . . . . . . . . . . . . . . . . 314. .

Setting security for applets . . . . . . . . 314. .

Saving applet data . . . . . . . . . . . . . . 317. .

Tips and troubleshooting for Java applets . . . . . . . . . . . . . . . . . 320. .

12 Including OLE Objects in Applications . . . . . . . . . . . . 325.Designing applications using OLE . . . . 325. .

Linking and embedding objects in forms 327. .

Adding OLE custom controls to a form . . . . . . . . . . . . . . . . . . . . . . 328. .

Modifying a form to size anembedded object . . . . . . . . . . . . . 329. .

Modifying a form so that it sizes anOLE custom control or JavaBean . 330. .

Modifying a form to run a customcontrol or JavaBean in Read mode 331. .

Letting documents update objectscreated by forms . . . . . . . . . . . . . 331. .

Launching objects automatically . . . . . . 331. .

Designing a form that launches anobject automatically . . . . . . . . . . . 333. .

Designing a form that launches anew object automatically . . . . . . . 334. .

Launching an object in-place orout-of-place . . . . . . . . . . . . . . . . . 335. .

Specifying the event that causes anobject to autolaunch . . . . . . . . . . 336. .

Designing a form for documents thatopen as modal dialog boxes . . . . . 337. .

Designing a form to hide the Notes document . . . . . . . . . . . . . . 337. .

Hiding an embedded object in a document . . . . . . . . . . . . . . . . . 339. .

Contents vii

Publishing actions . . . . . . . . . . . . . . . . . 340. .

Exchanging data using Notes/FX . . . . . 342. .

Preparing a form to exchange data . . . . 343. .

13 Restricting Access to and Securing Parts of an Application . . . . . . . . . . . . . 347.Security in an application . . . . . . . . . . . 347. .

Controlling access to a database during design . . . . . . . . . . . . . . . . 349. .

Enforcing encrypted Web transactionsusing SSL . . . . . . . . . . . . . . . . . . . 350. .

Restricting access to documents . . . . . . 351. .

Restricting who can see a view or folder 351. .

Restricting who can update thecontents of a folder . . . . . . . . . . . . 353. .

Restricting access to all documentscreated from a form . . . . . . . . . . . 353. .

Restricting who can create or read alldocuments from a form . . . . . . . . 354. .

Preventing printing, forwarding, andcopying of documents . . . . . . . . . 355. .

Using a Readers field to restrict accessto specific documents . . . . . . . . . . 355. .

Using an Authors field to restrict whocan edit specific documents . . . . . 356. .

Restricting who can read or edit specific documents . . . . . . . . . . . . 356. .

Tracking who edits a document . . . . . . 359. .

Restricting authors from changing fieldsin existing documents . . . . . . . . . 360. .

Creating pages, forms, outlines, views,and agents for public access . . . . . 360. .

Encrypting documents in Notes applications . . . . . . . . . . . . 361. .

Encrypting documents . . . . . . . . . . . 363. .

Creating a secret encryption key . . . . . . . . . . . . . . . 364. .

Encrypting documents automatically . . . . . . . . . . . . . . . . 365. .

Creating a field that generates a listof secret encryption keys . . . . . . . 366. .

Restricting who can edit a section . . . . . 368. .

Restricting who can access a section of a document . . . . . . . . . . . . . . . . . 369. .

Attaching electronic signatures todocuments and sections in Notes applications . . . . . . . . . . . . 371. .

How Designer stores and verifieselectronic signatures in Notes applications . . . . . . . . . . . . 372. .

14 Completing an Application and ManagingDesign Changes . . . . . . . . . . . 375.Completing an application . . . . . . . . . . 375. .

Creating a database icon for a Notes application . . . . . . . . . . . . . 375. .

Providing online help for an application 377. .

Creating About and Usingdocuments for a database . . . . . . . 377. .

Creating context-sensitive help for an application . . . . . . . . . . . . . . . 379. .

Writing help for fields . . . . . . . . . . . 380. .

Creating and displaying moredetailed application help . . . . . . . 381. .

Specifying the Web site home page inthe Server document . . . . . . . . . . 382. .

Restricting design changes . . . . . . . . . . 383. .

Checking the application design before rollout . . . . . . . . . . . . . . . . 383. .

Checking form design . . . . . . . . . . . . . . 384. .

Checking field design . . . . . . . . . . . . . . 385. .

Checking view design . . . . . . . . . . . . . 386. .

Making a design copy of a completed application . . . . . . . . . 388. .

viii Application Development with Domino Designer

Pilot testing an application . . . . . . . . . . 389. .

Renaming a database . . . . . . . . . . . . . . . 391. .

Renaming design elements . . . . . . . . 391. .

Design synopsis . . . . . . . . . . . . . . . . . . . 391. .

Updating documents after redesigning a form . . . . . . . . . . . . . . . . . . . . . . 393. .

Checking field values in a document . . . 394. .

Using agents to update documentsaffected by form changes . . . . . . . 395. .

Templates . . . . . . . . . . . . . . . . . . . . . . . 397. .

Creating templates . . . . . . . . . . . . . . . . . 398. .

Creating a design library template . . 401. .

Linking a database to a template . . . 402. .

Linking individual design elementsto a template . . . . . . . . . . . . . . . . 402. .

Making and distributing design changes . . . . . . . . . . . . . . . 403. .

Refreshing a design . . . . . . . . . . . . . . . . 404. .

Replacing a design . . . . . . . . . . . . . . . . . 406. .

Design changes and replication . . . . . . . 407. .

Preventing design changes . . . . . . . . . . 408. .

Hiding the design of a database . . . . . . 409. .

Hiding design elements . . . . . . . . . . . . . 411. .

15 Creating a Workflow Application . . . . . . . 413.Workflow Overview . . . . . . . . . . . . . . . 413. .

Planning workflow . . . . . . . . . . . . . . . . 414. .

Features that support automatic mailing 415. .

Enabling users to view documents . . . . 416. .

Mailing features and Web applications . 417. .

Fields that control mailing options . . . . 417. .

Displaying the MailSend dialog box . . . 421. .

Creating a database that receives mailings . . . . . . . . . . . . . 421. .

Using an agent to send automatic replies . . . . . . . . . . . . . 422. .

Using an agent to mail notices . . . . . 422. .

Using an agent to sendannouncements . . . . . . . . . . . . . . 423. .

16 Connecting to Enterprise Data . . . . . . . . . . . . 425.Accessing data in enterprise

applications . . . . . . . . . . . . . . . . . 425. .

Using ODBC to access relational databases . . . . . . . . . . . 428. .

Registering data sources for ODBC . . . . . . . . . . . . . . . . . . . 429. .

Writing formulas and scripts toaccess relational databases . . . . . . 430. .

17 Including Java Servlets in Web Applications . . . . . . . . 431.Overview of Java servlets . . . . . . . . . . . 431. .

Comparing agents, servlets, and CGI programs . . . . . . . . . . . . . . . 432. .

Running servlets in Domino . . . . . . . . . 434. .

Appendix A Domino Designer Templates . . . . . . . . 441.

Appendix B Importing to and Exporting from Views . . . 443.

Appendix C DevelopingApplications Using MAPI . . . . 455.

Appendix D Features to Avoid Using in WebApplications . . . . . . . . . . . . . . . 463.

Appendix E Programming a Web Site . . . . . . . . . . . . . . . . 475.

Index . . . . . . . . . . . . . . . . . . . . . 503.

Contents ix

Preface

This guide describes how to create all the design elements used in buildingDomino™ applications, how to share information with other applications,and how to customize applications.

This guide is intended for developers who are creating applications withDomino™ Designer.™

Structure of this guideThis guide consists of 17 chapters and 5 appendixes:

Chapter 1, “Introduction to Domino Designer,” provides an overview of theDesigner user interface and a brief introduction to key product features anddesign elements.

Chapter 2, “Creating an Application,” provides an overview of creatingapplications along with some design considerations.

Chapter 3, “Designing Outlines,” shows you how to create and format anoutline, and how to embed an outline on a form or page to use as anavigational structure for your application.

Chapter 4, “Designing Pages,” describes designing pages for Web andNotes applications.

Chapter 5, “Designing Forms,” describes designing forms and includesinformation on designing some special types of forms.

Chapter 6, “Designing Fields,” describes how to create fields to collect andstore specific types of information.

Chapter 7, “Designing Framesets,” introduces frames and framesets, whichcan add structure to your application.

Chapter 8, “Designing Views,” describes how to design views, which helpusers find the documents they want and also serve as summaries of thedatabase contents.

Chapter 9, “Designing Navigators,” explains how to create graphicalnavigators that help users find documents and use the database.

Chapter 10, “Automation in Applications,” explains how to add automationfeatures to an application to make it easier to perform tasks in thebackground.

xi

Chapter 11, “Including Java Applets in Applications,” describes addingJava applets to forms, documents, and pages.

Chapter 12, “Including OLE Objects in Applications,” illustrates ways todesign applications that use OLE technology to integrate data from otherapplications.

Chapter 13, “Restricting Access to and Securing Parts of an Application,”briefly describes Designer features for limiting access to parts of anapplication.

Chapter 14, “Completing an Application and Managing Design Changes,”describes how to document an application and how to test it beforedeployment, as well as how to make, control, and distribute design changesto applications that are already in use.

Chapter 15, “Creating a Workflow Application,” describes how to create aworkflow application by using automatic mailing features.

Chapter 16, “Connecting to Enterprise Data,” briefly describes tools andtechniques for connecting a Designer application to enterprise data.

Chapter 17, “Including Java Servlets in Web Applications,” describescreating and running Java servlets on a Domino Web server.

Appendix A, “Domino Designer Templates,” lists the templates availablewith Domino Designer that are specifically intended for use by applicationdevelopers.

Appendix B, “Importing to and Exporting from Views,” provides tips andrestrictions on moving data to and from views.

Appendix C, “Developing Applications Using MAPI,” providesinformation on the available support for accessing Notes mail files.

Appendix D, “Features to Avoid Using in a Web Applications,” identifiesfeatures that are not applicable to Web browsers or are not yet supportedfor them.

Appendix E, “Programming a Web Site,” contains information about usingDomino URL commands for programming related to Web applications,such as formulas, Java, JavaScript, Perl and CGI scripting, and Visual Basicscript.

xii Application Development with Domino Designer

Structure of Notes and Domino documentationDocumentation for Notes™ and Domino is provided online in threedatabases available from the Help menu:

Notes 5 Client Help

Domino 5 Administration Help

Domino 5 Designer Help

In addition, the Administration and Designer documentation is available asprinted books. In Notes, select File - Other Help to see a table of all theavailable documentation. You can order books from the Lotus Web site at:www.lotus.com/store.

Documentation for the Notes ClientIn addition to the online Help, the printed book Notes Step by Step providesa tutorial for beginning Notes users.

Documentation for Domino AdministrationThe following table shows the printed books that comprise the Domino Administration documentation set. The information in these books is alsofound in the Domino 5 Administration Help online database.

Moving to Notes andDomino Release 5

Describes how to upgrade existing Dominoservers and Notes clients to Release 5. Alsodescribes how to move users to Domino fromother messaging systems.

Configuring the DominoNetwork

Explains how to configure a specific networkto work with Domino. Also illustrates how torun Notes using multiple network protocolsand individual protocols, such as AppleTalk,Banyan VINES, NetBIOS, Novell SPX(NetWare), and TCP/IP.

Administering the DominoSystem, Volumes 1 and 2

Describes how to set up and manage servers,users, server connections, mail, replication,security, calendars and scheduling, Webservers, NNTP services, billing, and systemmonitoring. Describes how to troubleshootsystem problems.

Administering DominoClusters

Describes how to set up, manage, andtroubleshoot Domino clusters.

Preface xiii

Managing DominoDatabases

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

Documentation for Domino DesignerThe following table shows the printed books that comprise the DominoDesigner documentation set. The information in these books is also found inthe Domino 5 Designer Help online database.

Application Developmentwith Domino Designer

Explains how to create all the design elementsused in building Domino applications, how toshare information with other applications, andhow to customize applications.

Domino DesignerProgramming Guide Volume 1: FormulaLanguage

Introduces programming in Domino Designerand describes the formula language, the@functions, and the @commands.

Domino DesignerProgramming Guide Volume 2: LotusScriptClasses

Provides reference information on theLotusScript® classes, which provide access todatabases and other Domino structures.

Domino DesignerProgramming GuideVolume 3: Java Classes

Provides reference information on the Javaclasses, which provide access to databases andother Domino structures.

LotusScript LanguageGuide

Describes the basic building blocks ofLotusScript, how to use the language to createapplications, an overview of the LotusScriptprogramming language, and a comprehensivelist of language elements.

Domino EnterpriseIntegration Guide

Provides information on how to set up DominoConnectors, how to utilize Domino EnterpriseConnection Services (DECS) to access enterprisedata in real-time, and reference material forprogramming with the LotusScript Extensionfor Domino Connectors.

Managing DominoDatabases

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

xiv Application Development with Domino Designer

Step by Step

Setting up a Domino ServerMoving to Notes and Domino Release 5Configuring the Domino NetworkAdministering Domino ClustersAdministering the Domino System, Volume 1Administering the Domino System, Volume 2

Application Development with Domino DesignerDomino Designer Templates GuideDomino Designer Programming Guide, Volume 1: Formula LanguageDomino Designer Programming Guide, Volume 2: LotusScript ClassesDomino Designer Programming Guide, Volume 3: Java ClassesLotusScript Language GuideDomino Enterprise Integration Guide

Managing Domino Databases

AdministrationHelp

Release Notes

DesignerHelp

not available in print

Domino ObjectsPosters

NotesHelp*

*

*

**

** print only

Preface xv

Chapter 1 Introduction to Domino Designer

Welcome to Domino Designer. Designer is an integrated applicationdevelopment environment which lets developers and Web site designerscreate, manage, and deploy secure, interactive applications for the DominoServer.

To see what’s new in Release 5, look for this icon. If you are new toDesigner or just getting to know Release 5, this brief tour will introduce you to some of the features in Release 5.

Overview — applications and databases

ApplicationsDomino applications let people share, collect, track, and organizeinformation, using Lotus Notes® or the Web. Domino applications cancover a wide range of business solutions, including:

Workflow — Applications that route information.

Tracking — Applications that monitor processes, projects, performance,or tasks.

Collaboration — Applications that create a forum for discussion andcollaboration.

Data Integration — Applications that integrate with relationaldatabases and transactional systems.

Personalization — Applications that produce dynamic content basedon, for example, user name, user profile, access rights, or time of day.

Globalization — Applications that use Domino Global Workbench toproduce global sites.

Every Domino application starts with a Domino database. All Dominoapplications contain one or more Domino databases.

1

DatabasesA database is the container for the data, logic, and design elements in yourapplication. Design elements are building blocks you use to create yourapplication. Design elements include:

Pages

Forms

Outlines

Navigators

Views

Folders

Framesets

Shared Resources

Agents

Creating a databaseThere are three ways to create a database:

Using a template.

The fastest way to create a database is to use one of the Dominotemplates included with Designer R5. Designer includes templates forcreating a variety of applications. Applications created using one of theDesigner templates can be used as is or customized.

To decide if there is a template that is right for you, see the Table ofDomino Designer templates.

Copying an existing database.

If you have access to a database that already has all the elements youare looking for, you can copy the design and create a new database withthe same features. Once you have created the database, you cancustomize it to meet your company’s needs.

Starting from scratch.

If the database you need is unique, the best method for you is to startfrom scratch. When you create a database from scratch, you start with ablank or empty database and create all of the design elements.

In order to begin creating your application, you need to start Designer.

2 Application Development with Domino Designer

Starting Designer

There are two ways to start Designer after starting the Notes client:

From the Designer Icon

From a database in the Notes client

To start Designer from the Notes client Designer icon1. Start the Notes client.

2. Click the Designer icon on the bookmark bar on the left of thebookmark pane.

After you start Designer you can open an existing database or start a newone. Once you open a database, either a new or existing one, you will be inthe Designer Workspace.

If you already have a database to work with, you can start Designer directlyfrom that database.

To start Designer from an open database in the Notes clientYou must have designer or manager access to the database in the ACL.

1. Open the database.

2. Choose View - Design.

or

1. Right-click the database icon on the bookmark bar.

2. Choose Open in Designer.

Chapter 1: Introduction to Domino Designer 3

Exploring Designer

Building a great application requires the right tools. You can think ofDesigner as your workshop — it contains all the tools you need to build a great application. Before you get started building, we’ll explore the work area.

Item Purpose

Menu bar Presents context-sensitive menus of Designer commands.

Preview buttons Launches the browser of your choice to preview your work.

Tabbed windows Navigates among the open windows on your workspace.

Design action buttons Perform actions such as creating elements, saving, closing.

Properties box button Opens the properties box for the active design element.

Design pane Contains the Design bookmarks icons and the Design list.

Design bookmarks Opens lists of bookmarked applications.

Design list Takes you to Work pane of a design element or resource.

Work pane Lists everything in the database for the currently selecteddesign element in top level view. Once an element isopened, becomes the Work area for that element.

Menu bar

Design bookmarks

Design list

Design pane

Preview buttons

Properties box

button

Work pane

Design action buttons

Tabbed windows


When you open a design element such as a page or form, you will be in thework area for that design element. In addition to items in the DesignerWorkspace, the Programmer’s pane appears.

Item Purpose

Reference tab The Reference tab of the Info List replaces the R4.x LotusScriptbrowser window and is language-sensitive. The contents of theReference 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 inLotusScript, the window contains LotusScript information. If youare editing in JaveScript, the window contains information aboutthe Document Object Model. If you are editing in Java, thewindow contains Java-related information.

Objects tab The Objects tab of the Info List lets you navigate between objectsand events in the Programmer’s pane. To work on an object,select it to expand its list of properties and events. If you select aproperty or event, the script area of the Programmer’s panechanges to show the code that describes it. Events and propertiesthat are already programmed appear in a darker color.

Script area Enter formulas in the Script area. Formulas can be written inFormula language, LotusScript, JavaScript, or Simple Actions.

Objects tab

Script area

Reference tab


Properties boxesProperties boxes are tools for working the various pieces of yourapplication. With them you can select or modify settings for the elementyou are working with. Properties boxes have tabbed panes, and each panegives you access to different attributes or options. In most windows, right-clicking will open up the Properties box for that design element. You canalso choose Design - <element> Properties from the menu.

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

Displaying, collecting, and storing information — pages, forms,documents, and fields

How you display, collect, and store information is an important part of anyapplication. The design elements you use to accomplish these tasks arepages, forms and documents, and fields.

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


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

Pages can be used anytime you are displaying information to the user.Pages can contain:

Text

Tables

Graphics

Applets

Embedded objects such as navigators

Links

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

For more information on pages, see “Designing Pages.”

Forms and DocumentsForms, 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 forcreating and displaying documents. Documents are the elements that storedata in the database.

When you create a form in Designer, you can choose to have a user openthe form in the Notes client from the Create menu. On the Web, youprovide the user a button or action that opens the form. When the user fillsout the information and saves it, the information is saved as a document.When a user opens the document, the document uses the form as a templateto provide the structure for displaying the data.

For more information on forms and documents, see “Designing Forms.”


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

You can create fields in the following data types:

Text

Date/Time

Number

Dialog List

Checkbox

Radio button

Rich Text

Authors

Names

Readers

Password

Formula

You decide if a field is editable — that is, populated by user input — orcalculated — that is, based on formulas. You can also program fields toretrieve data from other Domino applications or from external sources. Youcan even create shared fields, which can be used in many forms within thesame database. The information collected in fields is stored in documents.

For more information, see “Designing Fields.”


Organizing your data — views and folders

Views and folders organize the documents in your database.

ViewsA view is a sorted or categorized list of documents. Views are the entrypoint to the data stored in a database. Every database must have at leastone view, although most databases have more than one view. Views selectthe documents they display programatically. You can create a view thatshows all of the documents in your database or only some of thedocuments, based on a formula. Views can sort the documents they displayby a field on the form, such as date, category, or author. You can createviews that are hidden from users but organize your data so that otherapplications can retrieve the information from the documents. Views canhave multiple columns that display any of the information contained in thedocument.

For more information, see “Designing Views.”

FoldersA folder is a container that stores documents. Folders have the same designelements 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 adocument selection formula that collects and displays documentsautomatically. A folder remains empty until users or programs adddocuments to the folder.

For more information on folders, see Notes 5 Client Help.


Creating navigation — outlines and navigators

Every application needs to include a way to navigate from one place toanother. When you create a database from scratch, Designer provides adefault navigation structure called the Folder pane or Navigation pane. TheFolder pane displays all the shared views and folders in the database. TheFolder pane displays on the left pane of the Notes client and on the top leftof a browser window. You can choose to use this navigation structure ordesign 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 representsa key piece of the application. An outline can include background graphics,custom icons, links, or actions. When the outline is embedded on a page orform, users can click on the outline entries, which will take them where youwant them to go. The process of creating a navigation structure with anoutline involves three steps:

Create a new or default outline and create an outline entry for eachpiece of the application you want to include in the navigation structureor site map.

Embed your outline on a form or page.

Format the display of the embedded outline. You can include the pageor form that the outline is embedded on in a frameset if you choose.

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

For more information, see “Designing Outlines.”


NavigatorsNavigators are graphical roadmaps that direct users to specific parts of adatabase. They let users find documents or take actions without having toopen views. Navigators are like imagemaps. You can create hotspots on agraphic that take the users to links within or outside of your application.You can embed navigators on forms or pages. Navigators can take the placeof the folder pane or work in conjunction with it.

For more information on navigators, see “Designing Navigators.”

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

Designer lets you:

Create an effective multi-paned user interface for your applications

Control frame attributes such as size, scrolling, border colors andwidth, and frame spacing


Determine frame source content at runtime

Create programmable links that are maintained automatically

Set a frameset to launch automatically when a database, form, orpage opens

For more information on framesets, see “Designing Framesets.”

Adding automation — actions, hotspots, and agents

Adding automation to an application can speed up repetitive tasks, routedocuments, update information, perform calculations, run programs, andcheck for errors.

You add automated components to the design elements in a Dominoapplication such as a database, a view, a form, or a document.

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

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

Agents Agents are programs that perform a series of automated tasks according toa set schedule or at the request of a user. An agent consists of threecomponents: when it acts (the trigger), what documents it acts on (thesearch), and what it does (the action). Use agents to set up user-activatedtasks, or background tasks, in any part of a Domino application. Agents canbe simple, such as moving documents to a folder, or complex, using Javaprograms to run multiple automated tasks at scheduled times. Agents arestored with databases, but you can use them to run automated tasks forviews, documents, fields, and databases.

For more information, see Adding Automation to Applications.


Getting database information — design synopsis

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

For more information, see “Design synopsis.”

It’s time to build!This completes the Designer tour. It’s time for you to go exploring on yourown. If you haven’t done so already, and you’d like more help getting toknow your way around the Designer tools, you can go through theDesigner Guided Tour. Choose Help - Guided Tour to start it. Rememberwhat you build with your tools can be as simple or as complex as you want.The Designer tools are at your disposal.


Chapter 2Creating an Application

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

Domino databases

All Domino applications begin with a Domino database. Domino databasesare the containers for your application. Databases hold the data, logic, anddesign elements for your application. Your Domino application can bemade up of one or more Domino databases.

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

DataDocuments

Fields

Design Elements:Pages, Forms, Views ...

Field Type:Rich Text

Field Name:Body

Data:'Dear John ...'

DATABASE

DOCUMENT

FIELD

}

}}

15

Creating databases

There are three ways to create a new database:

Using a template

Copying an existing database

Starting from scratch

Creating a database from a template

Designer comes with a collection of templates that you can use to createapplications quickly. A template is a file that contains the structure for thedatabase — that is, pages, forms, and views — but does not containdocuments. For example, to design a discussion database, use theDiscussion template (DISCSW50.NTF), which contains forms that trackdiscussion threads in a hierarchy, as well as views that display the entriesby date, author, or category. Designer templates have .ntf as their fileextension.

See “Domino Designer Templates” for a complete list of DesignerTemplates.

Customizing a TemplateYou can use a template as is or customize it for your organization. Thetemplates that ship with Designer can be used as master templates. Whatmakes a template a master template is that changes made to a mastertemplate can be passed along to all databases created from that template.Inheriting design changes from a master template can be initiated by theend user or by the Domino server, which runs a nightly Design task. Youcan disable this feature when you create your database by deselecting“Inherit design from template.” For more information on customizing atemplate, see “Completing an application and managing design changes.”

To create a new database from a templateAfter creating a database from a template, you may want to make changesto the database. Keep in mind that if you have selected “Inherit design fromtemplate,” changes you make to a database can be overwritten nightly bythe Domino server design task or by refreshing the design of the database.If you plan to make design changes to the database and want to avoid thepossibility 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 thefollowing:

Leave Local selected to store the new database on your hard disk.

Select or enter a server name to store the new database on a server.This allows multiple people to work on the database design.

2. In the Title field, enter a title for the new database. The Title can have amaximum of 32 characters.

Note As you type a title, Designer adds a name to the File Name field.You can accept this database file name or change it. Database file namescan be up to 8 characters and end with the file extension .nsf. If youplan to use the database you are creating as a template for otherdatabases, use the file extension .ntf.

3. Select a template from the list. To display additional templates, do onefollowing:

Click “Show advanced templates” and select a template from the list.

Click “Template Server” to use templates that reside on a server.

4. (Optional) Click Encryption, select “Locally encrypt this databaseusing:,” select an encryption type, and click OK. For information onencrypting a database, see “Notes and Domino encryption” inManaging Domino Databases.

5. (Optional) If you are creating a database that will be on a DominoRelease 4.x server, click Size limit and select a size (in gigabytes), andclick OK.

6. (Optional) Click the Advanced tab and select the options that you wantapplied to your database. Click OK.

For a description of the advanced options, see Managing Domino Databases.

7. Click OK.

8. (Optional) Choose File - Database - Properties, click the Design tab, anddeselect “Inherit design from template.” This will prevent the newdatabase from inheriting design changes from the master templatewhose design the database is based on.

Chapter 2: Creating an Application 17

Copying an existing Domino database

If you have found an application that contains all or most of thefunctionality you are looking for, you can copy the design of the databaseand use it as the basis for a new application. Before you copy the design of adatabase, check its Database Properties. If “No design information isavailable” is shown on the Database Properties box, the designer hashidden the design of the database, and you will never be able to modify thedesign of the new database.

If you copy the design of an existing database, keep in mind that thesettings for the full-text index are copied as part of the design. When youcomplete the new application, be sure to ask the database manager to createa new full-text index. For information on creating a full-text index for adatabase copy, see “Setting up and managing full text indexes” in ManagingDomino Databases.

You can use the new database as is, or you can modify it. Once you modifya database that you copied, protect your customized views, forms,subforms, navigators, shared fields, or agents. For more information onprotecting design elements, see “Preventing design changes.”

To create a new database by copying an existing database1. Open the database you want to copy.

2. Choose File - Database - New Copy.

3. In the server field do one of the following:

Leave Local selected to store the new database on your workstationhard disk.


4. (Optional) In the Title field, enter a title for the new database. The Titlecan have a maximum of 32 characters.

Note When you copy a database, Designer automatically give the newdatabase the same title and file name as the originally database. Youcan accept the database title and file name or change it. Databasefilenames can be up to 8 characters and end with the file extension .nsf.If you plan to use the database you are creating as a template, use thefile extension .ntf rather than .nsf.




7. Select “Database design only” so that the database’s documents will notbe copied to your new database.

8. Deselect “Access Control List” so that the original database’s accesscontrol list will not be copied to your new database.

9. Click OK.

10. (Optional) Choose File - Database - Properties, click the Design tab, anddeselect “Inherit design from template.” This will prevent the newdatabase from inheriting design changes from the template whosedesign the database is based on.

To copy an individual design elementIn addition to copying the entire design of a database, you can copyindividual design elements. If there is a form, view, or other design elementyou would like in your database, copy it from the original database ortemplate and paste it into your database.

1. Open the database or template containing the design element you wantto copy.

2. From the Work pane, select the element or elements that you want tocopy, such as a form or a view, and choose Edit - Copy.

To select multiple elements, hold down the CTRL key while you areselecting the elements you want to copy.

3. Open the database where you want to paste the element or elements.

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

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

To protect an individual design element1. 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.”


Starting a database from scratch

If you need a unique application, start from scratch. To do this, begin bycreating a blank database. A blank database contains no design elementssuch as pages or forms. Blank databases have one default view. You mustcreate all of the elements you need for the application. You begin bycreating a database based on the -Blank- template.

To create a new database from scratchTo design a database from scratch, you must first create an empty database.Then design the forms, fields, views, and other design elements you willneed for the application.

1. Choose File - Database - New.

2. In the Server field do one of the following:

Leave Local selected to store the new database on your workstationhard disk.


3. In the Title field, enter a title for the new database. The title can have amaximum of 32 characters.

Note As you type a title, Designer adds a name to the File Name field.You can accept this database file name or change it. Database file namescan be up to 8 characters and end with the file extension .nsf. If youplan to use the database you are creating as a template, use the fileextension .ntf rather than .nsf.



6. Select -Blank- as the template.

7. Click OK.


Tips for designing Web applications

When you design a database that is intended to be viewed on the Web, keepin mind that databases viewed from a Web browser may look somewhatdifferent than they do when viewed from the Notes client. Each browserrenders design elements with slight differences. Be sure to preview yourdatabase through each browser that will access it so that you can makeadjustments to your design. Also, for databases that will be accessedthrough Web browsers, it is best to:

Make sure the database is in the Domino Data directory or asubdirectory of the Data directory.

Add form actions such as Create, Edit, and Save. For more information,see “Actions.”

Hide features that aren’t supported on the Web. See “Features to AvoidUsing in Web Applications” for a detailed list.

Select the database property “Web access: Use JavaScript whengenerating pages” to allow you to use additional @commands andcreate multiple form buttons.

Change from the Lotus color palette to a Web color palette to providegreater color fidelity on the Web. To change palettes, choose File -Preferences - User Preferences. Check “Use Web Palette” on theAdvanced options list of the Basics page.

Set views, outline controls, action bars, and rich text fields to bedisplayed as applets when viewed with a browser. For moreinformation, see the topic “Domino Applets.”

Check the Access Control List (ACL) setting to make sure it allowsappropriate access for Web users. For more information, see “Setting upthe ACL for a Web database.” in Managing Domino Databases.


Domino Applets

When users run a Domino application from a Web browser, some Dominodesign elements are more effectively presented to Web users using Javainstead of HTML. Domino provides Java applets for these design elementsso that the interface for Web users is closer to the interface for Notes clientusers. You can easily enable the Java applets when you create the designelement.

When you consider whether to use the Java applets or HTML, keep thesepoints in mind:

The applets provide a more interactive interface.

The Domino applets will require download time to the Web user.

The applets use the Java Developer’s Kit (JDK), Release 1.0.2 to supportWeb users with any java-enabled Web browsers. The only fontssupported are typically Courier, Helvetica, and Times.

For a complete description of how the applets work, see the description foreach design element:

Outline applet

The outline applet lets Web users work with outlines embedded in apage or form.

View applet

The view applet lets Web users use many of the Domino view features,including column resizing, multiple document selection, and sectioncollapse/expand without page regeneration.

Action bar applet

The Action bar applet lets users scroll and easily view and selectsub-actions.

Editor applet

The editor applet lets Web users change the font, color, size, and stylefor text in rich text fields.


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. Tochange these properties, you need Designer access or higher in the databaseaccess control list.

To change a database’s properties1. 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 properties1. Open the database.

2. In the Design pane, click the type of design element you’re working on.

3. Open or select the design element from the Work pane.

4. Choose Design - <design element name> Properties to open the Propertiesbox for the selected design element.

5. Change the properties on any of the tabbed pages.

Setting “Use JavaScript when generating pages” for a databaseIf your application will be accessed on the Web, you’ll want to select thedatabase property “Web access: Use JavaScript when generating pages” soyou can use additional @commands and create multiple form buttons. Ifyou are upgrading from Release 4.5, consider the upgrade issues beforedeciding, because the property can cause unexpected behavior in existingactions, buttons, and hotspots.

The “Use JavaScript when generating pages” option is on the DatabaseBasics tab of the Database Properties box. To open the Database Propertiesbox, open or select the database and choose File - Database - DatabaseProperties.


Ramifications for “Use JavaScript when generating pages” for adatabase

Be aware that selecting the “Web access: Use JavaScript when generatingpages” affects formulas and actions, buttons, and hotspots throughout theapplication.

If you select “Use JavaScript” If you don’t select “Use JavaScript”

Documents and navigators display fasterbecause hotspot formulas are notevaluated until users click each hotspot.

Documents and navigators display moreslowly because the hotspot formulas areall evaluated at the display time.

Domino doesn’t generate a Submitbutton automatically. Create a Submitbutton, hotspot, or action whose formulaincludes these commands:

@Command([FileSave]);

@Command([FileCloseWindow])

You can have multiple buttons on a form.

If there are no buttons, Dominoautomatically generates a Submit buttonat the bottom of the form. Domino onlyrecognizes one button on a form. If thereare multiple buttons on the form,Domino recognizes only the first buttonand converts it to a Submit buttonautomatically.

The following commands are supportedon the Web:

@Command([FileCloseWindow]),@Command([FileSave]), and@Command([ViewRefreshFields])

The following commands are notsupported on the Web:

@Command([FileCloseWindow]),@Command([FileSave]), and@Command([ViewRefreshFields])

Domino checks the formulas beforedisplaying pages. Actions that containunsupported @commands or @functionswill not be displayed on the Web.

Upgrade issues for “Use JavaScript when generating pages” for aWeb database

Elements with unsupported formulas that Domino hid automatically inRelease 4.5 may now display if you select the “Use JavaScript” property.

With the property selected, Domino doesn’t check any hotspot or buttonformulas before using JavaScript to generate the page. Web users see allbuttons, actions, and hotspots — even those that contain @commands and@functions that aren’t supported for Web applications.

Revise any formulas that relied on hotspot formulas being evaluated atdisplay time. Make sure these formulas evaluate correctly after the userclicks the hotspot, not before.


Replace Release 4.5 attachment fields with Embedded Element - FileUpload Controls if you set the “Use JavaScript” property. The “UseJavaScript” setting disables @Command([EditInsertFileAttachment])hotspots used to create attachment fields in Release 4.5, because the hotspotis not evaluated when the page is displayed.

The “Use JavaScript” property can cause unexpected results because theURL generation in Release 5.0 is different than it was in Release 4.6.

Check any formulas that rely on accessing a Query_String or Path_Info URLfragment. The URLs will frequently be different. For example, POST URLsthat included ?CreateDocument and ?SaveDocument are no longergenerated in Release 5.0. The new POST URL is a variation of ?OpenFormor ?EditDocument.

Setting database launch propertiesYou can set database properties that control what a user sees when thedatabase opens. For example, you might want all users to start from anapplication home page or a registration page. Or you might display a mainnavigator that leads users to different pieces of the application. You canspecify one option for an application when it runs on a workstation andanother option for the application when it runs on the Web.

When the database opens on the Notes client, you can display:

The database as the user last viewed it

The “About This Database” document for the database

A frameset you specify

A navigator you specify

A navigator you specify in its own window

The first attachment in the “About This Database” document

The first doclink in the “About This Database” document

When the database opens on a Web browser, you can display:

Use the Notes launch option

The “About This Document” document

A frameset you specify

A page you specify

A navigator in its own window

The first doclink in the “About This Database” document

A doclink you specify

The first document in a view


To set the database launch property1. Select or open the database and choose File - Database - Properties.

2. Click the Launch tab.

3. Do one or both of the following:

Choose what to display for a Notes client

Choose what to display for a Web browser

4. (Optional) Choose whether to display the About This Databasedocument when the database opens for the first time and/or when theAbout This Database document is modified.

Setting the database property to launch the first link in the About ThisDatabase document gives users access to information in another applicationfrom a Designer application. For example, to collect spreadsheet data foruse in the application, launch a link to a spreadsheet application so usersimmediately see the spreadsheet when they open the database. Dataentered in the spreadsheet can be used to populate fields in the application.To view the About This Database document, users choose Help - AboutThis Database or close the link or attachment.

If you choose to launch a page, you will need to specify the page. Designergives you a drop-down list of the pages that are available to choose from.

If you choose to launch a doclink:1. Copy the doclink on to the clipboard.

2. Open the Database Properties box.

3. On the Launch tab choose - On Web open launch designated doclink.

4. Click Paste doclink.

To launch a Page from the Notes client1. 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 automaticallyYou can automatically display a preview pane that shows the contents ofthe highlighted document in a database view before the user opens thedocument. This gives users a sense of what is in a database without havingto open and close each document. If you do not display the preview paneautomatically, users choose View - Document Preview to access it.

1. Select or open the database you are designing and choose File -Database - Properties.


3. Click the Preview Pane Default button.

4. Choose a location where the document preview pane will display.

5. Check “Maximize document preview on database open” toautomatically display the preview pane.

Settings for multilingual applicationsIf you are creating an application that will have different language versions,you can select Multilingual Database on the Design tab of the DatabaseProperties box. Once you have enabled the database as a multilingualdatabase you can select the default language and region. This propertyworks in conjunction with the language preference setting on users’browsers. For example, if you have three versions of your database, one inEnglish, one in French, and one in Spanish, and the user’s browser or Notesclient preference is set to Spanish as the default language, the Dominoserver will serve up the Spanish version of the home page. This property isalso available for individual design elements and works in the same way.

Domino Global WorkbenchDomino Designer ships with the Domino Global Workbench, a fullyintegrated translation tool specifically designed to facilitate the translationof Designer applications into a variety of languages.

If you decide to use Domino Global WorkBench, a number of design-stagetasks will make the localization process simpler. For example, you shoulduse aliases for the names of design elements wherever you can. Use asystem of standard prefixes for the aliases so that they can easily beidentified as text to exclude from translation.

To launch Domino Global Workbench, click the Domino Global Workbenchicon.

For more information see “Preparing Source Databases” in Domino GlobalWorkBench Help.


HTML tag attributes for a Domino serverThe HTML tab appears on many properties boxes. If you are designing anapplication that will be used on the Web and are using HTML 4.0, theHTML tab on the Database Properties box lets you access core attributes,such as Cascading Style Sheet (CSS), easily. Domino incorporates the valuesof these attributes to the HTML that it creates at runtime. When you areusing the HTML tag attributes, remember:

The HTML must be ASCII characters.

Do not include quotation marks when you enter the attributes in thevarious boxes, except for the Other box.

Other needs quotation marks, as shown in the example below.

HTML tag attributesID: used to reference an object using JavaScript. For example, the objectcould beID = ZipCode

Class: used to specify a CSS class for an object. For example, if theobject’s name is ZipCode, the class could be Numeric.CSS styles aredefined in the HTML Head Content event for a form or page.

Style: used to apply a specific CSS styles to an object. For example, if theobject’s name is ZipCode, the class is Numeric, the style could befont-size:10pt, or if you have more then one value, separate them with asemi-colon, for example, font-size:10pt; color:blue.

Title: used to prompt the user to enter a value for the object. Forexample, if the object’s name is ZipCode, the class is Numeric, the styleis Bold, the title could be Enter your Zip Code. The title displaysdifferently on different browsers.

Other: used for additional HTML tag attributes and must be written aspure HTML code. For example, instead of writing ZipCode in theName/ID box, you have to write “ID=ZipCode.”


Hide-when optionsDesigner lets you hide many of the design elements and components of anapplication. If hide options are available, the hide — when tab appears onthe properties box for that element. To set hide-when options, select theelement you want to hide and open the properties box for that element.

1. Click the Hide tab.

2. For basic options, select all situations in the “Hide paragraph whendocument is:” section in which the components don’t need to be seen byusers.

3. For programmer options, select “Hide paragraph if formula is true”and write a formula in the design pane to describe the situations inwhich users don’t need to see the layout region.

You can hide elements, including its text, graphics, and fields, in any ofthese situations.

When users read, hide information that is useful only when users createor edit documents.

When users edit, print, and copy, hide information that is useful whenusers read documents.

If an element is hiddenwhen:

Then:

Previewed forreading

The hidden information isn’t visible when users readdocuments in the document preview pane.

Previewed forediting

The hidden information isn’t visible when users workon documents in Edit mode in the document previewpane.

Opened for reading The hidden information isn’t visible when users opendocuments in Read mode. A layout region that can’t beread can’t be printed either.

Opened for editing The hidden information isn’t visible when users workon documents in Edit mode.

Printed The hidden information isn’t visible on printeddocuments.

Copied to theclipboard

The hidden information isn’t visible when informationis copied to and pasted from the Clipboard. Thissetting doesn’t affect documents copied at the viewlevel.

Hide paragraph ifformula is true

A formula determines the circumstances in whichinformation is hidden.


Enabling subscriptionsSubscriptions work in conjunction with the Headlines database. TheHeadlines database enables users to stay informed of current events bothwithin their company and on the Web. The headlines database lets userssubscribe to databases that are of interest to them and then receivenotification when a posting meets their subscription profile. To design adatabase that can be subscribed to by users:

The database must reside on a server that allows subscriptionmonitoring. The Domino administrator must enable subscriptions onthe server document. See Administering the Domino System for moreinformation on enabling subscriptions at the server level.

The database must enable headline monitoring. This is enabled on theAdvanced tab of the Database Properties box. It is enabled by default.For more information about performance issues with headlinemonitoring, see “Prevent headline monitoring” in Managing DominoDatabases.

The database must contain a subscription form. You can design oneyourself or copy the subscription form from the headlines.nsf databaseinstalled with the Notes client. To copy the subscription form from theheadlines database to your database, see “To copy and individualdesign element.” If you are creating a subscription form from scratch,you must use a formula field. For more information, see the topic“Formula fields.”

Reducing database maintenance with shared resourcesEach database can contain its own library of shared resources. Sharedresources let you reference a resource repeatedly throughout an application,while only having to maintain in one standard place. For example, if youuse your company logo in many places throughout your application andthe design of your logo changes, you need only change it once, in the imageresource, and the change will be implemented everywhere that image isreferenced.

You can create the following resources:

Image resources

Images resources are graphic files that can be used throughout yourapplication. Images resources can be gif, jpeg, or bmp format. They aresaved in Designer as gif or jpeg. An image resource can be used asgraphics or icons on pages, forms, action buttons, outline entries, and asbackground images on forms, documents, pages, table cells, and actionbuttons.


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 onceand reuse it. When you define a field as a shared field, Designerdisplays the field with a dark border and adds the field name to a list ofshared fields available for use in a database. For more information, seethe topic “Creating shared fields.”

Subforms

A subform is a collection of fields you plan to use in more than oneform. For example, you might create a corporate letterhead in asubform and then use the subform on a variety of business forms. Formore information, see the topic “Subforms.”

Script libraries

A script library is a place for storing and sharing LotusScript programsand Java code. The script library contains (Option), (Declaration),Initialize, Terminate, and user scripts. All scripts in a database canshare the code in a library in that database. For more information aboutScript Libraries, see “Using script libraries” in the Programming Guide.

Shared Java files

For large Java applets with multiple files, it is most efficient to storesome of the related files as shared resources in the database. When youset up files as shared resources, all the applets can use a single copy ofthe file, instead of each applet storing its own copy. Then, if a filerequires updating, you only need to update one file. For moreinformation, see the topic “Setting up shared applet resources.”

Shared Actions

Use shared actions in forms or views to set up user-activated tasks. Youcan make shared actions available in the Actions menu or as buttons onthe action bar. In particular, actions let users complete tasks whenaccessing Domino databases on the Web. For more information onshared actions, see “Create and insert a shared action.”

Creating an image resource

Create a resource library of images to use throughout your database.Although there are other methods for using images in a database, usingimage resources is the most efficient, because with image resources youneed to maintain the image in only one location. If there are any changes tothe image, changing and refreshing the source file distributes the changeswherever the image is referenced.


To Create an image resource1. Expand Resources in the Design pane.

2. Select Image from the list of Resources.

3. Click the New Image Resource button.

4. Select gif, bmp, or jpeg in the “Files of Type:” list.

5. Select one or more graphic files you want to include as image resources.

6. Click Open.

Designer creates an entry for each of the files you select.

Image resource propertiesTo access the Image Resource Properties box, select the image from the listof images and choose Resource - Resource Properties.

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

Prohibit the design to be modified if the database’s design is refreshedor replaced

Hide the image from Web browsers or Notes clients

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

A horizontal image set creates an image that seems to change based on itsstate. (For example, a mouse passes over an image that appears to light up.Or, an image can darken as a user clicks on it, and dim once clicked.)

To create a horizontal image set1. In your graphics program, copy and modify an image up to three times.

All of the images must be the same size.

The number of images corresponds to the number of states you areusing. 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 Clicked image Fourth position

2. In a gif, bmp, or jpeg file, line up the images horizontally separated by aone-pixel space or line.

3. Create an image resource entry for image file.


4. On the Basics tab of the Image Resource Properties box, choose thenumber of images across

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

Using a vertical image setUse a vertical image set for icons you add to the bookmark bar. Thebookmark bar can display small, medium, or large icons if the imageresources for the icons are part of a vertical image set. A vertical image setincludes an icon in three different sizes. (Users choose what size icons theywant displayed in the bookmark bar in their User Preferences.)

To create a vertical image set, follow the steps for creating a horizontalimage set but, in Step 2, line up three differently sized images vertically,with a one-pixel space between each one, and in Step 4, select how manyimages down you are using. In addition, use a background around theimages to create a rectangle.

To colorize grays

If you want an image to blend with the user’s system colors, select theoption “Colorize grays” on the Basics tab of the Image Resource Propertiesbox. When enabled, the grays in an image that correspond to the Lotus


palette grays change to a corresponding color scale using the color schemeof the user’s operating system. This feature lets the image resources blendin with the other elements of the user’s system, such as dialog boxes andmenu bars.

Inserting an image resource1. Open a form, document, or page.

2. Place the cursor where you want to add the image.

3. Choose Create - Image Resource.

4. Choose the type of image — gif, jpeg, or All Images — from the ImageType list.

5. Select the name of the image file.

6. Click OK to display the image in the form, document, or page.

Tip To use the images among multiple databases, put the image into atemplate and inherit the resources into all the databases where they’reneeded. For more information on creating templates and inheriting design,see “Completing an application.”

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

To export an image resource1. Select the image you want to redesign.

2. Choose Image - Export.

3. Select the directory you want to copy the image to.

4. Click Open.

To distribute design changes for an imageIf the image you are using changes, you can distribute those changeswherever the image appears in the database.

1. Select the image that has changed and choose Resource - Refresh.

2. Select the new image from the filing system. It doesn’t matter if thename of the image has changed.

3. Click Open.

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


Designing an application for maximum accessibility for people with disabilities

When designing an application, keep in mind there are things you can do to make your application accessible to people with physical disabilities. To be accessible and meet federal accessibility guidelines, your applicationmust be:

Keyboard-accessible — An application is keyboard-accessible if it canbe used without a mouse or other pointing device.

Screen reader-accessible — An application is screen reader-accessible ifvision-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 thecursor. In order to function, the screen reader software must havedetailed information about the graphical user interface (GUI), so that itcan translate the graphical display into speech.

It must also follow good user interface design practices regarding the use ofcolor, text, and graphics.

The Notes client itself is both keyboard-accessible and screenreader-accessible. On those platforms which support it, Notes uses MSActive Accessibility (currently only available on Windows 95). However,application developers must be aware that it is possible to create anapplication in Designer that is not accessible. Many of the objects you createin Designer have the capacity to be made accessible. For example, imagescan have alternate text tag. Also, the Domino server will automaticallygenerate accessible HTML whenever possible. There are, however, somedesign elements that are not accessible. Here are some important things tokeep in mind when you are building your application.

Use text as the primary means of communicating information. Text andrich text are accessible in almost every situation.

Use the Alternate text tag on all images and applets.

Both images and Java applets allow you to specify a short piece of textto be displayed with the graphical object. Normally the alternate textappears only when the object is loading or when a user has turned offimage or applet loading in their browser preferences. However,alternate text is also used by screen reader software to describe thecontents of an object. Specify alternate text on the Basics tab of thePicture and Java applet Properties box.


Use Action buttons that echo items in the Action menu.

Screen readers cannot always provide information about action buttons.By echoing action buttons in the Action menu, you ensure accessibilityin this area. To make sure that an action button is echoed on the Actionmenu, open the properties box for the action and select “Include inAction Menu.”

Avoid:

Using Java applets as the sole means of navigating or performing anaction. Java accessibility is currently not widely supported, and akeyboard-only user cannot navigate to a Java applet in many browsers.

Excessive use of embedded objects. Although these are keyboard-accessible, navigating through too many objects can be a burden forkeyboard-only users.

Excessive use of framesets. It is laborious for keyboard-only users tonavigate through framesets. The fewer frames used in an application,the easier it will be for a keyboard user to navigate.

Using color and graphics as the sole means of communicating meaningin your application. To test if your application is usable for color-blindusers, set your display to monochrome and check all graphics forlegibility.

Very small text. Some operating systems support a large font userpreference, but this preference is not respected by all objects in anapplication. Avoid using text smaller than 10 point Helvetica.

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

For more information about accessibility, visit the IBM Special Needs Website at http://www.austin.ibm.com/sns/ or the W3 Web AccessibilityInitiative (WAI) site at http://www.w3.org/WAI.


Previewing your design work

In order for you to be able to test your application to see how it looks andbehaves from the Notes client and the Web, you can preview your work insupported browsers. When you start up your system, Designer searches forthe following browsers:

Internet Explorer

Netscape

For each supported browser Designer finds, it adds an icon to the tool bar inthe upper right corner of the Design pane. If you have both Netscapeversion 3.x and 4.x both icons are added. There are also icons forpreviewing through the Notes Browser and previewing in Notes.Previewing design work in the Notes Browser is not equivalent to choosingto Preview in Notes. Previewing work in the Notes Browser serves theapplication through the Domino server, while Previewing in Notes servesthe application directly to the Notes client.

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

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

To preview in Notes or in the default Web browser using the menu1. 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 <Webbrowser>. You will be prompted to save any changes. If you do not saveyour changes, Designer will preview your work without the changes.

To shut down the HTTP process that runs the Web Browser previewwithout exiting Notes, choose File - Tools - Stop Local Web PreviewProcess.


To preview in Notes or in the default Web browser using the preview icons1. Open the design element you want to preview or select it from the

Design list.

2. Make design changes if necessary.

3. Click the icon on the Menu bar that represents the browser in whichyou want to preview. You will be prompted to save any changes. If youdo not save your changes, Designer will preview your work without thechanges.

Notes client

Domino

Internet Explorer

Netscape version 3.x

Netscape version 4.x

To shut down the HTTP process that runs the Web Browser previewwithout exiting Notes, choose File - Tools - Stop Local Web PreviewProcess.

Requirements for previewing your design work on the WebA Windows 95, Windows 98, or NT workstation.

You must modify the application’s access control list. The Web previewprocess uses the access assigned to -Default- or, if available, an entrycalled Anonymous. One of those entries needs Reader access to let youpreview pages, framesets, documents, navigators, and views. One ofthose entries needs Author access with create document permission tolet you preview forms.

The element to be previewed must reside in a database under the Notesdata directory on the local machine or on a server running the HTTPtask.

The element to be previewed must not be marked as hidden from Webbrowsers.

Your browser(s) must be set up to override proxy settings (describedbelow).

To set up a default browser for previewingTo set up previewing, you must override the proxy settings so the previewprocess can find the databases — both on your local machine and on anyservers 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 browsersIf you use alternate browsers, you must set them up for previewing. See theHelp for your browsers for more specific information on proxy settings.

1. Open each browser, and then open its Proxy settings page.

2. Specify these case-sensitive entries:localhost

<Domino server name>

3. Click OK.


Chapter 3Designing Outlines

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

Outlines

Outlines, like imagemaps and navigators, are tools that let you providenavigation in your application. All databases come with a defaultnavigation structure called the folder pane (also referred to as thenavigation pane). The folder pane, by default, displays a list of sharedviews and shared folders. In the Notes client it appears in the left pane, andin a Web browser, the folder pane displays at the top left of the browserwindow. When users click on the view or folder they want to access, thatview or folder is displayed in the right pane. If you want create a customnavigation structure for your application, create an outline.

In addition to jumps to all of the views and folders in your database, youcan include actions or links to other elements. You can create an outline thatnavigates through your entire application or site, or through part of it.

You can also use outlines to help you plan your application. To do so, youcreate an outline that represents the skeleton of your application, in whicheach outline entry represents a design element or component of theapplication.

Once you create an outline, you embed it on a page or form. This displays itto users, who use it as a site map or navigational structure. Users can clickon the outline entries to take them where you want them to go.

The process of creating a navigation structure using an outline involves thefollowing steps:

1. Create a new blank or default outline.

2. Create outline entries for jumps or actions you want to present to theuser.

3. Embed your outline on a form or page or in a rich text field of adocument.

41

4. Format the display of the embedded outline.

5. (Optional) Include embedded outline in a frameset.

Some important features of the Outline include:

You can completely customize an outline, reordering how items appearin the folder pane as well as including jumps to elements outside ofyour application. You can control how the outline appears to users bychanging text and button styles and adding icons from your database’sshared resources.

Outline entries are fully programmable. You can add logic that controlshow outline entries are rendered by the Notes client or Web browser.

By combining the outline with Framesets, your application can includemultiple outlines that launch links in target frames.

Creating an outlineYou can create an outline from scratch or generate a default outline.

If you are using the outline to help you plan your application, you cancreate the outline entries prior to designing the actual design elements.Begin by creating a new outline and then adding entries for each elementyou plan to include in your navigator or site map.You can include outlineentries for any element that will be part of your application or site, such asjumps to pages, documents, views, folders, Web pages, or other Dominodatabases. Outline entries represent each piece or planned piece of yourapplication or navigation structure. Outline entries can also be clickableactions or can be top-level categories that organize other entries. You canalso choose what icons display with the entry. You can organize yourapplication into units and create multiple outlines to represent the differentportions of your application.

If you have already created all of your design elements or are working witha database created from a template, you can begin by creating a defaultoutline and customizing it.

To create a new outline from scratch1. Click Outlines in the Design pane.

2. Click New Outline.

3. Add outline entries for each design element, action, or link you want toinclude in the outline.


To create a default outlineThe default outline creates outline entries for all the views and folders inthe database. In addition, the default outline contains placeholders called“Other views,” “Other folders,” “Other private views,” and “Other privatefolders.”

Click Generate Default Outline.

To add a new outline entry:1. Click New Entry.

2. In the Outline Entry Properties box, enter the label you want appear inthe outline, for example, Home Page or Main View.

3. Enter a type for the element in the Content field. If you are creating ajump to a named element that does not yet exist, Designer will display aprompt letting you know that you will need to create the element later.

Jump to:

A URL (enter entire URL including protocol, for examplehttp://www.lotus.com)

A link - such as to an anchor, document, view, or database link

A named element - such as a Page, Form, or View

Perform an action - such as open or create a document. To enter anaction, click the @ button, and enter a formula.

None (use this to create a top-level category for nesting entries).

4. (Optional) Enter an alias for the outline entry.

5. (Optional) Enter the target frame for the jump or action.

If you have not yet created your frameset, you can either enter the nameyou are planning to use in your frameset or you can add this entry later,after you have created your frameset.

Note You can cut and paste outline entries from other outlines.

Once you have created outline entries for the elements that you areincluding in your application, you can reorder the elements or create ahierarchy between them.

Chapter 3: Designing Outlines 43

To reorder elements in an outlineCreate the order for the outline entries as you want them to appear to theuser. You can reorder the elements after you create them. To reorder theelements in an outline:

Select one or more outline entries in the Design pane and drag to movethem up or down in the list.

To create a hierarchy between elementsOutline elements can have a hierarchy, that is, there can be top-level entriesand sub-level entries.

This is especially useful, for example, if you would like to create nestedoutline entries. To create a hierarchy between elements do one of thefollowing:

Select one or more outline entries and click the Indent Entry button (orpress the TAB key) to indent the element one tab stop to the right.

Select one or more outline entries and click the Outdent Entry button(or press SHIFT-TAB) to outdent the elements one tab stop to the left.


To delete an outline entry1. Select the outline entry that you want to delete.

2. Press DEL or choose Edit - Clear.

Embedding an outlineTo 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 youroutline on a form, page, or document will depend on how you want to useit. You can embed the outline on a form so that each document created fromthat form includes the embedded outline. The outline then presents an easyway for users to navigate to other views, create a new document, move tothe next document, and so on. For example, in a Discussion database, youcan embed the outline on the Main Topic form. When an user creates adocument with that form, the outline appears on the document.

Embed the outline on a Page if you want to use the outline as part of aFrameset or as part of your home page. Embed the outline on multiplepages if you need to have several occurrences of the same outline withdifferent styles (for example, one outline with only text, another withgraphical buttons).

If you want several navigational structures in one application you can dotwo things. You can create one outline and embed it several times ondifferent pages, or you can create several different outlines and embed eachon different pages.

Embedding the outline on a page1. Click Outlines in the Design pane.

2. Open the outline you wish to embed.

3. Click Use Outline on the action bar at the top of the Design pane. Theembedded outline appears on a new page with the default style appliedto it.

4. Choose File - Save. You will be prompted to enter a name for the Pagewhich the outline is now embedded on.

Embedding the outline on a form, page, or document1. Open or create the form, page, or document you want to embed the

outline on.

2. Position the cursor where you want the outline to appear. In adocument you must be in a rich text field.

3. Choose Create - Embedded Element - Outline.

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

Outline properties Gives the outline a name and aliasMakes the outline available to public access users

Outline entryproperties

Assigns a label and alias to the outline entrySelects what the entry will do: Jump to a URL, link, or named element, perform an action, or nothingSelects the link or enters a formulaEnters the target frame for the action or linkSelects the imageSelects “Refuse selection”Selects hide options for the entry

Embedded outlineproperties

Formats the embedded outline’s look and structure

Selected outline properties

Making the outline available to public access usersThis 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 toread/write public documents. (Public access users will be able to open thedatabase to views enabled for public access and to read/write documentsenabled 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 forpublic access users. The page and frameset in which the outline appearsmust also be enabled for public access users. For more information aboutpublic access, see “Creating pages, forms, outlines, views, and agents forpublic access.”

Selected outline entry properties

To add an image to the entryYou can display an image with any outline entry. By default, outline entriesfor views will display the view icon, and outline entries for folders willdisplay the folder icon. You can display these icons, choose one of yourown, or choose no graphic. In order to use a graphic as an outline’s icon itmust be added to the database’s shared image resources.


To add an image to appear next to your entry1. Select an outline entry and choose Design - Outline Entry Properties.

2. On the Outline Entry Info tab click the folder icon in the Image sectionand select the shared image resource for your graphic.

3. (Optional) Click the @ button to use a formula to control the display ofthe image.

4. (Optional) If you do not want to display an icon with the outline entry,select “Do not display an image.”

Does not keep selection focusAfter a user clicks on the entry, the entry will not remain selected. Thepreviously selected entry will retain the focus.

To hide an entryYou may want certain entries to show up only under certain circumstances.For example, you can program an entry to be hidden when viewed with aWeb browser. To hide outline entries:

1. In the Outline Entry Properties box, click the Entry Hide When tab

2. Select an option for hiding the entry or enter a formula in the formulabox.

Selected embedded outline propertiesYou can control the display and behavior of the embedded outline using theEmbedded Outline properties box. There are two different style propertiesthat control how the embedded outline appears to the user: Type and Titlestyles.

The first, Type, determines whether the outline shows the hierarchy of theoutline entries. The hierarchy is set up when you outdent and indent outlineentries. If you select Tree style for type, then all of the outline entries thathave indented entries below them will show up as expandable sections. Youcan choose to have green triangles (or twisties) display next to expandableoutline entries, or users can click on the top-level entry to expand it. In aTree style outline, all top-level entries show at all times. Users expand andcollapse entries as necessary.


Tree style outline with twisties turned on:

Tree style with simple title:

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


Initial display for flat style outline:

After clicking Phone Book entry:

To change display attributes:

1. Open the form or page that the outline is embedded on.

2. Select the outline.

3. Choose Element - Outline Properties to display the Embedded Outlineproperties box. In the Embedded Outline properties box you can set theoverall display of the embedded outline.

On the Info tab you can set:

Type style - Tree or Flat. This setting allows you to decide whether to show the hierarchy of the Outline or not. Tree style shows all ofthe outline entries in the hierarchy, while Flat shows only one level at a time. Use the Flat style selection in conjunction with the Titlestyle setting.

If you choose Flat style, you have the option of displaying the outlinevertically or horizontally. Display horizontally displays entries to fitthe window across instead of down.


Title style - Hide or Simple. These settings work in conjunction withthe Type: Flat Style setting. In a Flat style outline, Simple style letsusers navigate back up to prior levels by displaying the parent of thecurrent level in a flat outline. Hide style does not display anyhierarchy, so once users go down a level in the outline they cannotnavigate back up.

Root entry - Defining a root entry will show the children of thespecified entry only. This can be used as a way to restrict users’access to elements in your site or database. Specify a root by usingthe alias of the parent entry. For example, if a parent entry has analias of “Main”, enter Main in the Root entry box and only thatentry’s children will display in the outline initially. If the specifiedentry does not have any children, then nothing will display in theoutline. If you want to give users a way to navigate back up thehierarchy from the root entry’s children, enable Simple as the Titlestyle 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 aTitle style.

On the Font tab, select either Top-level font or Sub-level font to formatthe font of the outline entries. If Title style is set to Simple, select theTitle Font. You can also select font colors for:

Normal state of entries

On Select (when the entry is selected)

On Mouse (when the mouse passes over the entry)

For each of the areas on the embedded outline, you can specify color orimage backgrounds on the Background tab. You can set mouse-overand selection colors. Images can be tiled in various ways, such as top tobottom, or left to right, or positioned under the text, for button effects.Images must be shared image resources for the database.

On the Layout tab you can set the positioning for the title-level (ifSimple title is enabled), top-level, or the subsequent levels of:

The entire outline entry

Height - height of each entry. (This setting represents the width ofeach entry in a flat horizontal outline.)

Vertical offset - aligns the outline entries relative to the top edge ofthe embedded outline. If you want to customize the spacing betweenoutline entries, use this setting.

Horizontal offset - aligns the outline entry relative to left edge of theembedded outline, for title or top-level entries. Sub-level offset isrelative to parent entry’s left edge.


The label text of the outline entry

Alignment - within the outline entry.

Vertical offset - relative to the embedded outline, depending onalignment; ignored for a middle vertical alignment.

Horizontal offset - relative to the embedded outline, depending onalignment; ignored for a center horizontal alignment.

The outline entry image

Alignment - within the outline entry.

Vertical offset - relative to the embedded outline, depending onalignment; ignored for a middle vertical alignment.

Horizontal offset - relative to the embedded outline, depending onalignment; ignored for a center horizontal alignment.

Using the outline appletWhen you are designing a Web application, you have two options fordefining how an embedded outline displays in a browser:

Define the embedded outline as HTML. This is the default behavior.

Define the embedded outline as an applet.

The outline applet lets Web users work with outlines embedded in a pageor form. With the outline applet, Web browser users can:

See mouse-over distinctions for items in the outline, including changeof color to indicate a selected item

See background images

To enable the outline applet1. Embed an outline in a page or form, or select an existing embedded

outline.

2. Choose Element - Outline Properties.

3. On the Info tab select Web access “Using Java applet.”


Displaying the outline in a Frameset

Once you have the outline formatted you can insert it into a Frameset.

1. Select Frameset from the list of design elements for the database.

2. Open an existing Frameset that you want the outline to display in, orcreate a new Frameset by clicking the New Frameset Button on theaction bar.

3. Right-click on the Frame you want the outline to appear in and selectthe Frame properties box.

4. For the Content Type select Named Element.

5. Select Page or Form.

6. Enter the Value by either clicking on the Folder icon and selecting itfrom the list box or typing in the name of the page or form containingthe outline you want to display.

7. (Optional) Enter the name of the target frame the links should appear inwhen a user clicks on an outline entry. For more information, see“Specifying a target frame.”

For more information, see “Designing Framesets.”


Chapter 4Designing Pages

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

Pages

A page is a database design element that displays information. Pages can beused anywhere in your application where you have text, graphics, or anembedded control, such as an outline, to present to the user. A page or formcan contain the following:

Text Use text anywhere on a page or form and apply textattributes, such as color, size, and font styles to the text. Forcomplete information on creating and formatting text, seeNotes 5 Client Help.

Horizontalrules

Add horizontal rules to separate different parts of a page orform, or to make a page or form more interesting visually.

Tables Use tables to summarize information, align text andgraphics in rows and columns, or position elements on apage or form. For information on creating programmabletables, see the topic “Creating a programmable tables.” Forall other information on creating and formatting tables, seeNotes 5 Client Help.

Sections A section is a collapsible and expandable area that caninclude objects, text, and graphics. An access-controlledsection allows only certain users to read the section.

Links Add links to take users to other pages, views, databases, ora URL when they click on text or a graphic.

Graphics Place a graphic anywhere on a page or form. Use graphicsto add color to a page or form or to create imagemaps.

continued

53

Imagemaps An imagemap is a graphic you enhance with programmablehotspots. 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.

Attachments Attach files to a page or form so users can detach or launchfiles locally.

Actions Actions automate tasks for the user. Add actions to themenu in a Notes client, or through buttons or hotspots on apage or form. For more information, see “Automation inapplications.”

Applets Use Java applets to include small programs, such as ananimated logo or a self-contained application, in a page orform. For more information about including Java applets ona page or form, see “Including Java Applets inApplications.”

Embeddedelements

Embed the following elements in a page or form: a view,folder pane, navigator, outline, or date picker. Use theseelements alone or combine them to control how usersnavigate through your application.

HTML If you have existing HTML or you prefer using HTML tousing the formatting tools Designer offers, you can import,paste, or you can write your own HTML on a page or form.

OLE objectsand customcontrols

Designer supports object linking and embedding (OLE) aswell as custom controls, sometimes called OCX controls.Including a linked or embedded object on a page or formlets you use a page or form as a gateway to anotherapplication. For example, an Employee Information page orform can include an OLE object that links to a Word Pro®file where the employee annual performance reviews arestored. Notes/FX™ 2.0 fields create a two-way exchangebetween Notes and a supporting application by allowingfield data to be shared and updated from either application.Lotus Components are examples of controls that let youinclude other Lotus products — such as a spreadsheet orchart — in a form. For information on including OLE objectsand custom controls on a form, see “Designing applicationsthat share information.”


How pages relate to forms and documentPages and forms both display information to users. Forms let you collectinformation as well. Fields, subforms, layout regions, and some embeddedcontrols can only be used on forms. A page is best suited for displayinginformation, while a form is more suitable for gathering information.

Creating a page

To create a page1. Click Pages in the Design pane.

2. Click the New Page button.

3. Create the contents for the page, using elements such as text and graphics.

4. Choose Design - Page Properties to assign a name and set other pageproperties, such as the target frame in which the page should display.

To delete a page1. Click Pages in the Design pane.

2. Select the page you want to delete.


4. Click Yes to confirm.

Displaying a pagePages do not display in views. You can display pages to the user by:

Designating the page to be part of a frameset. For more information onFramesets, see “Designing Framesets.”

Creating a link to the page from another design element such as a form,an outline, or another page. For more information on creating links, see“Adding links to a page.”

Creating an action that opens the page. For more information oncreating actions, see “Actions.”

Creating an outline entry that opens the page. For more information oncreating outline entries, see “Outlines.”

Setting the database launch property to launch the page when thedatabase is opened. For more information on the database launchproperty, see “Setting database launch properties.”

Chapter 4: Designing Pages 55

Creating a home page for an applicationA home page gives users a logical entry point to and a summary of theinformation in an application. Not all visitors need to stop by the “frontdesk,” but it’s important to provide a home page for those who need it.Provide links to the home page from other places within the site, so visitorswho enter through the back door can find their way around too.

A home page should contain the following elements in a pleasing mix ofgraphics and text:

A brief description of the company, product, service, or site

Links that navigate to other parts of a site

Information for new visitors

Information for frequent visitors who need to know what is new

A way to search for information

If necessary, a way to register on the site to participate in restricted areas

Create a page with links to other pages, views, documents, or navigators inthe same database or other related databases at the site. You should takesecurity issues into account when you decide whether to store the homepage in its own database or in a database used for other purposes, such asdiscussions, user registration, or product information. You generallyprovide fairly open access to a home page and limit access to other parts ofa site. For more information about security, see “Security in an application.”

To set the home page to launch automatically, choose File - Database -Properties, click the Launch tab, and select the page you want to launch forNotes clients and for Web clients. For more information, see “Settingdatabase launch properties.”

Specifying a page as a Web site’s home page in the server documentA server administrator can specify a page as a Web site’s home page in theserver document for the server. Contact your server administrator for moreinformation.


Styling text for the WebFor Web applications, Domino automatically converts text styles to HTMLtags when there is a corresponding HTML equivalent. This includes bullets,numbers, alignment (except Full Justification and No Wrap), spacing, andnamed styles. Certain types of formatting such as indents, interline spacing,and tabs do not appear when viewed from a Web browser because HTMLhas no corresponding format. Be aware that different browsers may displaytags differently and that not all browsers support the HTML tags thatDomino generates.

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

SizeDomino maps the text size you select in Designer to an HTML text size. Thefollowing table lists the text size in Notes Designer and the correspondingHTML size.

Text size less than or equal to Maps to HTML Size

7 1

9 2

11 3 (this is the default size)

13 4

17 5

23 6

greater than 23 7

Note that Domino does not map font sizes to HTML heading tags (H1, H2,and so on).

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

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


Creating computed textYou can use computed text to generate dynamic text based on formularesults.

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 - Computed Text - Value.

4. Write a formula whose value displays the text you want to show in the page.

Example: Computed textTo personalize the message a user sees on a page or form, create computedtext that displays the user’s name.

On the page or form enter the text:

Welcome <computed text>.

For the Computed text value (located on the Object tab of the Info List)enter the formula:

@Name([CN];@UserName)

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

Welcome Sara Ryan.

Note Domino publishes a <span> tag around the computed text for accessvia JavaScript.

Changing all text stylesThere may be times when you want to change the text style of all the text ona page or form. For example, you might want to customize the mailtemplate to display all text in a different font type or size.

1. Open the page or form.

2. Choose Edit - Select All.

3. Choose Text - Text Properties and choose style options.

4. Save and close the page or form.


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

To create a horizontal rule1. Move the cursor to where you want to enter the horizontal rule.

2. Choose Create - Horizontal Rule.

To change the style of a horizontal rule1. Select the horizontal rule; choose Horizontal Rule - Horizontal Rule

Properties.

2. Click the Horizontal Rule Info tab. On the Info tab you can:

Change the width and height.

To change the width and height in inches, choose Absolute.

To change the width and height as a relative percent of the window,choose Relative (%).

Select a solid color. You can select a color from the palette orcustomize colors by using the color wheel button in the top rightcorner of the Color box. To set the color of your horizontal rule toyour system’s color scheme, click the Color box menu and click theSystem button.

To select a solid color, select a color and click the solid rectangle.

Select a gradient color. A gradient color is a color that blends andfades into the other original color within a horizontal rule. Gradientcolor is not supported on the Web.

To select a gradient color, select the first color, click the shadedrectangle and select the “to” color.

Make a horizontal rule transparent.

Click the Color box menu and click the transparent button.

To undo transparency, click the Color box menu and click the undotransparent button.

Select No 3D shading.


Creating programmable tablesProgrammable tables let you create a table that displays one row at a time,based on an action or field formula. Programmable tables start with atabbed table, much like the Properties boxes in Designer. One tab, or row, of the table is visible at a time to the user. With regular tabbed tables, theuser clicks the tabs at the top of the table to switch which row displays.With programmable tables, the user selects which row appears based onclicking on an action, a link, or an outline entry. When you write theformula to control what row displays, include a field which is the name ofthe table proceeded by “$” (a dollar sign). Also keep in mind when you arewriting your formula, that field names are case-sensitive: $table is adifferent field name than $Table.

For example, on your company’s home page, you could put aprogrammable table that displays different information about yourcompany depending on what your site visitors want to see. If they click“Location Information” they would see the row of the table that gives themthe location of your company. If they click “Company History” they see therow of the table that describes your company’s history.

Note When you are designing programmable tables on a form, you havethe option of using a field on the form to control the table. You can use achoice list field that refreshes on change or computed field.

To create a programmable table1. Move the cursor to where you want the table to appear.

2. Choose Create - Table.

3. Click the programmable table button.

4. Select the number of rows and columns you want in the table. Tabs areused to display rows on the table. All columns in a row will appearwhen that row is displayed.

5. On the Table Programming tab of the Tables Properties box:

Enter a Name/ID for the table.

For each row in the table, click on the tab for the row. Then, enter aname for the row in the Row Tags field of the properties box.

6. Set the display options for the table. For information about formattingtables, see Notes 5 Client Help.

7. Enter text, graphics, or objects in the table.

8. Create links, actions, or an outline that will set the fields for the tableand control what displays.


Example: Creating Hotspots to control a programmable table1. 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 whatusers will see when that row of the table is displayed. Enter a line foreach row of the table. For example, if you have a two-row table — onerow has the company location and the other has the company history —enter two lines of text:

Our company locations

Our company history

4. Select the text for the first line and choose Create - Hotspot - Action Hotspot.

5. Click the Hotspot Click event in the Objects tab of the Info list in theProgrammer’s pane.

6. Enter a formula in the Script area of the Programmer’s pane that setsthe field $CompanyInfo to the name of the row of the table you want to display.FIELD $CompanyInfo:= "a";

@Command([RefreshHideFormulas])

7. Select the second line of text and create a hotspot with the formula:FIELD $CompanyInfo:= "b";

@Command([RefreshHideFormulas])

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

For more information about writing formulas, see the Programming Guide.For more information on creating basic, tabbed, or animated tables, seeNotes 5 Client Help.

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


To create a section1. 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 section1. Select the section and choose Section - Section Properties.

2. On the Section Title and Border tab you can:

Enter a title for the section. Titles can be either text or a formula.

Use text if the title should be the same all the time.

Use a formula if you want the title to appear differently underdifferent conditions.

Select the border style. The border appears around the section.

Select a border color.

3. On the Expand/Collapse tab:

Select options for showing the section expanded or collapseddepending on whether a document is being previewed, opened forreading, opened for editing, or printed.

Select “Hide title when expanded” if users don’t need to see thesection title when the fields are displayed.

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

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

To create a link to a design elementTo link to a design element, create a named element link. Named elements are:

Pages

Forms


Framesets

Views

Folders

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. Wheneverpossible, create aliases for design elements. If the design element has analias, 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 link1. Select the design element you want to link to.

2. Choose Edit - Copy as Link - Named Element.

3. Select the text or graphic that will serve as the link and choose Create -Hotspot - Link Hotspot.

4. Click the Paste icon on the Properties box.

5. (Optional) Enter a target frame for the link.

6. (Optional) Select “Show border around hotspot.” (Not supported on theWeb.)

To create a link using the properties box1. 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 thefollowing:

Enter the name of the element

Click the folder icon to browse

Click the @ icon to enter a formula that resolves to a link


6. (Optional) Select “Show border around hotspot.” (Not supported on the Web.)


To create a link to a document, view, anchor, or databaseThese links are more stable than traditional HTML links because they donot reference file names; rather, they reference the unique internal ID of theelement. If the name of the linked item changes, the link remains valid.

1. Open or select the element you want to link to. For document, view, oranchor links, open or select from the Notes client.

2. Choose Edit - Copy as Link - <type of link>.

3. Select the text or graphic that will serve as the link and choose Create -Hotspot - Link Hotspot.

4. On the Hotspot Info tab of the Hotspot Resource Link Properties box,select “Link” for the type.

5. Click the Paste icon on the Properties box.



Linking to a URLUse a URL link to create a link based on a URL name. Since this type of linkis based on a hard-coded URL name, any changes to the URL break the link.

To create a URL link1. 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.



Adding graphicsA page or form that contains a graphic is visually appealing but takes moretime to display and print. You can paste or import graphics into pages, asyou can into documents, forms, views, and navigators. Designer storesgraphics in Graphics Interchange Format (GIF) and Joint PhotographicExperts Group (JPEG) in their native formats. Therefore, these are the best


choices for graphic fidelity. Designer stores other types of graphics in aplatform-independent 256-color format that is similar to GIF89a format.(GIFs are 256-color images.)

Graphics can be:

Stand-alone graphics that add aesthetics or focus to a page or form

Background graphics

Imagemaps — navigation structures composed of graphics that contain links.

Preparing graphicsYour goal, when preparing a graphic, is to have it look as much as possiblelike the graphic you created in your drawing program. How graphics lookdepends on the user’s viewer, operating system, and color mode.

Viewer — Notes client or a Web browser

Depending on your audience, you should use either the Lotus colorpalette or the Web color palette.

If your audience is only Notes users, use either the Lotus colorpalette or the Web color palette.

If your audience is only Web users, use the Web color palette.

If your audience is both Notes and Web users, use black and white or very simply colored graphics, or use the Web color palette.

Operating system — Macintosh, Windows NT, Windows 95/98, OS/2,or UNIX

Always reduce graphics in formats other than gif or jpeg to 256 or fewer colors. Although doing this may reduce the quality ofhigh-resolution graphics, it ensures a more reliable color display across platforms.

Color mode — 16-color mode, 256-color mode, or High/True/24-bitcolor mode.

If all users have machines that display in true color mode, reducing thecolors to 256 or fewer is all you need to do to prepare a graphic. If usershave machines running in 256-color mode, use a color palette to mapcolors in the graphic to a table of predefined colors.


Changing the color paletteIf you are designing applications for users to access on the Web, you canchange from the Lotus color palette to a Web color palette while designingto provide greater color fidelity. To change palettes:

Choose File - Preferences - Notes Preferences. Check “Use Web Palette” onthe Advanced options list of the Basics tab. If this option is unchecked,Designer uses the Lotus color palette.

Note When Web users open a database, Domino converts non-gif andnon-jpeg graphics to gif or jpeg formats. The system administrator specifiesthe format in the “Image conversion format” field, which is part of theHTTP Server section of the Server document. For more information, seeAdministering the Domino System.

To add graphics to a page or formThere are four ways to add a graphic:

Copy and paste

Import a graphics file

Create a picture

Insert a shared resource

To copy and paste a graphic1. Copy a graphic to the clipboard.

2. Open the page or form and move the cursor to where you want to placethe graphic.

3. Choose Edit - Paste.

To import a bmp (bitmap), jpeg, gif, pcx image, or tiff 5.0 bitmapBecause Web browsers support gif and jpeg formats directly, manydevelopers find it easier to design graphics using these formats.

1. Move the cursor to where you want to place the graphic.

2. Choose File - Import.

3. Choose the graphic file to import and click Import.

To create a picture1. Move the cursor to where you want to place the graphic.

2. Choose Create - Picture

3. Choose a graphic to import and click Import.


To insert a shared image1. Move the cursor to where you want to place the graphic.

2. Choose Create - Image Resource.

3. Choose the type of image — gif, jpeg, or All Images — from the ImageType list.

4. Select the name of the image file.

5. Click OK.

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

To resize a graphic1. Select the graphic.

2. Choose Picture - Picture Properties.

3. Do one of the following:

Drag the box in the graphic’s lower right corner

In the Scaling field of the properties box, enter a value for the widthand height

To return a graphic to its original size1. Select the graphic.


3. On the Picture Info tab, click “Reset.”

To set the text wrap properties for the graphicThere are several alignment and text wrap properties you can set in thePicture Properties box. Alignment options indicate how the picture lines upwith text on either side of it. By default, Designer aligns a picture with thebottom of the text around it. To wrap text around the picture, choose either“Wrap, float image left” or “Wrap, float image right.”

1. Select the graphic.

2. Choose Picture - Properties.

3. Choose an option for wrapping the text around the graphic.


To add alternate text for the WebYou can make your application accessible to people with physicaldisabilities. 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. Inorder to function, the screen reader software must have detailedinformation about graphics, so that it can translate the graphical displayinto speech. You can provide this information by making sure you includealternate text for all the graphics in your application.



3. Click the Picture Info tab.

4. Enter text in the “Alternate text” box.

5. (Optional) Enter a caption and a caption display option.

Adding a background color or graphicYou can paste or import a bmp (bitmap), jpeg, gif, pcx image, or tiff 5.0bitmap graphic file as a background for a page or form. If the graphic is thesame size as the page or form, it appears once; smaller graphics “tile” to fillthe background. All page or form elements appear in front of background.

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

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

To choose a background color1. Open the page or form.

2. Choose Design - <Design element > - Properties and click theBackground tab.

3. Select a different background color.

To paste a bitmap as a background1. Copy to the clipboard the bitmap you want to use as a background.

2. Open the page or form.

3. Choose Design - <Design element> Properties and click the Background tab.

4. Click Paste Graphic to display the graphic as the page or formbackground.


To import a bitmap, jpeg, gif, pcx image, or tiff 5.0 bitmap as a background1. Choose Design -<Design element> Properties and click the

Background tab.

2. Click the Import Graphic button and select the file to import.

3. Click OK.

To delete a page or form background1. Choose Design - <Design element> Properties.

2. Click the Background tab then click Remove Graphic.

For more information, see “Adding a picture” in Notes 5 Client Help.

Creating an imagemapAn imagemap is a graphic you enhance with programmable hotspots thatperform some action when a user clicks on them. Imagemaps are often usedas navigational structures in an application. For example, an imagemap of aplate of food might have hotspots users click to see recipes for the foodpictured. Unlike a navigator, which is an independent design element, animagemap resides on a page or form, so you can easily combine animagemap with text and other page or form elements, and you can controlthe display of an imagemap using a hide-when or computed-for-displayformula. If you plan to create a sitemap or navigator that combines severalgraphics with text and action buttons, create a navigator instead of animagemap.

An imagemap can be any graphic you can paste or import into a page orform, with the exception of graphics in the pic format. If you create animagemap and then need to change the graphic, you can change the graphicwhile keeping the hotspots intact.

To create an imagemap1. Paste, create, or import a graphic or shared image on a page or form.


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 entiregraphic, choose Default Hotspot.

5. Choose Picture - Hotspot properties.

6. On the Hotspot Info tab of the Hotspot <shape> Properties box, specify alink. For information on linking, see “Adding links.”


7. (Optional) Specify a target frame where the linked document willdisplay when a user clicks the hotspot.

8. On the Advanced tab add alternate text.

9. (Optional) On the Advanced tab, specify the Imagemap tab order forthe hotspot. The tab order specifies the order in which hotspots areselected when a user presses the TAB key.

10. (Optional) In the Script area of the Programmer’s pane, specify a simpleaction, formula, or LotusScript or JavaScript routine to run when a userclicks the hotspot.

To move a hotspotOnce you create a hotspot you can move it as necessary. To move a hotspotdo one of the following:

Click and drag the hotspot that you want to move.

Select the hotspot and use the arrow keys to move one pixel at a time.

To delete a hotspot from an imagemap1. Select the hotspot.

2. Choose Picture - Delete Hotspot.

To copy an imagemapYou can copy an imagemap from another page or form, form, or document,and Designer will maintain all of the hotspots from the original imagemap.

1. Select the imagemap you want and copy it to the clipboard.

2. Open the page or form where you want the imagemap and choose Edit - Paste.

To change the graphic for imagemap1. Select the current graphic.

2. Choose Picture - Replace picture.

Adding an appletYou can add a Java applet to provide visual interest or additionalfunctionality — for example, you might use animation to make your homepage or form appealing. Applets can range from programs you buildyourself to pre-built programs that you simply drop into a page or form. InWeb applications, there may be times when you want to display anembedded object, for example, a view or outline, as an applet rather than asHTML to provide a richer user interface.


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

In the case of custom or pre-built applets you want to include in a page or form, follow the steps for inserting, modifying, and running appletsdescribed in “Including Java applets in an application.”

Creating an attachmentAdd a file attachment to make the file available for users to launch ordetach. You can also create attachments to store files. For example, attach afile for use in a Web application, so that it can be accessed using a DominoURL. For more information about opening an attachment with a URLcommand, see the topic “URL commands for opening attachments, imagefiles, and OLE objects.”

To create an attachment1. Open the page or form.

2. Move the cursor to the location where you want to create the attachment.

3. Choose File - Attach.

4. Select the file and click Create.

Embedding elementsEmbedded elements are a group of objects and controls that can beembedded on a page or form, form, subform, or document. Elements thatcan be embedded include:

Views

Folders

Outlines

Navigators

Date pickers

One reason to embed an element on a page or form is to make theapplication’s display consistent for both the Notes client and Web browser.Most design elements have different display properties depending onwhether a user views them from a Web browser or from a Notes client. Tobetter control the display and functionality of views, folders, navigators,and outlines, you can embed them on a page or form, form, subform, ordocument. Embedded elements provides functionality in Web applicationsthat closely resembles functionality already available in Notes applications.


Embedding makes it easier to design a single application for use by Notesand Web clients.

Additionally, embedding lets you combine elements on a page or form anduse a full range of design features, including frames, tables, styled text, andgraphics, to create a high-impact design.

To add an embedded element on a page or form1. Move the cursor where you want the embedded element to display on a

page or form, form, subform, or rich text field of a document.

2. Choose Create - Embedded Element and select the type of element to embed.

3. (Optional) If available for the element, you can enter a formula thatspecifies under what circumstances it should display.

4. (Optional) Click the embedded element and choose Element - <element> Properties to change the alignment, style, or hide.

To delete an embedded element1. Select the embedded element.

2. Choose Edit - Clear.

Embedding a date pickerYou can easily create a custom calendar application by embedding a datepicker on a page or form. An embedded date picker displays a monthlycalendar. The most common application of this is to display a date picker in one frame of a frameset and a standard calendar view in another frame.Clicking a specific day in the date picker broadcasts a message to theframeset to open the corresponding day in the calendar view, displaying all calendar entries for that day. This feature is not supported on the Web.

To embed a date picker1. Move the cursor where you want the date picker to display on a page

or form, form, subform, or rich text field of a document.

2. Choose Create - Embedded element - Date picker.


Setting properties for the date pickerChoose Element - Date Picker Properties to set:

Horizontal and vertical size

Font style and color

Alignment and spacing

Hide-when options

Importing, pasting, or entering HTMLYou can use an existing Web page or form as a starting point for a page orform you are designing by importing or pasting HTML from the Web intoyour page or form. There are three ways to use HTML on a page or form.You can import HTML. When you import HTML, Designer renders it onthe page or form already translated from HTML. You can also paste orwrite HTML directly on a page or form. In these cases, the HTML stays inHTML format, and you must choose “Treat contents as HTML” in the PageOr Form Properties box.

To import HTMLTo import HTML you must first save it as a file that you can access. Whenyou import HTML to a page or form, Designer will translate the importedHTML and render it already translated from HTML.

1. Open a page or form.


3. Select the file containing the HTML you want to import and click OK.

To paste HTML1. Select the content you want to paste from the source of an existing Web

page or form or another source.

2. Copy the content to the clipboard.

3. Open a page or form.


5. Choose Design - <Design element > Properties.

6. Click the HTML tab and check the “Treat contents as HTML” setting.


To enter HTML directly on a page or form1. Open a page or form.

2. Enter the HTML directly on the page or form.

3. Choose Design - <Design element > Properties.

4. Click the HTML tab and check the “Treat contents as HTML” setting.

When you select the “Treat document contents as HTML” property,Domino passes all data on the page or form directly to the browser. Dominoignores embedded navigators and folders and any embedded views thatdon’t have the property “Treat view contents as HTML” selected.

To include some HTML on a page or formYou can include some HTML on a page or form and mark this text asHTML. Designer will serve it correctly to the browser.

1. Enter or paste HTML on the page or form.

2. Select the text and choose Text - Pass-thru HTML.

Launch properties for pages or formsTo set the launch property for a page or form:

1. Click the Launch tab

2. Set the following auto-launch properties for when a user opens a pageor document created with a form:

First Attachment

First Document Link

First OLE Object

None

3. Set the frameset that the page or form will be associated with and theframe within that frameset.


Programming a page or form

A page or form has events associated with it that you can use to run asimple action, a formula, a LotusScript routine, or a JavaScript program. Tosee what events are available for a page or form, open the page or form inDesigner and look at the list of events in the Objects tab on the Info List inthe Programmer’s pane. Selecting an event makes active the choices youhave for programming that event. For example, if you select the onLoad oronUnload events, you must program them using JavaScript. If you selectthe Window Title event, you must program the event with a formula.

For information on each event and an example of how to program them, seethe Programming Guide.

Adding HTML header informationThe HTML Head Content event on a page or form lets you pass HTMLinformation, such as Meta tag to the Head tag for a document.

To add HTML header information1. In the Programmer’s pane, click the Objects tab of the Info List.

2. Select the HTML Head Content event.

3. Enter the HTML in the Script area of the Programmer’s pane.

4. Click the green check mark to validate your work.

Example: Adding HTML to the head tag header informationThis 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 informationUse the JS Header event to store any JavaScript functions that you want tocall from other events on the form or page or form. You do not have toinclude the <SCRIPT> tags. Domino creates those for you and puts thescript into the <HEAD> tag of the HTML page or form.

To add JavaScript header information1. In the Programmer’s pane, click the Objects tab of the Info list.

2. Select the JS Header event.

3. Enter the HTML or script in the Script area.

4. Click the green check mark to validate your work.


Example: Adding JavaScript header informationThis example uses JavaScript and cookies to load a page or form into thebrowser and save a cookie called “Cookie_Man” in the user’s cookie file. Italso displays a message that shows the number of times a user has visitedthe site. It uses two functions, doCookie() and getTimes(), written in the JSHeader. These functions are called from the onLoad event and the inlinescript on the page or form.

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

In the JS Header Event enter the following code:

cookieName = "Cookie_Man";function doCookie() {

if(document.cookie) {index =

document.cookie.indexOf(cookieName);} else {

index = -1;}

if (index == -1) {document.cookie=cookieName+

"=1; expires=Saturday,01-Apr-2000 08:00:00 GMT";

} else {countbegin =

(document.cookie.indexOf("=", index) + 1);countend =

document.cookie.indexOf(";", index);if (countend == -1) {

countend =document.cookie.length

}

count =eval(document.cookie.substring(countbegin, countend)) + 1;

document.cookie=cookieName+"="+count+"; expires=Saturday,01-Apr-2000 08:00:00 GMT";

}}function getTimes() {

if(document.cookie) {index =

document.cookie.indexOf(cookieName);if (index != -1) {

countbegin =


(document.cookie.indexOf("=", index) + 1);countend =

document.cookie.indexOf(";", index);if (countend == -1) {

countend = document.cookie.length;}count =

document.cookie.substring(countbegin, countend);if (count == 1) {

return ("<b>"+count+"</b> time before.</b>");} else {

return ("<b>"+count+"</b> times before.</b>");}

}}return ("<b>0</b> times before.</b></b>");

}

The onLoad page or form event contains the following code:

doCookie()

This HTML code is at the bottom of the form, formatted as Pass-ThruHTML text.

<script>document.write("You have visited this site"+getTimes());</script>


Chapter 5 Designing Forms

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

Forms

Forms, like pages, display information. Everything that can be done with a page can be done with a form. What sets forms apart from pages is thatforms can be used to collect information. A form provides the structure forcreating and displaying documents, and documents are the design elementthat store data in the database. When a user fills out the information in aform and saves it, the information is saved as a document. When a useropens the document, the document uses the form as a template to providethe structure for displaying the data.

The following are the basic steps involved in designing a form:

Decide on the purpose and type of form you need. To do so, consider:

The kind of information you want to collect and what elements you willneed.

How and where the resulting documents, which contain and displaythe collected information, will appear.

Create the form.

Add elements to the form.

Name the form.

Assign its properties.

Preview and test the form in the browsers users access it with.

79

Form Elements

Form elements are the components you use to create a form’s aesthetics andfunction. Like pages, forms can contain:

Text Text is often used to label fields so users understand thepurpose of each field.

Horizontal rules Add horizontal rules to separate different parts of a form, or tomake a form more interesting visually.

Tables Use tables for summarizing information and aligning elementssuch as fields and graphics in rows and column. A table placedon a form appears in every document created with the form.

Sections A section is a collapsible and expandable area defined on aform. It can include fields, objects, layout regions, and text. Anaccess-controlled section allows only certain users to edit thefields in the section.

Graphics When you place a graphic anywhere on a form, it appears onevery document created with the form. For example, on a formfor correspondence, placing your company logo at the top ofthe form creates a letterhead.

Imagemaps Imagemaps are graphics you enhance with programmablehotspots that perform some action when clicked by a user.Imagemaps are often used as navigational structures in anapplication.

Links Within a form, you can add links to databases, views, specificdocuments, or URL links that open pages on the Internet.

Automation Form actions, buttons, or hotspots automate simple or complextasks. For more information on creating these elements see“Automation in applications.”

Applets Use Java applets to include small programs, such as ananimated logo or a self-contained application, in a form.

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

Embeddedelements

Embed the following elements in a form: an outline, view,folder pane, import navigator, navigator, and date picker. Usethese elements alone or combine them to control how usersnavigate through your application.

HTML If you have existing HTML or you prefer HTML, you can use it on forms. Use existing HTML by importing or pasting it intoyour form, or you can write your own.

For information on including any of these elements in a form, follow thesteps given for adding them to a page in “Designing Pages.”


In addition, forms can contain:

Fields Fields are the design element that collect data. You can createfields only on forms. Each field on a form stores a single type ofinformation. A field’s field type defines the kind of information afield accepts. You can place fields anywhere on a form. Forinformation about fields, see “Designing Fields.”

Subforms A subform is a collection of form elements stored as a singleobject. A subform can be a permanent part of a form or canappear conditionally, depending on the result of a formula.Subforms save redesign time. When you change a field on asubform, every form that uses the subform changes. Commonuses of subforms include adding a company logo to businessdocuments or adding mailing label information to mail andmemo forms. For more information on including subforms, see“Subforms.”

Access-controlledsections

You can restrict access to a section by creating an access controllist. For information on creating an access-control list for asection, see “Restricting who can access a section of adocument.”

Layout regions A layout region on a form or subform is a fixed-length designarea in which related elements can be dragged and movedeasily and can be displayed in ways not possible on regularforms and subforms. A layout region can contain static text,graphics, buttons, and all fields except rich text fields. You canhide or collapse a layout region and all its components undercertain conditions. Layout regions are not supported for Webapplications.

Embeddedelements

Embedded elements such as the file upload and the groupscheduler that require programming support can be used on a form only. For more information, see “Embedded elements.”

Forms and documents

When a user creates and fills out the information in a form and saves it, the information is saved as a document. When a user opens the document,the document uses the form as a template to provide the structure fordisplaying 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 allassociated documents. However, there may be times when you are mailinga document to a database that does not have the form that was used tocreate the document. In those cases you can designate the form to be stored

Chapter 5: Designing Forms 81

with each document created from it. Storing the form with each documentdoes consume more memory.

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

Condition Form used to display document

If the form used to create thedocument is available and thereis no form stored in thedocument and no form formula

The form that was used to create the document.The original form name is stored in a hiddenfield called “Form” in the document. To find thevalue of the field you can check the DocumentProperties box under the Fields tab.

If a form is stored with thedocument

The form stored with the document. (When aform is stored in a document, the form name isstored in an internal field called $Title.)

If the view has a form formula The form is determined by the view’s formformula.

If the form used to create thedocument is not available in thedatabase

The default form for the database. Each databasecan have only one default form, which is markedwith an arrow in the Forms list.

Storing a form with each documentStoring the form with each document allows the document to displaycorrectly even in a database where the form is missing, renamed, or deleted.This feature uses more system memory and may require as much as 20times more disk space. It can also cause additional work if you change theform design because there is no easy way to update all of the stored copiesof the form. In general, store a form in a document only under theseconditions:

The database to which documents are mailed or pasted does notcontain a copy of the original form.

The database to which documents are mailed or pasted doesn’t share an alias with the original form.

The form contains an embedded OLE object or a subscription, and youwant documents to reflect any changes to the object.

You selected “Include in Search Builder” in the Form Properties boxand want the form’s static text to be searchable.

The documents created with this form are stored as encapsulateddatabases and mailed to cc:Mail users.

To store a form with each document1. Open the form.

2. Choose Design - Form Properties.


3. Click the Form Info tab.

4. Select “Store form in document.”

5. Switch to Database Properties in the drop-down list on the Propertiesbox and select “Allow use of stored forms in this database” on theDatabase Basics tab.

Overriding the stored formWhen a form is stored in a document, the form name is stored in a hiddenfield called $Title. Additional information is stored in the $Info,$WindowTitle, and $Body fields. To use a different form to display thedocument, create an agent that deletes this stored form information anddesignates another form to display the document.

Shared fields and documents with stored formsIf the form contains a shared field, that field is converted to a single-usefield in the copy of the form that is actually stored in the document. Thisensures that if a copy of the document is stored in a database that does notcontain the shared field definition, the field can still be used. In the originalform, the field is still defined as shared.

Form formulasTo override the default form selection, write a form formula for a particularview. For example, you can write a form formula that uses one form todisplay all fields when a user edits a document and a different form thatresequences or omits fields when a user reads a document. Since formformulas apply only to a specific view, documents created in other views do not use the form formula.

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

Designating a default form for a database1. Open the Form Properties box.

2. Click the Form Info tab.

3. Select “Default database form.”

Alternatives to storing formsAs an alternative to storing the form in a document, you can use theLotusScript Send method to design a form you can mail along with adocument. This ensures that the database will have the correct form todisplay 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 the Programming Guide.


Creating a form

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

For information on database access, see Managing Domino Databases.

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

To create a new form1. In the open database, click Forms in the Design pane and click the

New Form button.

2. Design the form. Create fields, text, and other elements on the form.

3. Choose Design - Form Properties to assign a name and other formproperties.

To copy an existing form1. 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 inthe Design pane.

5. Choose Edit - Paste to paste the copy into the list of forms in the targetdatabase.

If you are copying a form from a different database, resources such asshared field definitions and shared images are not sent with the copiedform. You must copy resources separately to the new database to avoid anerror message.

Special types of formsThere are several types of forms that you can create for specific purposes.See the following topics for information on creating any of these types offorms.

Profile formsForms that prompt users for inputForms for a Domino billing application

To delete a formRemove a form when users no longer need it. After you delete the form,documents that were created with the deleted form are displayed with thedefault form instead. After you delete a form, to prevent users from seeing


a message that the form can’t be found when they open existing documents,create an agent that reassigns the form name. For information on usingagents to reassign documents to a new form, see “Adding automation toyour application.”


2. In the Design pane, click Forms.

3. Select the form you want to delete.


Tips for designing forms

Placing elements on the formUse the ruler to set tabs and to position elements. Choose View - Rulerto see the current paragraph settings.

Use tables to align elements on a form. Nested tables give you veryprecise control over how you present content. In addition, you can usetables to create certain text effects, such as having text wrap around apicture.

Group related information together. Use sections for approvals or otherspecial access needs. Create subforms that group design elements youuse in multiple forms.

When designing multiple forms for an application, locate particularfields, especially data such as name, department, current date, and duedate, in a consistent place and a consistent order.

Place hidden fields together at the bottom or top of a form. Assign adifferent text color to hidden fields.

Computed fields are evaluated from the top down and left-to-right.Place dependent fields after the fields they depend on. Forgetting thisrule is a common source of problems.

Use centered text at the top of a form only. It tends to get lost whenused farther down on the form.

Use consistent spacing between elements, and avoid crowding theinformation together.

Hide elements that users don’t need to see when they are editing,reading, or printing. In particular, hide nonessential graphics whileprinting.

Provide actions and hotspots to let users take action quickly.

Use collapsible sections to organize a form and make it easier for usersto see the information they need. Set the section properties to expandthe section in one context and collapse it in another.


Naming formsEach 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 willautomatically prepend “Copy of” to the form name to keep the namesunique. If you create multiple databases that contain the same information,use the same names for the forms. Standard names enable users torecognize commonly used forms; they also make it easier for users withsimilar databases to communicate. For example, suppose you have fourcustomer-tracking databases, one in each regional sales office. If theSouthern regional manager wants to discuss a shared account with theWestern regional manager, both managers should know what a “CompanyProfile” document is.

To name or rename a form, choose Design - Form Properties and enter a name for the form.

Name requirementsThe name is case-sensitive and can be any combination of characters,including letters, numbers, spaces, and punctuation.

The full form name, including all synonyms and the cascading name,cannot exceed 256 bytes. If you’re using multibyte characters, 256 bytesis different from 256 characters.

Only the first 64 characters of a form name appear in the Create menu.

Creating aliasesA form can have additional names (aliases). Using aliases lets you changethe form name that appears on the Create menu without having to rewriteevery formula that references a form name. It also lets you reassign existingdocuments to the new form, and rewrite formulas or reassign documents ifthe form name is translated. The the form name and its aliases are separatedby a vertical bar |.

If a form has only one name, it appears on the Create menu and in thedocument’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. Inthose cases the middle names are ignored. As long as the alias does notchange, documents will display using the original form and all formulasreferencing the form will continue to work.


To add an alias1. Choose Design - Form Properties.

2. In the name field on the properties box, add a | (vertical bar) to theright of any other names.

In the following example, Interview is the alias and Main Topic is theoriginal name:Main Topic | Interview

Form names and keyboard shortcutsWindows users can select a menu item quickly by typing its keyboardshortcut (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 letterthat you want to use. Each keyboard shortcut must still be unique withinthe form list. For example, to force the letter “v” as the keyboard shortcutfor the Interview form, enter the name as:

Inter_view

Ordering forms on the Create menuA form structures the data for a document that a user creates. In a Notesclient application, a user chooses a form from the Create menu to create anew document. The Create menu sorts form names in alphabetical order. To display the forms in a different order — for example, with the mostfrequently used form appearing first — precede the form name with anumber or a letter to force the forms into the correct sequence. If a databasehas too many forms to display all the forms neatly on the Create menu, youcan design a cascading menu to group the related forms under one menuitem. The Mail (5.0) template uses cascading workflow forms. When userschoose Create - Workflow, they see these form choices:

Workflow\BookmarkWorkflow\Phone MessageWorkflow\Task

To create a cascading menu for Notes clients1. Open the form.


3. In the form name box, enter the name of the menu item you want toappear 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 formname, as in: Service Request\Hardware|HW, where HW is the alias.

4. Make sure the option “Include in Menu: Create menu” is checked.


To move a form to the Create - Other menu in Notes clientIf 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.


3. On the Form Info tab, select “Include in Menu” and select “Create -Other dialog.”

To remove a form from the Create menu in Notes clientRemoving a form from the Create menu hides the form from all users. Forexample, the Mail template hides the NonDelivery Report and ReturnReceipt forms because only the Notes Mail Router uses them. Forcompatibility with earlier releases of Notes, putting parentheses around the form names when you name a form will also remove forms from theCreate menu.

1. In the Form Properties box deselect “Include in Menu.”

2. Save the form.

To hide a form from only some users, use a create access list.

For more information about create access lists, see Managing DominoDatabases.

To hide a formAnother way to remove a form from the Create menu is to hide it. Hidingallows you to specify conditions under which the form is hidden ordisplayed. For example, you can hide a form from Notes clients, but displayit 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 browsersIn Web applications, users do not have access to the Notes menu structure,so you must provide a mechanism for users to create and edit documents.For example, you might design a view action users use to create adocument, and a button on the form to edit the document.


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

To make a form available to Web usersYou must use this technique to allow Web users to create a document froma 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 theevent with a formula or script that creates a document from the form.

For example, this formula opens a new Main Topic document in thecurrent database:@Command([Compose];"Main Topic")

Use this formula to compose a document in the current database:@Command([Compose];"formname")

Use this formula to compose a document from another database:@Command([Compose];"":"database";"formname")


Selected form properties

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

To open the Form Properties box1. Open the form.

2. Choose Design - Form properties.

Protecting author/editor anonymityIf you want a document’s author or editors to remain anonymous, define aform that doesn’t record the names of people who create or edit it. Forcomplete anonymity, be sure that the author name does not appearelsewhere on the document — for example, in a visible computed field.

On the Form Info tab, select “Anonymous Form.”

Consolidating replication conflictsA replication-or-save conflict occurs when users in different locations editthe same document. One version becomes the main document, and theothers become conflict documents that are marked with a diamond in the view.

You can design a form that merges replication conflicts into a singledocument where possible. In this case, if two users edit different fields in the same document, Domino saves the edits to each field in a singledocument. However, if two users edit the same field in the same document,Notes saves one document as a main document and the other document asa response document marked as a replication conflict.

On the Form Info tab, select “Merge replication conflicts.”

For more information on replication conflicts, see Notes Help.

Opening documents in edit mode automaticallyFor users’ convenience, you can specify that documents created with a formautomatically open in edit mode.

On the Defaults tab, select “On Open: Automatically enable EditMode.”

Generating HTML for hidden fieldsWhen checked, this form property generates HTML information abouthidden fields on a form. This allows document behavior in a Webapplication to more closely match document behavior in a Notesapplication. For example, if you create a form that relies on a hidden fieldfor a calculation, that form may not behave as expected in a Webapplication in certain situations. By generating HTML for the fields, theinformation is available for Domino to successfully complete the


calculation. The HTML generated for the hidden fields is also accessiblethrough JavaScript, so you can change the value or find out the state of ahidden field with a script. Checking this option creates larger files on theWeb and may decrease application performance. Consider security, sinceinformation in hidden fields, though not visible in the browser, is visiblethrough the “View Source” menu item on the browser.

To generate HTML for hidden fieldsOn the Defaults tab, in the For Web Access section, check the option“Generate HTML for all fields” and deselect the option “Treat documentcontents as HTML.”

Defining a header on a formIf you are designing a form for use in a Notes application, you can define aheader that does not scroll off screen when the user scrolls down the formor document created with that form. For example, in the Notes mailtemplate, a header displays all of the information contained in the mailsender and recipient fields. This section remains static while you scrollthrough a mail message. Headers can contain any element that a form cancontain. The only caveat is that a table cannot be the first element in aheader; 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 theheader region of the form.

2. Move the cursor to the line below where you want the header to start.


4. On the Header tab, select "Add header for form," to mark off the headerarea.

5. Set the display properties for the header.

Height can be set in pixels as a percentage of the form height, or to fitcontents.

Select a scrolling option. Auto automatically turns scrolling on whenthe content of the header exceeds the space allotted.

“Allow resizing” lets users resize the header area.

“Border” controls the display of the dividing line between the headerand the body of the form. You can turn the border off or change thethickness and color.

Displaying a graphic in a headerTo 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 backgroundgraphic.


Creating a print header and footerYou can define a header and footer that will print on all documents createdwith that form. Headers and footers are not supported for Webapplications.

1. On the Printing tab, click Header and type the header and/or clickFooter and type the footer.

2. Click the icons to add the page number, date, time, and so on.

3. (Optional) Assign a font, size, and style for header or footer text.

Header and footer alignmentHeaders 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 firsttab is left justified; text between the two tabs is centered; and text to theright of the second tab is right justified. For example:

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

|URGENT| — Centers the text URGENT.

||URGENT — Right justifies the text URGENT.

Creating a response hierarchyIf you are creating an application that requires users to create a documentand then post responses to that document, and responses to the responses,you will need to set up a hierarchy between the forms. There are three typesof forms you can designate:

Main topic form - The top level in a hierarchy of forms. It can have zeroor more response forms associated with it.

Response form - Creates response documents associated with a maindocument. In a view, response documents appear under whichevermain document is highlighted when the user composes a response.Designers often create response documents that inherit data from themain document — for example, the topic title.

Response-to-response form - Creates response documents associatedwith either a main document or a response document.

A form creates main (parent) documents unless you designate it as a formthat creates response documents. For information on indenting responsedocuments under its parent document in a view, see “Designing Views.”


To designate a response or response-to-response form1. Open a form.


3. In the Type field on the Form Info tab, do one of the following:

Select “Response” as the type to use the form to create responses tomain documents.

Select “Response to Response” as the type to use the form to createresponses to main documents and other responses.

To inherit a parent document into a new documentTo make it easy for users to find a related document, a document caninherit a parent or related document as a link, as collapsible rich text, or asrich text. For example, a new response document can include a link to itsmain document. A link takes up less disk space than including the full orcollapsed contents of a parent document because Domino stores only apointer to the document rather than a copy of the document.

Once inheritance is enabled, whichever document is highlighted when theuser chooses Create - <response/new form name> becomes the parentdocument. The documents do not need a main document/responsedocument relationship, whichever document is highlighted is assumed tobe the parent document. A user can suppress inheritance by pressing CTRLwhile choosing Create.

1. Open the form.

2. Create a new rich text field to display the document or link.


4. Click the Defaults tab.

5. Select “On Create: Inherit entire selected document into rich text field.”

6. Select or enter the name rich text field you created in step 2.

7. Select one of the following:

Link

Collapsible rich text

Rich text

8. (Optional) Select “On Open: Show context pane” and Parent.

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


To designate a form for version tracking1. Open the form.


3. On the Form Info tab, select a Versioning method and a Create versions option.

There are different versioning methods:

New versionsbecome responses

Use this when the original document is the most important.The original document is listed first in the view; all successiveversions follow. Choose this method if the original document is the focal point of the view, with responses being used forreference.

When new versions become responses, you can preventreplication or save conflicts in the view. If users on differentservers modify and save the main document, their versions are treated as two separate response documents when thedatabases replicate. The two responses are displayed in theview in chronological order.

Prior versionsbecome responses

Use this when the new version is the most important. Thelatest version is listed first in the view; previous versions andthe original follow. Use this if the update is the mostimportant or most frequently read document and you want tostore older versions as a backup or for historical reference.

When prior versions become responses, you can’t preventreplication or save conflicts. If users on different serversmodify and save the main document, the two new versions of the document appear as conflicting main documents whenthe databases replicate.

New versionsbecome siblings

Use this when all versions have equal importance. The original document is listed first in the view; all successiveversion follow as additional main documents withoutintroducing 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 formwhere workgroup members create their own replacementversions of an original document or where the originaldocument is used as a template for each new document.

This method is most effective when you don’t expect everymain 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 documentfrom the original document, add identifying information, suchas “New Proposal” or “Revised” to the field that displays inthe view.


There are two create versions options:

Manual - File, NewVersion

Manually creates a new version of the document onlywhen the user chooses File - Save As New Version. Thisoption allows the user to choose when to create a newversion and when to overwrite the existing document.

Automatic - File, Save Automatically creates a new version of a document eachtime the user saves a document.

Make sure users understand that version tracking is active, so that theyunderstand the impact of editing documents. Explain version tracking inthe Using Database document.

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

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 thetitle bar. To help users understand the context of the document they’rereading, 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 aformula you create. An example of a dynamic window title is a title for amain document in a discussion database that includes the number ofresponses to the document. The title changes each time a new response getscreated.

To create a window title, you write a formula that supplies the text todisplay. The text can be a text string you enter directly, text that resultsfrom a function, or the contents of any field type except rich text. If the fielddoes not contain text or if a function does not return text, you must convertthe value to text using the @Text function. For example, the followingformula 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 title1. Open the form.2. On the Object tab of the Info List in the Programmer’s pane, select the

Window Title - attribute.3. In the Script area of the Programmer's pane, enter text enclosed in

quotation marks or a formula that evaluates to text.


4. Click the check mark to save the formula.

5. To test the window title, create, save, and read a new document. Makesure the title is appropriate for all three situations.

For more information on creating window title formulas, see theProgramming Guide.

Examples: Customizing window titlesTitle includes creation date and company nameThis formula displays the date the document was created, form name, andcompany that was billed. @Text converts the date to a text string, and theextra spaces within the quotation marks force the words in the title to beproperly spaced.

@Text(@created) + " Inventory Invoice for " + CompanyName

This formula uses the field “form” to refer to the form name instead of hardcoding it into the formula.

@Text(@created) + " " + form + " for " + Company Name

Title includes number of responsesThis 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 barwhile the user composes the document. After the document is saved, thetitle is the subject combined with the number of responses. If the subject isIcebox 2000 and there are no responses, the title of the document is Icebox2000 (No Responses). With one response, the title becomes Icebox 2000 (1Response). With two responses, the title becomes Icebox 2000 (2 Responses).

Response includes the subjectWhen the response or response-to-response is first composed, this formuladisplays New Response To and the subject of the main document.

@If(@IsNewDoc;"New Response to " + Subject;"Response " + @DocNumber("") + " of " + @DocSiblings + " to "+ Subject);

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


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 saveredesign time. When you change a field on a subform, every form that usesthe subform updates. Common uses of subforms include adding a companylogo to business documents or adding mailing label information to mail andmemo forms. A subform can be a permanent part of a form or can appearconditionally, depending on the result of a formula. For example, you mightoffer users a choice of custom mail forms with different graphics and stylesfor various types of mail messages, such as memos, alerts, or letters. Fieldnames used in the subform can’t be used elsewhere on the form. Changesyou make to a subform affect all forms and documents that use thesubform.

Creating a subformYou can copy and modify a subform that is similar to the one you need orcreate a new subform and design it yourself.

1. Select the database that will have the new subform and click Resources - Subforms.

2. Click the New Subform button.

3. Create the subform using the same elements you use to create a form.

4. Choose Design - Subform Properties.

5. Enter a name for the new subform.

6. Choose display options for including the subform in the Insert Subformor the New Form dialog box.

7. Close and save the subform.

Display options for subformsThe following options do not apply to computed subforms.

Select “Include in Insert Subform dialog” so designers see it wheninserting a subform. Excluding a subform from the Insert Subformdialog box is not a security measure. Users with Designer access orhigher can open any subform in Designer and copy individualcomponents.

Select “Include in New Form dialog” if you want the subform to appearimmediately when designers choose Create - Design - Form.


Displaying a subform on a form

To insert a subform1. Open the form.

2. Click where you want to paste the subform.

3. Choose Create - Insert Subform.

4. Select the subform you want and click OK.

To display a computed subform1. Open the form.

2. Click where you want to paste the subform.

3. Choose Create - Insert Subform.

4. Select “Insert Subform based on formula.”

5. Click OK.

6. Enter a formula in the Programmer’s pane that determines whichsubform to display.

7. Close, name, and save the form.

Example: Displaying a computed subformIn the Main Topic form of a discussion database, you want to display theNewDocSubform if a document is new and the SavedDocSubform if thedocument has been saved. Each subform contains different fields andgraphics. The Insert Subform formula is:

@If(@IsNewDoc;"NewDocSubform";"SavedDocSubform");

Deleting subformsWhen a user opens a document that references a deleted subform, themessage “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, themessage “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 thesubform.

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


To delete a subform from a formYou can remove a subform from an individual form, without disturbingother forms that use it.

1. Click the subform area on a form.2. Choose Edit - Clear.3. Adjust the formatting if necessary.

To delete a subform from a databaseYou can remove all instances of a subform from a database. Be aware thatthis will cause errors in any form that refers to the subform.

1. Click Subforms in the design list for the database.

2. Choose Edit - Clear.

Layout regionsA layout region is a design area on a form that affords flexibility forcombining and arranging text and graphics. Layout regions are notsupported in Web applications.

A layout region can contain:

TextGraphics (either in the background or as graphic buttons)Fields (except rich text fields and dialog list fields)Buttons

You cannot add the following elements to a layout region:

AttachmentsHorizontal RulesHotspotsJava AppletsLinksOLE ObjectsPage BreaksPop-upsSectionsShared ActionsShared FieldsSubformsTables


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

Creating a layout region

To create a layout region1. Open the form.

2. Move the cursor to the location in the form where you want to place the layout region.

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

To delete a layout region1. Click the layout region and choose Edit - Clear.

2. Adjust the formatting if necessary.

Aligning and rearranging elements in a layout region1. Open the form.

2. Click the layout region and choose Design - Layout Properties.

3. Click Show grid to see the current spacing between elements.

4. Do one or more of the following:

Click “Snap to grid” to align all elements with the grid.

Change the grid size if you want a narrower or wider arrangement of elements.

Click and drag an element to move it to a new location within thelayout region.

Click an element and choose Design - Send to Back to move it behindother elements.

Click an element and choose Design - Bring to Front to move theelement on top of others.

Changing the size and style of a layout regionYou can adjust the size, position, and look of a layout region.

1. Open the form.

2. Click the layout region and choose Design - Layout Properties.

3. Select a different Left setting to move the layout region horizontally.Elements within the layout region stay in a fixed position, relative to the borders of the layout region.

4. Select a different Width or Height setting to size the layout regionperimeter.


5. (Optional) Deselect “Show border” to make the layout region bordersinvisible.

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

Adding a graphic to a layout region1. Move the cursor to approximately where you want the graphic to

be in the layout region. Once the graphic is in, you can move it bydragging it.

2. Choose Create - Picture and select the graphic file.

3. Select either Graphic or Graphic button.

4. Edit the layout options to change the size or position of the graphic.

5. (Optional) Click the Hide tab to adjust the hide properties.

6. (Optional) Choose Design - Send to Back to position the graphic behindother elements.

Adding a graphic button to a layout regionA graphic button adds a hotspot to a layout region.

1. Copy a graphic to the clipboard.

2. Move the cursor to approximately where you want the graphic buttonto be in the layout region. Once it is pasted in, you can move it bydragging it.

3. Choose Create - Layout Region - Graphic button.

4. From the Objects tab on the Info List in the Programmer’s pane, selectHotspot - Click.

5. In the Script area of the Programmer’s pane, enter a formula for whatyou want the hotspot to do.

6. Edit the layout options to change the size or position of the graphicbutton.

7. (Optional) Click the Hide tab to adjust the hide properties.

8. (Optional) Choose Design - Send to Back to position the graphic behindother elements.


Embedded Controls

There are two types of embedded controls that can only be used on a form:

The file upload control - allows you to create a form so that Web userscan attach files to documents

The group scheduler - allows you to create a form that displays theschedules of specified users

Adding a file upload controlTo allow Web users to attach files to documents, include a file uploadcontrol on a form. When Web users create a form or open a document inedit mode, they can attach a file by typing the path and file name or byclicking Browse and selecting a file from the filing system. The serveradministrator must also define a temp directory on the server. If thedirectory doesn’t exist, the attachment is not saved with the document. Thefile upload control is not supported in the Notes client.

1. Open the form to which you want to add the file upload control

2. Move the cursor where you want the upload control to display.

3. Choose Create - Embedded Element - File upload control.

4. Select the control and right click to open the File Upload ControlProperties box.

5. On the Hide tab select, “Hide paragraph from Notes R4.6 or later.”

Adding a group schedulerThe group scheduler allows you to design a form for the Notes client thatdisplays the schedules of users. For example, you can create a form forusers to schedule department meetings. Embedding a group scheduler onthe form lets users check everyone’s schedules before planning the meetingtime. Also, within the group scheduler users can click on a person’s name toopen that person’s calendar view (provided the user has been given accessin the person’s mail preferences). You can program the calendar to open ina separate frame, or in its own window.

There are three parts to using group scheduler:

Embed the group scheduler on a form.

Create the fields that collect the data for the group scheduler’s display.

Program the group scheduler to retrieve the data from the fields.


Creating a group scheduler on a formOnly one group scheduler can be embedded per form.

1. Open or create a form for the group scheduler.

2. Move the cursor where you want the group scheduler to appear on the form.

3. Choose Create - Embedded element - Group Scheduler.

Note The group scheduler does not display scheduling information whileyou are designing the form.

Creating fields for the group schedulerThe group scheduler needs three pieces of information before it can displayanyone’s schedule.

Whose schedule to display (individuals or group).

What week to start the schedule information from.

How many hours per day of schedule information to display.

One way to collect this data is to create editable fields on the form and haveusers enter in those fields the information they want displayed. You canalso use LotusScript or the Formula language to create the field items. Foran example of collecting the data using an action button and Formulalanguage, look at the GroupScheduler form in the Mail5.0 Template.

Once you have created the fields or other method for collecting the data,associate those fields with the Group Scheduler attributes.

Programming the group schedulerOnce you have created the fields for collecting the data, you must programthe group scheduler so that it can retrieve the data from the fields. Thegroup scheduler has three attributes that must be programmed:

Group member items — Points the group scheduler to where the data isfor whose schedules are displayed

Start time item — Points the group scheduler to where the data is forthe week the scheduler should start the display from

The group scheduler displays one week of scheduling information at atime. The Notes Preference settings for the user accessing the formdetermines the day of the week that the display starts on.

Duration item — Points the group scheduler to the data that determineshow many hours to display for each day


To associate the fields with the attributes, select the attribute from Objectstab of the Info List and enter a field name in quotation marks in the Scriptarea of the Programmer’s Pane.

Group Member itemsWhen a user creates a form containing the group scheduler, the groupscheduler evaluates the contents of this attribute to determine the locationof the data that indicates whose schedules to display. When the groupscheduler finds the field, it returns scheduling information for those peoplewhose names or group name is specified in the field. If the contents of thefield contains a group name, the group is expanded into its individualmembers, each of whose scheduling information is displayed. If you arewriting a LotusScript formula to obtain the data for this attribute, theformula must evaluate to a text list of one or more field names.

Start Time itemWhen a user creates a form containing the group scheduler, groupscheduler examines the contents of this attribute to determine where to findthe data for the date and time on which to begin the display. The value ofthis field should be a date and time. If the value is not a date and time, thecurrent date and time of the user’s system is the default. If the value is adate only, that date and the current time on the user’s system are thedefault. If the value is only a time, that time and the current date on theuser’s system are the default.

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

Note 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 appearfree between 12 and 8 to an EST user.


Duration itemThis attribute is examined to determine where to find the data for howmany hours of each person’s schedule to display. The value of this fieldshould be an integer between 1 and 24, inclusive. A value less than 1 will be defaulted to 1 and a value greater than 24 will be defaulted to 12.

Setting a refresh modeWhen a user creates a document that contains a group scheduler, the groupscheduler retrieves the scheduling information from the mail servers of thegroup members. The user can change any of the scheduling informationdisplayed by changing the values in the fields. When any of the informationin the fields used by the group scheduler changes, the user must refresh thedocument to see the changes reflected in the scheduler display. The defaultrefresh mode is a full refresh. That is, whenever a user refreshes, all threepieces of scheduling information are updated regardless of which fieldshave been changed. This includes retrieving the scheduling data for allgroup members. Therefore, it could unnecessarily affect performance if all a user did was change the value in the duration field.

To limit the refresh, add an optional, reserved field on the form named $GroupScheduleRefreshMode. This field controls how the group scheduler refreshes the scheduling information. The value of$GroupScheduleRefreshMode can be “0” or “1.”

If the value of $GroupScheduleRefreshMode is “0”, the group schedulerperforms a partial refresh which refreshes only data in the field that haschanged. This is useful when the users have added or deleted a groupmember or changed the duration item or start time item. If the value of the$GroupScheduleRefreshMode field is “1”, group scheduler will update alldata for all members on refresh.

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

Setting properties for the group schedulerUse the Group Scheduler Properties box to set the following properties forthe group scheduler:

Target frame - Clicking on a group member’s name in the groupscheduler opens that member’s calendar in its own window. You canspecify a target frame to display group members’ calendar views andappointment documents.


Size - Set the horizontal size as either a percentage of the window widthor a fixed width. Set the vertical size to fit to contents (number of groupmembers) or a fixed height. If you select fixed height, the schedulerdisplays a scroll bar if all of the members do not fit on the screen.

Color - The group scheduler uses a number of colors to displaycalendar information. All of the colors can be customized on theBackground tab of the properties box.

For an example of a group scheduler form, see the Group Calendar form in the Mail (R5.0) template.

Profile formsProfile forms are forms that collect user-specific or database-specific values.These values are stored and retrieved in Profile documents. What sets thesedocuments apart as profile documents is not the form they are created with,but rather the way the documents are displayed and values in the fieldspassed 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 thatform is available to all users.

Profile documents allow for quick data retrieval, because they are cachedwhile 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 thedatabase. Users create profile documents through an action button or agentyou design that uses LotusScript or the formula language.

A database can have a single profile document or multiple profiledocuments 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 multipleprofile documents depends on your design needs. Use a single profiledocument to contain settings that all documents in the database need, such as environment variables. Use multiple profile documents for morecustomizable settings, such as user preferences. A user must have at leastAuthor access in the access control list (ACL) of a database to create aprofile 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 orNotesDatabase GetProfileDocument in a LotusScript program to create orretrieve a document. In each case, Notes looks for a profile document withthe form name you specify, and creates a profile document if one does


not already exist. For an example of a profile document, see the InterestProfile form in the Discussion - Notes & Web (R5.0) template. For moreinformation about accessing or editing a profile document using Formulalanguage or LotusScript, see the Programming Guide.

Creating a profile form1. Create a form with fields to hold the values you want to store in profile

documents.

2. Choose Design - Form Properties and deselect “Include in Menu.”

3. Save the form.

4. Do not include the form in any view. For more information, see“Designing Views.”

5. Create a button, action, or agent that uses either the LotusScript NotesDatabase GetProfileDocument method orUIWorkspace.EditProfile, or the Formula language @CommandEditProfile to create or access the document.

See the Programming Guide for more information about Formula languageand LotusScript.

You can create or edit a profile document using @Command([EditProfile])or @SetProfileField. You can retrieve field values from an existing profiledocument using @GetProfileField. For full syntax descriptions, see thetopics for these commands in Help.

Use the SetProfileField and GetProfileField commands to set and retrievefield values from a profile document. A SetProfileField command alsocreates a profile document if none exists.

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

If you prefer scripts to formulas, use LotusScript routines to create and editprofile documents. The EditProfile method of the NotesUIWorkspace classproduces the same result as the @Command([EditProfile]) command usedin a formula.

To set or retrieve field values for a profile document with a script, use theGetProfileDocument method to get a handle to the document. You can thenretrieve values from the document or set new ones, just as you would withany document.

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

For information on creating or editing profile documents using an@Command formula or a LotusScript program, see the Programming Guide.


Designing forms that prompt users for input

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

Designing a form that presents a dialog boxTo help users to fill out documents, create a custom dialog box that promptsfor specific input. You can do this by using the @DialogBox function orLotusScript. Using @Dialog requires two forms: one, the dialog form, has alayout region that contains fields, text, and graphics, and looks like a dialogbox; the other, the host form, contains a button that uses @DialogBox todisplay the dialog form. The two forms contain shared fields, and whenusers enter field values in the dialog form, the values are shared with fieldson 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 formcalled “Memo Options.” Both forms have a field called “Comments.” Textentered into the Comments field in the Memo Options form also appears inthe Comments field in the Memo document.

When using @DialogBox, all values entered in the dialog box are stored inthe document created with the host form and can be seen in its DocumentProperties box even if the fields do not appear on the host form. If thekeyword [NoNewFields] is used with the @DialogBox function, the fieldsthat are on both the host form and the dialog form will be updated whenthe dialog form is saved or refreshed. If [NoFieldUpdate] is used, no fieldsor field values from the dialog box form will be updated on the host form.

Layout regions are supported in Notes applications only. To create a dialogform for use on the Web, design the dialog form with a table instead of alayout region, and follow steps 8 through 11 for calling the dialog formfrom a host form.

1. Open or create the dialog form.2. Choose Create - Layout Region - New Layout Region.3. Drag the layout region to the dialog box size you want.4. Choose Design - Layout Properties.5. Deselect Show border and select 3D style.

6. Click the layout region and then create the graphics, text, and fields forthe dialog box.

7. Close and save the form.8. Double-click the host form that will display the @DialogBox button.

9. Click where you want to add the button, and choose Create - Hotspot -Button.


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

Guidelines for designing a form that presents a dialog boxTo match the Notes user interface as closely as possible, follow theseguidelines:

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 layoutregion most closely resembles a dialog box. A layout region that is 3inches square is big enough to display a few fields and two or threebuttons.

In the @DialogBox formula, include the [AutoVertFit] and[AutoHorzFit] options to size the dialog box to fit the layout region.

Use 9 point Helvetica for static text, fields, and buttons.

Place static text labels above or to the left of fields and end them with acolon (for example, Name:).

Place buttons at the bottom of forms.

OK and Cancel buttons appear automatically to the right of the layoutregion. If you do not want the cancel button to appear, use the@DialogBox keyword [NoCancel]. If you do not want the OK or theCancel button to appear use [NoOkCancel].

To arrange choices horizontally, use the multi-column display optionwith radio button and check box field; use None for the frame option sochoices blend with the dialog box background.

For button text with multiple words, use initial capital letters. Useellipses for buttons that lead to another dialog box or task — forexample, “Show Details...”

Designing a form that prompts users for informationYou can design a form that uses @Prompt to request information from usersto help them fill out a document. This function is similar to @DialogBox, butit is simpler: @Prompt contains only text and doesn’t interact with any otherforms.

1. Create a field, button, hotspot, or action that will store the @Promptformula.

2. Double-click the field, button, or hotspot.

3. In the Programmer’s pane, select Run Formula.


4. Enter a formula in the Script area using @Prompt.

5. Close and save the form.

For more information on the @Prompt command, see the ProgrammingGuide.

Examples: Using @Prompt[YesNoCancel]This formula displays a warning before sending the memo and gives theuser a chance to select Yes, No, or Cancel.

Result := @Prompt([YesNoCancel]; "Send memo?"; "This memo willbe 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, Notescancels the formula evaluation.

FIELD Name := @Prompt([OkCancelEdit]; "Enter Your Name"; "Typeyour name in the box below."; @UserName);

[OkCancelList]This formula captures the user’s response in a temporary variable calledComposeType and uses it to create a new report using the appropriateform.

ComposeType := @Prompt([OKCancelList]; "Report Type"; "Choosea report type."; "Adjustment Report";"AdjustmentReport":"Infant Progress Report":"Toddler ProgressReport":"Preschool Progress Report":"Transition toKindergarten Report");@Do(@Command([Compose]; ""; ComposeType));

Designing a form that lets users make selections from a viewYou can design a form that uses @PickList to display a list of choices from aview. These steps assume you have already created a field, button, hotspot,or action to store the @PickList formula.

1. Open the form.

2. Choose View - Action Pane and double-click the action, or double-clickthe form and click the field, button, or hotspot.

3. In the Programmer’s pane, click Formula.

4. Write a formula using @PickList and the [Custom] parameter, unlessyou want to use [Name] to display a Domino directory or personalname and address book.



Using @PickListThe @PickList function looks up the values in a view as @DbColumn does,but lets the user pick a value from one document. This is similar to using@Prompt in a form, but is specifically for use with views.

@Picklist offers the following advantages over formulas that use@DbColumn or @DbLookup.

It is not limited to 64K of data.It is faster than @DbColumn or @DbLookup.It allows users to type the first few characters of an entry to find itquickly in the view.

For more information on the @Picklist function, see the Programming Guide.

ExampleThis 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 toorder" ; 1 );

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

Field name Result of adding this field to a form

$ChargeRead Domino creates a billing record when a user opens a documentthat contains this field

$ChargeWrite Domino creates a billing record when a user creates, copies, edits,or saves a document that contains this field

To specify which documents to charge for1. On the form that you want to track, create a field named $ChargeRead

or $ChargeWrite.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 one of thesefields, the billing task retrieves the cost value in this field and places itin a document billing record.

6. Save the form.


Note If there are many documents for which you want to charge, you cancreate a shared field and add it to multiple forms. If a database is updatedby a template, you can modify the template to include the hidden fields.

For more information on setting up billing, see “Setting up billing” inAdministering the Domino System.

Customizing “Form processed” confirmation for the WebAfter Web users submit a document, Domino responds with the defaultconfirmation “Form processed.” To override the default response, add acomputed text field to the form, name it $$Return, and use HTML as thecomputed value to create a customized confirmation.

Displaying a personalized responseThe following $$Return formula returns the response “Thank you,” andappends 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>");

Linking to another pageInclude HTML with a URL to link to another page based on field values inthe submitted document. The following $$Return formula returns aresponse based on the region the user selects. For example, if the userselects Europe, the message “Visit our site in Italy” displays with a link tothe Web site in Italy. (Assume that “stdAnswer” and “stdFooter” aredefined earlier in the formula.)

@If(Region="Asia"; stdAnswer + "<h2>Visit our site in <a href=\"http://www.japan.lotus.com\">Japan</a></h2>" +stdFooter;

Region="Europe"; stdAnswer + "<h2>Visit our site in <a href=\"http://www.lotus.com\it_ciao/it_ciao.htm\">Italy</a></h2>" + stdFooter;stdAnswer + stdFooter);

Returning another pageTo jump to a different Web page, enclose a URL for the page in brackets.When the user submits the document, the Web client displays thereferenced document. For example, the following $$Return formuladisplays the home page for the Lotus Japan site.

"[http://www.japan.lotus.com]"


Customizing search formsYou can customize Domain Search forms to meet the needs of yourorganization. The forms used for a Domain Search are Search Form,SeachResults, ResultEntry, and DetailedResultEntry, and they reside in theCatalog (R5.0) template. To customize the forms, create a database based on the template or copy and paste the forms into the domain catalog on theDomino server you are using for Domain Search.

Refer to the following table if you are customizing a search form for use on the Web. The table lists the URL commands used on the Search Queryform to drive the initial search through the SearchDomain URL. They areavailable on the results page for use by buttons and hotspots in the resultsform. For example, you may specify &SearchOrder=2 on your initial searchform. 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 oroverride it by specifying something else.

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

URL Commands Description Default Value

Query The search string none

SearchMax Maximum number of entries to return in total; 0 = no limit

none

SearchWv Include word variants: TRUE or 1 or FALSE or 0 TRUE

SearchOrder 1 = by relevance2 = by date ascending3 = by date descending

1

SearchThesaurus Use thesaurus synonyms: TRUE or 1 or FALSE or0 (This option is ignored by the R5 search engine)

FALSE

SearchFuzzy Use fuzzy search: TRUE or 1 or FALSE or 0 FALSE

SearchEntry Name of form to use for each result entry “ResultEntry”

Start Start document for paged results; 0 = unpaged 0

Count Number to return for paged results; 0 = unpaged 0

Scope Scope of search: 1 = notes databases only2 = filesystem only0 = both

0

If you are customizing a search form for use on in a Notes client, you willneed to use the FTDomainSearch method.

For more information about using the FTDomainSearch method, see theProgramming Guide.


Customizing search results formsSearch results are displayed using the SearchResults form, the ResultEntry,and the DetailedResultEntry form. The SearchResults form defines thelayout of each page of results. The ResultEntry and DetailedResultEntryforms defines the format of a single result within that page, and is repeatedfor each result returned. On the Web you specify the name of this formthrough the SearchEntry field/argument. The fields below are for theResultEntry and DetailedResultEntry 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 orfile system document

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

How the SearchResults and ResultEntry/DetailedResultEntry forms are used.The LotusScript below is attached to the click event of the Search actionhotspot used by the Notes client on the search form. The lines that call thename of the results form and the result entry form are underscored.

Sub Click(Source As Button)Dim s As New NotesSessionDim db As NotesDatabaseDim w As New NotesUIWorkspaceDim uidoc As NotesUIDocumentDim q As StringDim l As IntegerDim d As IntegerDim sort As StringDim stype As Integer


Dim useint As IntegerDim rtype As StringDim rformname As StringSet db=s.CurrentDatabaseSet uidoc = w.currentdocumentuidoc.refreshSet doc=uidoc.Document

q=doc.query(0)l=doc.resultlimit(0)d=doc.MaxDisplay(0)sort = doc.sort(0)usestr = doc.usesscope=doc.searchscopertype=doc.GetItemValue("SearchType")(0)

If rtype = "1" Then

rformname="DetailedResultEntry"Else

rformname="ResultEntry"End If

Select Case sortCase "R"

stype = FT_SCORESCase "O"

stype = FT_DATE_ASCCase "N"

stype = FT_DATE_DESEnd Select

Forall values In usestr

If values = "2" Then useint = useint + FT_STEMS

If values = "3" Then useint = useint + FT_FUZZYEnd Forall

Forall values In sscope

If values = "1" Then useint = useint + FT_DATABASE

If values = "2" Then useint = useint + FT_FILESYSTEMEnd 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 Formproperties box to preserve field values when data is passed between a Webbrowser and the server.

Using navigational buttons for paged resultsTo make it possible to navigate forward and backward between pages ofresults, add buttons or hotspots to the SearchResults form. The fieldsavailable for use with next and previous buttons are listed in the tablebelow. In the Notes client, the buttons should reinvoke the LotusScriptFTDomainSearch function with revised arguments. On the Web they shouldbe 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 Databaseproperties. If selected, a URL attached to a hotspot or button will becomputed on the click event. If it is not selected, the URL will be computedwhen the page is loaded.

Query Search string used

Start Starting document number

Count Number of results requested for this page

Hits Actual number of results returned this page, may beless than Count

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

Include word variants: 1 or 0

SearchOrder(only for URL command)

1 = by relevance2 = by date ascending3 = by date descending

SearchThesaurus(only for URL command)

Use thesaurus synonyms: 1 or 0

SearchFuzzy(only for URL command)

Use fuzzy search: 1 or 0

SortOptions(only for Notes client)

FT_SCORES = by relevanceFT_DATE_ASC = by date ascendingFT_DATE_DES = by date descending

OtherOptions(only for Notes client)

FT_STEMS = Include word variantsFT_FUZZY = Use fuzzy searchFT_DATABASE = search databasesFT_FILESYSTEM = search filesystems

SearchEntry Name of the Result Entry form used

Scope(only for URL command)

Scope of search: 1 = notes databases only2 = filesystem only0 = both


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

Field Description

Hits The actual number of hits returned. This field is useful in determiningthe Start parameter of Next.

TotalHits The total number of hits returned without regard to paging.

Tips for improving document display timeTo help users create and read documents quickly, follow these guidelineswhen designing forms:

Designing formsAvoid large bitmaps or graphics.

Avoid the form property “Automatically refresh fields.”

Instead, use the “Refresh fields on keyword change” for a choice field,or write a LotusScript field event to recalculate the document or updateother fields when users move from a specific field.

Avoid long tables with many computed fields.

Designing fieldsUse @DbColumn or @DbLookup formulas sparingly, or replace themwith LotusScript programs, which are generally faster and supporterror checking.

Use simple formulas for “hide when” conditions.

Avoid recalculating fields, if possible. Otherwise, change such fields tocomputed-when-composed fields, which calculate only when thedocument is composed but can be updated later if needed throughbuttons, actions, or agents.

Use LotusScript form events rather than conditional formulas in thefield 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 thatuses @If(@IsDocBeingSaved;“x”;“y”).

Minimize the number of fields, especially hidden fields, and use formevents rather than field formulas to execute processing logic and avoidunnecessary recalculations.

For example, suppose a form contains a hidden computed field calledState, which determines where documents are in the workflow and


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

Testing a form before deploying it

There are two ways to test a form before using it in the actual application.You can preview the form from the Notes client or through a Web browserto see how it will look to a user and to make sure form elements areworking. Alternatively, you can put the form through its paces, using it as users will. Testing the form in the application allows you to createdocuments, examine the documents through different views, and test all actions.

For more information about previewing your work, see “Previewing yourdesign work.”


Chapter 6Designing Fields

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

Fields

A field is the part of an application that collects data. You create fields onforms, subforms, or in layout regions. Each field stores a single type ofinformation. A field’s field type defines the kind of information a fieldaccepts, such as text, numbers, dates, or names. When a user, either in aNotes client or a Web browser, creates a form, fills out the information inthe fields, and saves the form, the data in the fields is stored in anindividual document. The contents of the fields can then be displayed indocuments and views or can be retrieved for use in formulas. A field can beused on a single form, or you can create shared fields for use in multipleforms in a database.

When you create a field on a form, you define the following:

Field name

Field type

Display options and field properties

Computed or editable attribute

Formulas or scripts associated with the field

To create a fieldWhen you create a field on a form, the field displays with its namesurrounded by a rectangle and a letter or symbol that lets you know whattype of field it is. You can use tabs, returns, and other formatting tools torefine the field’s position on the form.

1. Open the form.

2. Move the cursor where you want the field to appear.

3. Choose Create - Field.

121

4. On the Field Info tab of the Field Properties box:

Assign a name to the field.

Assign a field type.

Select the display style.

Select Editable or one of the computed options.

5. On the Control tab, select a display option for the field.

6. On the Fonts tab, format the font style for the field.

Copying fieldsIf you copy a field from one place on form to another, each copy of the fieldhas a sequential number appended to its name to preserve nameuniqueness. You can rename the field after copying it. If you copy a sharedfield, the new field changes to a single-use field.

Deleting fieldsTo delete a field, you select the field on the form and press the Delete key orchoose Edit - Clear.

Deleting a field from a form means that data for that field is no longerdisplayed in documents. The data still exists, however, and you can displayit 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 alldocuments containing the field.

For example, to purge the AssignedTo field and its data from all Scheduledocuments, create an agent or action that uses the form name and@DeleteField:

SELECT Form=“Schedule”;

Field AssignedTo:=@DeleteField;

Creating a shared fieldYou can define a field for use on more than one form. For example, manyforms have a creation date field, so you can define this field once and reuseit. When you define a field as a shared field, Designer displays the fieldwith a dark border and adds the field name to a list of shared fieldsavailable for use in a database. Then to insert a shared field in another formin the database, you select the field name from the list of shared fields.

You can design a field specifically as a shared field, or you can convert asingle-use field that is not in a layout region to a shared field.


To create a shared field1. Expand Resources in the Design pane and click on Shared fields.

2. Click the button “New Shared Field.”

3. Enter a name for the shared field.

4. Assign a field type and choose Editable or a computed option.

5. Close the properties box.

To insert a shared field1. Move the cursor where you want the field to appear on the form.

2. Choose Create - Insert Shared Field.

3. Select the shared field you want to use and click OK.

4. (Optional) Type a text label next to or above the field.

5. (Optional) Highlight the label and choose Text - Text Properties tochange the text style.

Copying a shared fieldTo copy a shared field from another database,

1. Open the form you are copying the field from.

2. Select the field and choose Edit - Copy.

3. Open the form you want to paste the field in.

4. Move the cursor to where you want the field to appear on the form.


Cutting and pasting converts a shared field to a single-use field. To turn thefield into a shared field in the current database, select the field and chooseDesign - Share this field.

Renaming shared fieldsRenaming a shared field affects all forms that use the field, as well as anydocuments created with the form. After renaming a shared field, edit eachform that uses the shared field. Delete the old shared field, and insert thenew shared field. Also revise all formulas that refer to the former fieldname. If you already used the form to create documents, create and run anagent to reassign field data to the new field name and to computed fields.

Deleting shared fieldsTo delete a shared field, you select the shared field from the list of sharedfields and choose Edit - Clear.

When you delete a shared field from a form, you delete only the fieldreference from the form. Because other forms may use the shared field

Chapter 6: Designing Fields 123

definition, its definition remains in the database. Unless you delete the fielddata with the @DeleteField function, the data from deleted shared fields canbe displayed again by adding a field of the same name or re-inserting theshared field.

When users open a document that refers to a deleted shared field, they seethis message:

Cannot locate field definition for Field: <field name>.

When users click OK, they see the contents of the shared field asnon-editable text.

To prevent this message, modify each form to convert the old shared fieldto a single-use field (by cutting it and pasting it back on the form). The fielddefinition is stored within each form, rather than in a central location, anddocuments can be displayed as they were when they referred to a sharedfield definition.

Converting a single-use field to a shared field1. Open the form.

2. Click the field to be shared.

3. Choose Design - Share This Field.

To change a field’s status from shared to single-use, click the field and choose Edit - Cut and Edit - Paste. You cannot convert fields in a layout region.

Field names and labelsA field name is a required element. You assign a field name in the FieldProperties box when you create the field. A field label is descriptive textyou create that appears next to or on top of the field on the form, and helpsthe 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 — forexample, “Enter a product name.”

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


Field names cannot contain spaces. Run multiple words together, forexample, 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, forexample, the date of creation and the author’s name, use the same fieldname for all of them. This makes sharing information between forms easieras you continue to develop the application. Establishing and maintainingnaming standards simplifies application design throughout yourorganization.

Renaming a fieldUnlike forms and views that can have aliases, a field can have only onename. 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 textinto many instances of this field in documents, and you then rename thefield to “Observations,” all of the data in “Comments” will no longerappear when you display the document. If you must rename a field andneed to transfer data, create a new field, create and run an agent to reassigndata to the new field, then delete the old field. Remember to update allformulas to refer to the new field name.

Defining field typesThe 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:

Text

Date/Time

Number

Dialog List

Checkbox

Radio button

Listbox

Combobox

Rich text

Authors

Names


Readers

Password

Formula

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

Displaying graphics, attachments, and objects in a rich text fieldMany databases use an editable, rich-text field named Body to give users the flexibility of adding whatever they want to the main part of adocument — attachments, graphics, objects, or different fonts and colors. A rich text field can contain anything a page contains.

You can use a rich-text field to launch an OLE object — that is, to open anobject from another application within a form. You can even define the fieldso that an OLE object automatically launches when a user opens the form.For more information, see “Launching objects automatically.”

Rich text fields on the WebYou have two options for defining how a rich text field displays on the Web:

The rich text field displays for editing within an HTML text area. This is the default behavior.

The rich text field displays using the editor applet, allowing for abroader range of editing options.

Using the editor appletWeb users can do the following when using the editor applet in a rich text field:

Bold, underline, and italicize text

Change to Helvetica, Courier, or Times (fonts supported by the JavaDevelopment Kit (JDK), Release 1.0.2)

Change font size

Change font color


Align paragraphs (left, center, right)

Indent paragraphs

Use bulleted and numbered lists

Create links

Cut, copy, and paste text within the rich text field

Note Web users cannot paste text from outside the editor because ofthe limitations of the JDK, Release 1.0.2.

Enter international characters

Note Not all international characters can be displayed in the editorapplet. The ability to display international characters depends on thefonts installed on the user’s workstation and the version of the browserthe user is working with. Most characters entered in the editor will becorrectly transferred to Domino (depending on the browser).

Enabling the editor appletYou 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’swindow. It is recommended that you resize it. The minimum sizerecommended is 300 by 500 pixels. To resize it:

4. In the Objects tab of the Info List in the Programmer’s pane, select therich text field.

5. Click HTML Body Attributes.

6. In the Script area, enter the height and width. For example:"HEIGHT=300 WIDTH=500"

If the same document is edited by both a Web browser and a Notes client,there are some additional caveats. For example, it is possible to format adocument in the Notes client using a formatting feature that is notsupported in the editor applet. Also, there are features that, once openedand edited in the editor applet, will subsequently not format properly ifopened for editing in the Notes client. These are the formatting features toavoid if editing a document with both the Notes client and a Web browser:

First line indent or outdent

Full justification paragraph alignment


Tabs

Images

Ordered lists

Tables

In addition, any features that the editor applet cannot interpret aredisplayed as HTML in green on the document.

Number fieldsUse Number fields for numeric and currency data. The Number field typelets you limit a field to numerical values and define how the numbersdisplay in a form. For example, a Monthly Total field in a Budget form addstogether all of the numeric values from the fields listed in the followingformula 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 aComputed option in the Field Properties box. In the example above, theMonthly Total field is computed so users cannot edit the value.

Fields used in calculations must have default values. Otherwise, themessage “Incorrect data type for operator or @Function: Text expected”appears.

On the Control tab of the Field Properties box, you can specify whether thefield should display formats according to the custom settings you specify,or whether it should use the default settings of the user’s workstation. Inthe case of currency, where you might want different fields to displaydifferent currency formats, you can apply settings on a field level.

When you are defining a currency field, you can choose a currency symbolfrom an extensive list. If the symbol you need is not included in the list, youcan create a custom currency symbol by pasting in the ASCII character forthe currency symbol and entering the corresponding country code.

Caution Applying different currency formats, such as displaying Britishpounds in one field and American dollars in another, might result inunexpected results if you combine values using the formula language or ascripting language.


Choose any of these number formats on the Control tab of the FieldProperties box:

Decimal displays numbers either as they are entered (zeroes to the rightof the decimal point are suppressed), or with a fixed number of decimalplaces, depending on what you specify. To base the decimal symboland thousands separator display on the type of measurement (Imperialor Metric) users set in the operating system’s International UserPreferences, choose Client. To set the decimal symbol and thousandsseparator yourself, choose Custom.

Note A number field can store up to 8 non-zero decimal digits withoutloss of precision. Notes implements floating point arithmetic using theIEEE64 industry standard. In cases where a user enters more than 8non-zero decimal digits, rounding may occur and the number maydisplay and be stored differently from the number the user entered.

Percent displays a number as a percentage. For example, 12 displays as1200%, while .12 displays as 12%.

Scientific displays numbers using exponential notation. For example,10,000 displays as 1.00E+04. Select the number of decimal places fromthe Decimal Places list.

Currency displays values with the currency symbol you specify. Thedefault is the American dollar sign. For example, $15.00 is displayedwhen the value is 15 and “2” is selected in the Decimal Places list. Youcan select a different currency symbol from the list, or enter a customcurrency symbol and country code.

Designer recognizes the following formats for numbers:

Integers 123, -123Decimal fractions 1.23, 0.12, -.12Scientific notation 1.23E2, -1.23E12Currency $2.50, ($600.09)

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

Date/Time fieldsDate/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 canchoose a computed option so the user cannot change the field value.

Dates may range from 1/1/0001 through 12/31/9999. Entering two-digityears between 00 and 49 assumes the century starting in the year 2000.Entering two-digit years between 50 and 99 assumes the century starting inthe 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 toenter four digit years.”

Times may range from 00:00:00:00 through 23:59:59:59 in the 24-hourformat and from 12:00:00 AM through 11:59:59 PM in the 12-hour format.

Choosing a Date/Time formatOn the Control tab of the Field properties box you can select the format forthe display of the Date/Time field. You can choose to use the date/timedisplay based on users’ workstation preferences, or you can customize thedisplay.

To display a date1. Select or create a Date/Time field.

2. On the Control tab, select “Display Date.”

Select User’s settings to use the preferences from the users’workstations.

Select Custom to customize the display.

If you select Custom, choose display options. As you select options, thesample will change to show you what the user will see.

Note If you specify a comma as a date separator (for example:11,15,98) then you must use a semi-colon if you are separating multipledates in a list (for example: 11,15,98; 12,15,98; 1,15,99). If you specify asemi-colon as the date separator, then you must use a comma toseparate multiple values in the list.

The following are the date display options:

Show:

All

Only month, day, and year

Only weekday, month, and day

Only month and year

Only month and day

Only year

Special:

None

Show ‘today’ when appropriate.

Always show four digit year.

Show four digit year for the 21st century

Show year only when not this year


Format:

YMDW - Year, month, day, weekday. For example, 98 12/17/Thu.

WMDY - Weekday, month, day, year. For example, Thu 12/17/98.

WDMY - Weekday, day, month, year. For example, Thu 17/12/98.

To display a time1. Select or create a Date/Time field.

2. On the Control tab select “Display Time.”

Select Client to use the preferences from the users’ workstations.

Select Custom to customize the display.

If you select Custom, choose display options. As you select options, thesample will change to show you what the user will see.

The following are the time display options:

Show:

All

Hours, minutes, and seconds

Hours and minutes

Hours only

Format:

12 hour

24 hour

To show both date and time together in the same field select both “DisplayDate” and “Display Time.”

Time zone optionsChoose any of these time zone options on the Control tab of the FieldProperties box:

Adjust time to local zone - Displays the time relative to the time zone inwhich the document was created.

For example, if the document was created at 3:00 PM in Boston and isread by a user in Los Angeles, the creation time is adjusted to thePacific U.S. time zone and displays as 12:00 PM.

Note In order to take advantage of time zone conversion, the datemust be included in the field.

Always show time zone - Displays the zone in which the document wascreated 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 Angelessees the creation time as “3:00 PM EST.”

Show only if zone not local - Displays the zone in which the documentwas created only if the document was created in a different time zonethan it is being viewed in.

For example, if the document was created in Boston at 3:00 PM, users inthe U.S. Eastern standard time zone see the creation date as “3:00 PM,”while users in other time zones see the creation date as “3:00 PM EST.”

Note In order to take advantage of time zone options, the date must beincluded in the field.

Examples: Possible date/time formats 10/30

10/30/95

10/30/1995

Monday 10/30/95

Monday 10/30/1995

October 30, 1995

Monday October 30, 1995

Today

Yesterday

Tomorrow

Monday

Tuesday

Wednesday

Thursday

Friday

Saturday

Sunday

10/30 11:00 PM

10/30/95 11:45:30 AM

10/30/1995 11:45:30 AM

Monday 10/30/1995 11:45:30 AM


Monday 10/30/1995 11:45:30:00 AM

Monday 10/30/1995 11:45:30:00 AM EST

Monday October 30, 1995 11:45:30:00 AM EST

Monday 11:45:30:59 AM

11:00 PM

11:45:30 AM

11:45:30:59 AM

11:45:30:59 AM Today

11:45:30:59 AM EST Today

98 12/17/Thu

Formulas for Date/Time fieldsDates and times are often calculated by formula rather than supplied by auser. Use the following @functions to create date and time field values.

To display Create a Date/Time fieldshowing

Use the formula

Date a document is created Date and time @created

Date a document ismodified

Date and time @modified

Current date Date @today

Current date and time Date and time @now

Creating a graphical display for Date/Time fieldsYou can display certain editable Date/Time fields either as a blank fieldthat 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 controlUsers can click a helper button on the field box to bring up a one-monthcalendar on which they can select the date they want.

1. Create an editable Date/Time field.

2. On the Field Info tab of the Field Properties box, select “Native OSstyle.”

3. On the Control tab, choose:

Display Date

User’s settings or Custom display

For Custom display, choose display options.

To create a time controlUsers can select time by clicking on the control and sliding the selection barto a new time.


2. On the Field Info tab of the Field Properties box, select “Native OSstyle.”


Display Time




To create a duration controlUsers can select a range of time with a duration control, for example, from12:00pm - 1:00pm.


2. On the Field Info tab of the Field Properties box, select “Native OSstyle” and “Allow Multi-Values.”


Display Date



Examples: Creating a field to display dates and timesTracking modification datesYou want to track the dates on which purchase requisitions are created andmodified. On the Purchase Requisition form, you create a computed-when-composed Time field called CreationDate with the formula“@Created.” This date always shows the date the author first saves thedocument. To track editing dates, you also created a computed Time fieldcalled ModifiedDate with the formula “@Modified.” This date is the sameas the CreationDate the first time the document is saved but is updatedautomatically each time the document is modified.

Determining the daily age of a documentIn your Service Tracking database, you want to track the age of requestdocuments. On the Request form, you create three fields to calculate the information.


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

@Created

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

@Now

The third field is a computed Numbers field that is calculated by thisformula, which uses the values from the previous two fields:

@Abs(@Integer((CurrentDate - DateCreated) / (60 * 60 * 24)))

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

Names fieldsCreate a Names field to display user names. A names field can be computedor editable. If you associate the formula @UserName to a Names field, thename will appear the way it appears in Notes IDs — for example, SaraRyan/Acme/US.

To display only the common name portion of names, use the [CN]parameters with @Name. For example, in an editable names field calledMembers use this formula as the default value:

@Name([CN];Members)

This formula displays the name “Sara Ryan” if the user’s hierarchical nameis Sara Ryan/Acme/US

For more information about formulas for displaying user names, see theProgramming Guide.

Looking up names for field valuesTo help users enter names correctly in a document, provide links to existinglists of names. For example, a Names field might require that users selectnames from the access control list for the database. This enables users topick a name from a list, eliminates spelling errors, and restricts names in thefield. Other sources for names are the Domino Directory or a view dialogthat presents names from a column in a view.

Lookup options are available on the Control tab of the Field Properties boxwhen you create a Names field, an Authors field, and a Readers field. Youcan 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 theentry helper button to the right of the field to see a list of possible entries.Lookup options are not supported on the Web.

Lookup optionsUse Address dialog for choices - This option displays the Names dialogbox so users can select names from a Personal Address Book or DominoDirectory. Select “Look up names as each character is entered” to helpusers fill in a name quickly. Notes looks up a match for the typed lettersin the open Address Book or directory.

Use Access Control List for choices - This option brings up a list ofpeople, servers, groups, and roles in the access control list.

Use View dialog for choices - This option brings up a dialog boxcontaining entries from a column in a database view. Select thedatabase to look up, select a view, and select a column number.

For information on the access control list for a database, see ManagingDomino Databases.

Readers and Authors fieldsReader and Authors fields allow you to control who can read and createdocuments created from a form. Because these fields work with the overallDesigner security model, they are described in “Restricting Access to andSecuring Parts of an Application.”

Creating fields to display lists of choicesYou can create fields that present users with a list of choices. The list can begenerated by formula, entered manually by you, or created or added to byusers who enter values. Enter lists and formulas for choice fields on theControl 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 FieldProperties box to let users add their own words without changing theoriginal list. Also, some of the interface styles have an option to “Allowmulti-values” on the Field Info tab which lets users select several choices inthe field. Choice list fields can be editable or computed; however, mostchoice list fields are editable. The field types that present lists of choices are:


Field Type Usage “Allow valuesnot in this list”

“Allowmulti-values”

Dialog listUsers either press ENTER or click the entryhelper button to see all the choices at once,press the space bar to display choices one ata time, or type a letter to display the firstchoice beginning with that letter. Select“Display entry helper button” if you do notwant to display a button next to the fieldthat a user clicks to view all the choices.Dialog lists are not available in layoutregions.

Available Available

CheckboxEach choice is displayed with a box usersclick to select. Checkboxes have border andcolumn options. To create a wide checkboxpanel, choose a column number between 2and 8.

Not available Available

Radio buttonEach choice is displayed with a button;users can click only one. Radio buttons have border and column properties. Tocreate a wide button panel, choose a column number between 2 and 8.

Not available Not available

List boxEach choice is displayed with an expandedlist box. Users click an entry to select it. List boxes have border, size, and placementoptions. To resize the list box withoutdragging it, change the Width and Heightmeasurements. To move the list box in alayout region without dragging it, changethe Left and Top measurements.

Not available Available

Combo boxEach choice is displayed with a drop-downlist box. Users click the drop-down arrow to see the entries and click the one theywant. Combo boxes have border, width,and placement options. To resize the combobox without dragging it, change the Widthmeasurements. To move the combo box inthe layout region without dragging it,change the Left and Top measurements.

Available Not available


Generating choices for listsWhen you are defining a list field, choose one of these options on theControl tab of the Field Properties box for generating the list.

Enter choices (one per line)

Type a list of choices in the edit box. Select Sort todisplay the list in alphanumeric order. Click the greencheck mark to save your entries. Choices can containletters, numbers, and all punctuation charactersexcept commas.

Use formula forchoices

Type a formula in the formula window to generate alist of choices. Click the green check mark to saveyour entries.

Use Address dialogfor choices

This option displays the Names dialog box so userscan select names from a Personal Address Book orDomino Directory. Click “Look up names as eachcharacter is entered” to help users fill in a namequickly. Notes looks up a match for the typed lettersin the open Address Book or directory.

Use Access Controllist 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 forchoices

This option brings up a dialog box containing entriesfrom a column in a view. Select the database to lookup, select a view, and select a column number.

Use View dialog for choicesLooking up values in a view lets you retrieve data from databases. This isconvenient for displaying choices that change, such as customer names,sales territories, and job titles.

View lookups provide the following benefits:

Non-designers can maintain choices without having access to the rest ofthe database design.

Designers can avoid hard-coding choices into fields. This makesverification and maintenance easier.

Designers can hide the design of the database without affectingmaintenance of choices.

Designers or administrators can customize the application orconveniently translate lookup information to other languages.

Users can review choices and codes more conveniently from outside theform or application.


Note Use lookups sparingly because they adversely affect the performanceof the application.

To retrieve information from Domino or non-Domino databases you canuse @DbColumn and @DbLookup formulas instead of using a View dialoglookup.

For more information on @DbColumn and @DbLookup, see theProgramming Guide.

Examples: Creating a field to display a list of choicesYou want to make it easy for users to include a product number when theyfill out a Purchase Request. Create an editable Dialog List field namedProductNumber and use the “Use View Dialog for choices” property togenerate choices.

You select the Inventory Database, the By Product Number view, andColumn 1, where product numbers are listed.

Creating a formula-generated listA Travel Request form contains an editable Listbox field called Countrythat uses the following formula to show only those countries relevant to thelocation selected by the user:

@If(Location="Europe";"France":"Germany":"Italy":"Spain";Location="Far East";"Japan":"Singapore":"SouthKorea";Location="North America";"Canada":"Mexico":"UnitedStates";"")

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

All | A

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


Converting aliases to full category namesIf you are creating a view with a categorized column that refers to choicelist fields, you need to be aware that the view will use the alias name as thecategory 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 aliasesback to their full names. For example, the following is a column formula forthe view to convert the alias back to their full names for display in thecategorized column:

@If(RequestType="HW";"Hardware Request";RequestType="SW";"Software Request";"Service Request");

Example: Using aliases for choices in a listYou 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 productgroups 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 theword seen by users in the document. To display the contents of the Productfield in a view, you need to use a hidden field or column formula thatconverts the alias name to its long form:

@If(Product="1";"Microwaves";Product="2";"Ovens";Product="3";"Refrigerators";Product="4";"SpecialtyItems";Product="5";"Toasters";Product="";"";"");

Password fieldsA Password field is a text field that maintains a user’s privacy by displayingeach character a user enters as an asterisk on the screen. The contents of thePassword field is not secure, and it is visible in the Document Propertiesbox from the Notes client. There are several ways to secure the contents of aPassword field. If you are using the Password field as a method for securingan application, the best way to secure the contents of a Password field is notto save the contents after the entry is verified. This can be done using aformula that clears the field once it’s been verified. You can use the inputtranslation event or a LotusScript QuerySave event.

Example: Using an input translation formulaThis formula is an input translation formula for a Password field. When theuser enters a password, Domino looks up the user in the Domino Directoryand gets the user’s HTTPPassword field. Then, it compares the value thatthe user inputs into the field with the HTTPPassword field. If the valuesmatch, it presents a prompt saying “You passed.” If the values do notmatch 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 REM entered after running it through the @Password hash REM function and prompts the user whether they typed in aREM valid password or not.";

@if(@isError(x);@Prompt([OK];"Error";"Error");@Password(Password) = x;@Prompt([OK];"You passed";"Youpassed");@Prompt([ok];"Password failure";"You entered anincorrect password"));

REM "This deletes the password field.";

@Unavailable


Example 1: Using a QuerySave eventThis script determines whether the password field contains a password. If itdoes it gets the name of the author of the document and puts theabbreviated form of the name into the PublicEncryptionKeys field. Thiseffectively encrypts the Password field with the author’s public key. Thisdoes not involve a lookup to the Domino Directory to get the key. It isretrieved from the user’s ID file.

Dim doc As NotesDocument

Dim db As NotesDatabase

Dim session As New NotesSession

Set db = session.CurrentDatabase

Set uidoc=Source

Set doc=source.Document

If doc.GetItemValue("Password")(0) <> "" Then

Set PkName = New NotesName(doc.GetItemValue("Author")(0))

Call doc.ReplaceItemValue("PublicEncryptionKeys",PkName.Abbreviated )

End If

Example 2: Using a QuerySave eventThis script determines whether one or more Password fields contains apassword. If one of the fields does contain a password, the script gets thevalues from the Author field and the OtherEditors field (which mightcontain a group) and expands the OtherEditors field so that it has namesand puts the abbreviated form of the name into the PublicEncryptionKeysfield. This effectively encrypts the Password field with the public keys forall unique entries in the two fields. This does involve a lookup to theDomino Directory to get the keys for each of the users listed, unless the onlyvalue is the name of the current user. If there is more than one name to lookup, then it finds the public keys from the Domino Directory. If the only keyto 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

Calldoc.ReplaceItemValue("PublicEncryptionKeys",Evaluate(|@Name([Abbreviate];@Unique(Author:OtherEditors))|,doc))

End If

Formula fieldsFormula fields are used to populate a subscription list, which works inconjunction with the Headlines.nsf database. The Headlines database isaccessible from the Bookmark pane of the Notes client and can be used asthe home page of a Notes client. The Headlines database includes a featurecalled subscriptions. Each database designer has the option of including asubscription form in a database. When a user subscribes to a database (byfilling out and saving a subscription form in that database), it triggers aserver task that will notify the user whenever a document of interest issaved in that particular database. The criteria that the server looks for iscontained in a formula field on the subscription form. Although users fillout the subscription form in the database they want to subscribe to, thesubscription documents are stored in users’ headlines databases on theirlocal client.

You can use the default subscription form, which is located in theheadlines.ntf database. To use the default form, copy and paste it into yourdatabase. The subscription form, named $Subscription, is in theHeadlines.nsf or Headlines.ntf database that is included with Designer. Youcan use the subscription form as is or you can customize it. If you customizeit you must include the formula field. The formula field on the $Subcriptionform is named $HLFormula and is on the second tab of the tabbed table onthe right side of the form. The $HLFormula field is a computed field. If youchoose to keep the formula field computed, you write a formula thatresolves to a formula for a subscription list. A formula field must resolve toa formula in order for the server to be able to retrieve the subscriptioncriteria for the user.

Another option for the formula field is to choose Literalize fields on theField Info tab of the Field Property box. When you select the Literalizefields option, you are programming the formula field to accept the formulayou put in without compiling it. If you literalize a formula, the fieldreferences 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 asa field reference.

The following is an example of a formula for a formula field for whichLiteralize 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 toanother formula. This provides the ability to optimize complicated formulasbefore they are saved. After the formula is evaluated, the resulting formulais saved.

If the resulting formula is invalid, the field is saved with a value of typeerror. In some cases, the user would never be able to exit out of thedocument. To differentiate between success and failure, you should test inthe 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")

Editable and computed fields

You choose whether a field is editable or computed in the field propertiesbox, when you create the field. If a field is editable, a user can enter orchange the value of the field. If a field is computed, a formula calculates thefield 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 formulasYou 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 Objecttab of the Info List. For example, the default value event provides an initialvalue for an editable field. If you include a Date field on a form, you mightwant to enter a default value formula of @Today. This populates the fieldwith today’s date.

Use the Reference tab on the Info List of the Programmer’s pane to accessthe list of fields, @commands, and @functions. You can use the Referencelist as a shortcut for looking up @functions and @commands and for pastingthem into the formula.

For information on writing formulas for fields, see the Programming Guide.

Computed field formulasComputed fields are used to automatically enter data, such as the author’sname or the date, in a field. You can have more than one computed field ona form. Computed fields require formulas to supply their values. Forexample, 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 isdependent on values in other fields and you want to be sure that thecalculation occurs after those fields have been validated.

When it’s important for users to see results as they proceed, you can forceeach 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 ofthe form are dependent on field values at the top. Be aware that thisproperty can slow down document display time if the form has manycomputed fields.

There are three types of computed fields:

Type of computed field Formula calculates

Computed A computed field formula calculates each time a usercreates, saves, or refreshes a document.

Computed whencomposed

A computed-when-composed field formula calculates onlyonce: when the user first creates the document. Use thistype of formula in a field to preserve information aboutthe origin of a document, such as the creation date ororiginal author, or to create a field whose original valuenever changes, such as a document sequence number.

Computed for display

A computed-for-display field formula recalculates eachtime a user opens a document. Use this type of formula ina field to display information that is relevant only to theimmediate session, such as the current time or the resultsof calculations that you don’t need to save. The field valueexists 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 field1. 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 theScript 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 delaycomputing until after validation formulas run, choose Design - FieldProperties and select “Compute after validation” on the Field Info tab.

6. (Optional) To recalculate field values while users edit a document, clickthe form and choose Design - Form Properties, click the Form Info tab,and select “Automatically refresh fields.”


Note Automatically refreshing fields can slow down documentdisplay time. A faster alternative is to write a LotusScript field event torecalculate the document or update other fields when users move froma specific field.


Editable field formulasYou can write up to three formulas for each editable field:

The default value formula provides an initial value that the user canchange. Providing a default value for an editable field ensures that thefield gets filled in and often removes the need for users to enter datasuch as their name or the date.

The input translation formula modifies the contents of a field after auser fills it in — for example, to correct typing or standardize theformat. Use an input translation formula to format information enteredby users — for example, to make all entries uppercase. The result of theformula replaces what the user entered. Input translation formulas areevaluated each time a document is saved, recalculated, or refreshed.

The input validation formula checks the contents of a field againstpredefined criteria, making sure the entry meets certain requirements.For example, use an input validation formula to ensure that users fill ina required field. Input validation formulas are evaluated each time adocument is saved, recalculated, or refreshed.

To create a default value or input translation formula1. 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:

a formula

a field name

a text string in quotation marks

4. Click the green check mark to verify and save the formula.

To enter a literal text string, enclose it in quotation marks (“ ”). Field namesdon’t need quotation marks.

If you select the form property “On Create: Formulas inherit values fromselected document” when designing the form, use the default formula tospecify 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 thedocument that is currently highlighted if that document contains thespecified field.

An alternative to an input translation formula is to write a script for theExiting event that verifies information.

To create an input validation formula1. 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 check mark to save the formula.

@Failure prevents the user from saving the document until the user enters avalue that meets the criteria. As part of the formula, include text that clearlyindicates what is wrong and how the user can correct it.


Examples: Creating a formula for an editable field

Default value formula examplesThe default value formula provides an initial value for an editable field.You can set the value to a specific number or text string, or you can use aformula. For example:

The formula Returns

0 The number 0

@Now The current time and date

@Name([CN];@Username) The common name portion of a user’shierarchical name

Price The value of the field named Price

“Connecticut”:“New York”:“New Jersey” A text list containing Connecticut, New York, New Jersey

Product + “, ” + Department The value of the field named Product,followed by a comma and a space, andthe value of the field namedDepartment


Example: Input translation formulaThe following formula translates the text in the Attorney field for displaywith initial capital letters. If a user enters the text john smith in the Attorneyfield, it is translated to John Smith when the document is saved.

@ProperCase(Attorney);

The following formula gives documents a uniform look by capitalizing theinitial letter of the value in the Subject field and removing extra spaces.

@Trim(@ProperCase(Subject));

Input validation formula examplesField criteria Formula

User must enter a valuethat is less than 100 in Costfield

@If(Cost<100;@Success;@Failure(“Cost must be lessthan $100.”));

User must enter a value forthe Subject field

@If(Subject = “”; @Failure(“You must enter a subjectfor your document.”); @Success)

Examples: Calculating a value for a computed fieldCombining text and field values to create a messageThe SchedDisp field, which displays only when users read or print adocument, can display two different messages depending on the value inthe Sched field. If it is a special, temporary schedule, the message combineswords with a text-based version of the value in the Date field. If theschedule is permanent, the message is “Regular schedule.”

@If(Sched = "Special schedule"; "Special schedule for weekstarting: " + @Text(Date); "Regular schedule")

Totaling monthly budget figuresThe MonthlyTotal field in the Budget form is a computed Numbers fieldthat is formatted for Currency with two decimal places. The formula totalsthe values in each category to calculate the total budget.

Advertising + Entertainment + Miscellaneous + Overhead +Salaries + Travel

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

@Created;


The field is defined as computed-when-displayed, rather than computed, toavoid storing the creation date information twice.

Determining the normal work day age of a documentThis field formula determines the age of a document in work days, based ona five-day work week. In the following example:

DateCreated is a field containing the date when the document wascreated. The field’s data type is Date/Time, and it is computed usingthe formula @Created.

Currentdate is a field containing the current date of the document. Thefield data type is Date/Time, and it is computed using the formula@Now. Because Notes sorts dates in seconds, you must divide by(seconds per minute) * (minutes per hour) * (hours in a day), whichequals 86400.

Weekend_days is a temporary variable that contains “Age of documentin days” divided by “Number of days in a week,” multiplied by “Daysin a weekend”.temp := (@Date(Currentdate) - @Date(DateCreated)) / 86400;

weekend_days := @Integer((temp / 7)) * 2;

wkday := @Weekday(DateCreated);

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

working_days := temp - (weekend_days + adjust);

@If(Currentdate = ""; 0; working_days);

Selected Field Properties

Setting a tab order for a fieldTab order specifies the sequence in which fields become active when a userpresses the Tab key. By default, the tab order moves from left to right, topto bottom. You can control the tab order by explicitly assigning a numericsequence to fields in the Tab order field on the Field Info tab of the FieldProperties box.


Using Native OS StyleIf you choose the field property “Native OS style” for an editable field, suchas Text, Authors, Readers, Names, or Number, the field appears on thedocument as a fixed-size outlined box instead of as blank space marked offby brackets. An editable Date/Time field displays as a graphical date/timecontrol. On the Web, native controls are ignored and fields display in theirdefault format. You can change the width and height of native controls by:

Entering a fixed width and height.

Choosing “Expand width to window.”

Choosing “Dynamic.” This option increases the size of the entry boxdynamically up to 3 lines. If an entry is longer than 3 lines, scroll barsdisplay automatically.

Automatically refreshing field values Sometimes users must see the results of all field calculations as they workon a document. To provide continuously updating information, design aform that recalculates fields automatically whenever a field value changes.Be aware this setting slows down a document’s display and data-entrytime.

You can refresh field values in the following ways:

Automatically, by setting a form property that refreshes all keywordfields as the user edits a document.

Automatically, by setting individual field properties to refresh based onthe event you choose. For example, you might set a keyword field torefresh automatically when a keyword changes.

Manually, when a user manually refreshes a document.

For choice list fields use the field property “Refresh field on keywordchange” for better performance on large documents with many computedfields. This field property refreshes all the fields on a form only after a userselects a value for a specific choice field that has the property enabled. Youcan also write a LotusScript field event to recalculate the document orupdate other fields when users move from a specific field.

To refresh field values automatically1. Open the form.


3. On the Form Info tab select “Automatically refresh fields.”

4. Save the form.


Making a field active by defaultThe first editable field on a form is the active field by default. You canoverride this setting and change which field is active when a user creates oredits a document.

Changing the default active field helps emphasize an editable field that isn’tlocated at the top of the form, or directs users to a field that is the mostfrequently edited field on the form or to a required field that you don’twant users to miss.

This option applies only to editable fields.

1. Create a field, or click an existing field. Then choose Design - Field Properties.

2. On the Field Info tab select “Give this field initial (default) focus.”

Hiding fieldsUse hidden fields to perform interim calculations or to store informationyou do not want users to see. In the Designer templates, hidden fieldsappear at the bottom of forms, preceded by the heading “Hidden fields.”

Hiding fields is not a security feature. Users can see the value of hiddenfields 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 optionsWhen you hide a field, you are actually hiding the paragraph on the formthat contains the field. If there is text, such as a field label or graphics in thatparagraph, Designer hides them with the field. You can hide a field and anyassociated text or graphic all the time or only at certain times. For example,information useful only when users create or edit documents can be hiddenduring 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 aneditable choice list field, can be hidden during editing.

The following are options for hiding fields:

Hide paragraph from Notes 4.6 or later

Information is hidden when the application opens on a Notes 4.6workstation.

Hide paragraph from Web Browsers

The information is hidden when the application opens on a Web browser.


If the paragraph is hidden when: Then:

Previewed for reading The hidden information isn’t visible when usersread documents in the document preview pane.

Previewed for editing The hidden information isn’t visible when userswork on documents in Edit mode in thedocument preview pane.

Opened for reading The hidden information isn’t visible when usersopen documents in Read mode. A field that can’tbe read can’t be printed either.

Opened for editing The hidden information isn’t visible when userswork on documents in Edit mode.

Printed The hidden information isn’t visible on printeddocuments.

Copied to the clipboard The hidden information isn’t visible wheninformation is copied to and pasted from theClipboard. This setting doesn’t affect documentscopied at the view level.

Hide paragraph if formula istrue

A formula determines the circumstances in whichinformation is hidden.

To hide a fieldIf you have computed fields that users don’t need to see, or if you createtwo fields — one for display when reading and one for use when editing — you can stipulate when to hide the fields.

1. Select the field you want to hide.

2. Choose Design - Field Properties.

3. On the Hide tab:

Select “Hide paragraph when document is:” and click all situationswhen users don’t need to see the field information.

or

Select “Hide paragraph if formula is true” and write a formula in theformula window on the Properties box to describe the situationswhen users don’t need to see the fields.

For more information on using a formula to hide a paragraph, see theProgramming Guide.

Choosing “Refresh fields when keywords change” displays documentsfaster than the form property “Automatically refresh fields.” It is useful forshowing or hiding parts of the form when you have hide-when formulasthat are dependent on values in the field.


ExamplesTo make documents more readable, you decide to modify the MarketingIdeas form to show only the model name for the product that the authorselects.

The Models field is a radio button field that displays these choices forrefrigerator 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 underthe Models field. SelectedModel uses the value from the Models field. Youhide 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 regionIf you are designing a field in an application that will be accessed by Notesclients only, placing a field in a layout region allows you to display the fieldvalue over text or graphics and limit the number of characters users canenter in a field. In addition, creating certain date/time fields in a layoutregion automatically displays calendar controls.

Creating an editable date/time field in a layout region with Displaydate selected displays a calendar pop-up that users click on to choose anew date.

Creating an editable date/time field in a layout region with Displaytime selected, displays a time control that let users pick a time bysliding the selection bar to a new time. To make the time control aduration control that lets users pick a range of time, specify that thefield 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.

3. Choose Design - Field Properties and assign a name to the field.

4. Assign any field type except Rich Text and then select Editable or acomputed option.

5. Drag the field horizontally or vertically to adjust its width and height.

To create a field label:1. Choose Create - Layout Region - Text.

2. Click the text area, choose Design - Object Properties, and type a fieldlabel in the Text box. Click the green check mark.

3. Drag the text area above or to the left of the field and drag it to the sizeyou want.

4. Click the Style tab to change the text style for the label.

To resize a field:Placing a field in a layout region allows you to adjust the way field valuesappear or to limit the number of characters users can enter in a field. Toresize a field, drag the borders of the field.

Adding HTML attributes to a fieldThere are two places to attach HTML to a field. Use the HTML tab on the Field Properties box, or use the HTML attributes field event to attachHTML formatting attributes to editable fields. For example, you can defineSIZE and MAXLENGTH for a text field and ROWS and COLS for a rich text field.

1. Click the field you want to format.

2. On the Objects tab of the Info List in the Programmer’s pane, select theHTML Attributes event for the field.

3. Write the HTML code in quotes in the Script area — for example,"SIZE=40 MAXLENGTH=40"

4. Save the form.


Storing HTML in a field

To pass HTML directly to the browser and force Domino to disregard allother fields, add a field named HTML to the form. The field can becomputed or editable, but editable is preferable if you want to change theHTML on a per-document basis. Use a text field if the HTML text is lessthan 15K; otherwise, use a rich text field. Enter the HTML code as the fieldvalue in the Script area of the Programmer’s pane or enter the HTML in thefield of the document you create using the form. Using HTML in a field issimilar to enabling the form property “For Web Access: Treat documents asHTML,” but converts only the field value to HTML, so you can keep fieldsfor Notes users on the same form. Web users see the HTML informationwhen they read documents, but they do not see the HTML informationwhen they edit documents.

1. Create a field named HTML.

2. Select Value or Default Value in the Programmer’s pane object list.

3. (Optional) Write the HTML code in the script area if you want topresent 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 HTMLfield, 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 orfrom another field on the same form. A field that inherits a value from afield on the same form must be a computed field, placed below or to theright of the field it is inheriting from. Use the parent field’s name as thevalue for the field formula. The form itself does not need the “Inherit fieldvalues” property set. To inherit a field value from another form, a Notesclient user must have that form selected and a Web user must have the formopened or referenced in the URL command, for example,http://server/db.nsf/InheritanceForm?OpenForm&ParentUNID=6b87e303374b19148525639a00506656.


To create a field that inherits values from another documentCreate fields that inherit information from another document to save usersfrom unnecessary typing or to keep related documents consistent.Open the form.


2. (Optional) To display the parent document to end users in the previewpane of the Notes client, click the Defaults tab, select “On Open: Showcontext 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 usesthe parent document field name as the value. For example, to inheritthe FullName field, use FullName as the inheriting field’s formula.

Example: Inheriting address informationIn a Customer Contacts application, a Letter form uses inheritance to copyinformation from a Company Profile document. The Company Profilecontains name and address fields and a hidden field called FullName. TheLetter form inherits the values of the name and address fields for theaddress block and uses the FullName field for the salutation.

When Notes client users highlight a Company Profile document and chooseCreate - Letter, the Letter is already filled in with the recipient’s name,address, and the correct salutation.

When Web users open the Company Profile document and click a button tocreate a Letter document, the Letter is already filled in with the recipient’sname, address and the correct salutation.

Creating a field that inherits an entire documentYou can create a field that inherits the full contents of a document. Forinstance, a rich-text field in a new response document can automaticallyinherit the entire contents of its main document. To create a document thatinherits the parent document a Notes client user highlights or opens anexisting document before creating a new document. The documents do notneed a main document/response document relationship. The opened orhighlighted document is assumed to be the parent document. The parentdocument 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 givesusers the opportunity to review the parent document, but doesn’t clutterthe form. To suppress inheritance a Notes client user can press CTRL whilechoosing Create.


To inherit the parent document a Web browser user must open an existingdocument before creating the new document. The options “Inherit as richtext” and “Inherit as Collapsible rich text” both inherit the topic in itsentirety into the new document. Collapsible sections and inheriting as linkare not supported on the Web. To enable Web users to create a newdocument from an open document, you must provide a form action tocreate a new document.

1. Open the form.

2. Create a rich-text field to store the inherited document.



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

Inheriting information in a response hierarchyIf you have set up a response hierarchy, a response can automaticallyinherit the subject of the main topic with added text that distinguishes itfrom the original subject line. For example, if a user creates a main topicwith the subject “New Product Ideas,” then all subsequent responses willhave the subject “Response to New Product Ideas.”

Create a field on the main topic form and the response form namedSubject.

Make the Subject field on the main topic form editable so that the usercan enter the subject.

Make the Subject field on the response form a computed field whichuses the formula:"Response to " + Subject

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


Standard fields used in templates

The following fields are frequently used in the templates that ship withDesigner. You may want to follow the same standards in databases youdesign to maintain consistency and make it easier to share informationbetween forms.

Field name Field purpose

Body Editable rich-text field that stores most of theinformation in a document.

ComposedDate Hidden, computed-when-composed, date/timefield that uses the formula @Created.

From Computed-when-composed, Authors field thatuses the formula @UserName.

Subject Editable text field that contains a one-linedocument summary.

Predefined fields with built-in functionality

Designer provides predefined fields that you can use to automatically addfunctionality that you would otherwise have to program yourself. Forexample, to design a form with mailing options, you add predefined mailfields such as SendTo and CopyTo to a form. Designer recognizes the fieldsand provides the interaction with the mail router that routes and deliversthe mailed document.

If you try to use a reserved name in a way that is different from its intendeduse or redefine the field, Designer displays an error message.

Reserved fields for mailing documents

Reserved field name Use

MailOptions Gives users the option of mailing a document

SaveOptions Controls whether documents are saved whenmailed

Sign Signs creator’s name to prevent tampering

Encrypt Encrypts mail

SendTo Sends mail to users listed in field

CopyTo Sends copy to users listed in field

continued



BlindCopyTo Sends blind copy to users listed in field

DeliveryPriority Delivers mail high, medium, or low priority

DeliveryReport Returns a report when mail is delivered torecipient

ReturnReceipt Returns a receipt when recipient reads mail

MailFormat Routes mail via cc:Mail™

Reserved names for embedded elements


$$ViewBody Contains an embedded view

$$ViewList Contains an embedded folder pane

$$NavigatorBody Contains an embedded navigator

$GroupScheduleRefreshMode Contains a value for refreshing an embeddedgroup scheduling control

$GroupScheduleShowLegend Valid values for it are 0 and 1. 0 means that thecolor legend should not display, and 1 means thatit should. The default is 1.

Reserved fields for use in billing applications


$ChargeRead Creates a billing record when a user opens adocument that contains this field

$ChargeWrite Creates a billing record when a user creates,copies, edits, or saves a document that containsthis field

Reserved fields for general use


Categories Categorizes documents

$VersionOpt Controls version tracking for documents

FolderOptions Puts new documents in folders

SecretEncryptionKeys Encrypts documents with secret, rather thanpublic, encryption keys

continued



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, Dominoresponds with the default confirmation “Formprocessed.” To override the default response, adda computed text field to the form, name it$$Return, and use HTML as the computed valueto create a customized confirmation.

Internal fields on formsInternal field name Use

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

Fields for version trackingAdding 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 fieldUse a computed text field if you want each document created from a formto 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 notwork 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 AsNew Version when they save a document

2 New versions automatically become responses when saved

3 Prior versions become responses if users choose File - Save AsNew Version when they save a document

4 Prior versions become responses when saved

5 New versions become siblings if users choose File - Save AsNew Version when they save a document

6 New versions automatically become siblings when saved

To create a choice list $VersionOpt fieldUse a choice list field if you want users to be able to choose the method ofversion control each time they create a document.

1. Create a field named $VersionOpt and define it as an editable dialoglist field, in the Field Properties box.

Do not select “Allow multi-values” or “Allow values not in the list.”

2. On the Control tab select “Enter choices (one per line)”.

3. Enter one or more of the following options:

Don’t track versions | 0

Create response if File - Save As New Version is used | 1

Create response automatically | 2

Promote to main document if File - Save As New Version is used | 3

Promote to main document automatically | 4

Create additional main document if File - Save As New Version is used | 5

Create additional main document automatically | 6


Fields that prompt users to select folders

Adding a FolderOptions field to a form lets users select a folder for newdocuments 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 sothat a document is automatically saved to the current folder.

1. Create a field named FolderOptions and define it as a computed textfield, 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 notwork 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 akeyword 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 Listin the Programmer’s pane.

For an editable field, select Default value from the Objects tab of theInfo 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 valuesaves and adds the document to that folder. If the user is not creatingthe document from a folder, the document is saved but not added to a folder.


Chapter 7Designing Framesets

This chapter introduces frames and framesets.

Overview of framesets

A frameset is a collection of frames and can add structure to your Web siteor Notes database. A frame is one section, or pane, of the larger framesetwindow and is independently scrollable.

A frame can contain a form, folder, page, document, view, navigator, orframeset. The frame can also contain a Web page and be associated with aspecific URL. Framesets let you create links and relationships betweenframes. For example, you can leave one page displayed as users scroll orlink to other pages or databases.

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

165

Note Framesets created with Release 5 do not work with previous releasesof Notes. A database opened by a previous version of Notes will belaunched using “restored as last viewed by user.”

Creating a frameset1. 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 fourframes. 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, orkeyboard keys to further refine your frameset. You can:

Split the selected frame vertically by choosing Split into Columns(SHIFT - INSERT key).

Split the selected frame horizontally by choosing Split into Rows(INSERT key).

Delete the selected frame by choosing Delete Frame (CTRL - DELETEkey).

Refresh the content of the selected frame by choosing RefreshContent.

Remove the content of the selected frame by choosing Remove FrameContent (DELETE key).

Cycle through frames by using the TAB key (SHIFT - TAB cyclesbackwards).


6. Open the Frameset Properties box. At the Basics tab:

Name the frameset.

Provide an alias for the frameset. An alias is an internal name for the frameset. Use an alias to change or translate the frameset namewithout causing reference problems. The alias appears with theinitial list of framesets in the Work pane.

Add a comment. The comment appears with the initial list offramesets in the Work pane.

Click “Available for public access” if you want to have the framesetavailable for public access.

Enter a title for the frameset in the Title field or use a formula tocompute the frameset title by clicking Formula Window and enteringthe formula. The frameset title is the name that appears in theWindows tab when the frameset is launched.

7. Add content to each frame by using the Frame Properties box.

8. To move borders between frames, you can:

Drag borders with the mouse.

Use the Arrow keys to drag the border in the direction of the arrowand the SHIFT + Arrow keys to drag the border in the oppositedirection.

9. To preview the frameset:

To preview the frameset on the Web, choose Frame - Preview in Webbrowser and choose a browser.

To look at the HTML source, click Synopsis in the Design pane. Inthe Design Elements tab of the Design Synopsis dialog box, chooseframesets and add each frameset for which you want to view theHTML source. Make sure to check “Include JavaScript and HTML”in the Contents tab.

You can also look at the HTML source by previewing the frameset onthe Web and then viewing the source with the chosen Web browser.

To preview the frameset in Notes, you can launch the database intothe frameset or select the frameset name in the Work pane and clickthe Preview in Notes icon from the Designer toolbar.

Chapter 7: Designing Framesets 167

Providing content for a frame

When you first create a frameset, the text “No content” appears in eachframe. To provide content for a frame in a frameset, you can do thefollowing:

1. Select a frame in the frameset.

2. Choose Frame - Frame properties. The Frame Properties box appears.

3. At the Basics tab, provide a name for the frame.

Make sure that each frame has a unique name. Using the same name forframes in different framesets is not recommended. For example, if youhave a frame named Banner in more than one frameset, you may getunexpected results when you set it as a target frame.

Note that you should not use HTML predefined target names to name aframe ( _self, _top, _parent, and _blank).

4. At the Type field, choose one of the following ways to provide contentfor the frame:

Link

Link requires that you paste in a link that you’ve already copied tothe Clipboard. Click the Paste icon to paste in the link. There arethree kinds of links you can paste in from the Clipboard: View,Document, or Anchor. (Database links are not supported inframesets.)

See “Adding Links” for more information on links.

Named Element

A named element is a design element that you have already createdand 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 namedPAGE1, enter it into the Value field). Alternately, you can click oneof the following icons:

Formula icon (@) to use a formula that evaluates to a name.

Paste icon to paste in a name which you previously copied to theClipboard.

Folder icon to open the Locate Object dialog box and select adesign element from a list of elements.

If you choose Named Element - View or Folder, an option appearscalled “Simple appearance.” If you check this option, the View actionbar is hidden when the view or folder is loaded into the frame.


If you want a view or folder on the Web, consider first embeddingthe view or folder on a page or form. If you choose to make theembedded view an embedded view applet, you preserve much ofthe HTML view functionality and provide features such as resizeablecolumns, multiple document selection, and scrolling.

URL

To put a Web page into a frame, choose URL and enter the full URLspecification (for example, http://www.lotus.com). You can alsopaste in a URL or use a formula that evaluates to a URL. You receivean error in the frame if the URL you specify is not accessible. Notethat all content rendered in framesets in Designer uses the nativeNotes Web browser even if your current browser selection issomething else.

When you click a link in a Web page (in the Notes client or in a Webbrowser), the link may open within the same Web page or in a newwindow, depending on the setting for that Web page.

5. (Optional) Enter the target frame for links activated within the currentframe.

Specifying a target frame In addition to adding content to a frame, you can target a specific frame of aframeset so that data opens in the target frame. You specify a target framein the Frame Properties box or in the Properties boxes of many otherelements (such as the properties boxes for pages, forms, outline entries,embedded outlines, group scheduler, and hotspot resources).

The target frame set in the property box of the element takes precedenceover the target frame set in the Frame Properties box. For example, youcreate a frameset with three frames: NewPage, Target1, and Target2. Youset Target1 as the target frame in the Frame Properties box for NewPage.NewPage also contains a URL link. You set the URL to open in Target2 inthe Hotspot Resources Properties box. When a user opens the frameset onthe Web or in the Notes client, links in NewPage open in Target1; however,the URL link overrides the target set for NewPage and opens in Target2.

If there is no target frame specified in the element, then the target frame setin the Frame Properties box is used. If you specify a target frame that doesnot exist, the link opens in a new, top-level window. If you do not specify atarget frame, the link opens in the frame that contains the link.

For more information on specifying a target frame for an individual link orelement, see the on-line help for that element’s properties box.

Note Remember to specify a name (in the Frame Properties box) for anyframe that is going to be a target frame.


Using the View menu with framesetsWhen you are designing frames and framesets, the View menu contains thefollowing commands:

Refresh all — refreshes the content of each frame with changes youhave made since opening the frameset.

Show Frame Content — once you have populated the frames, you canuse this menu option to view either the actual content of the frame or ashort description of the frame content. For example, instead of an actualWeb page appearing in a frame, the frame contains text such as:Content type: URL

Content value: http://www.lotus.com/

Setting the style for framesYou can set properties such as scroll bars, size of frames, and borderproperties in the Frame Properties box.

Note The Web browser you use may not fully support all the propertiesyou can set in the Frame Properties box.

To set the style for each frame:

1. Choose Frame - Frame Properties.

2. At the Frame Size tab, you can specify the following properties for eachframe:

Width and height for the frame

You can choose relative, percent, or pixel to specify the frame widthand height:

Relative — sizes the frame relative to the other frames in theframeset. For example, a frame with no frames above or below it isautomatically set to relative and is the height of the frameset.

Percent — sizes the frame as a percentage of the frameset. A frameset to 50 Percent width is half the width of the frameset.

Pixel — sizes the frame exactly in pixels.

Note that if you change the width and height properties for oneframe, the width and height of adjacent frames will change;however, the properties of adjacent frames are not automaticallyadjusted. Adjacent frame properties are adjusted if you drag theborders.


Scroll bar properties. Choosing On forces a scroll bar for the frame;choosing Off causes no scroll bar to appear. If you choose Auto, thescroll bar appears if it is needed. The default is Auto.

Allow Resizing. If you choose Yes, you allow users in the Notesclient or Web browser to change the height and width of frames bydragging their borders. If you choose No, users cannot drag bordersto resize the frame.

3. At the Frame Border tab, you can specify the following properties:

For “Border Style (Applies to this frame):”3-D border — allows three-dimensional borders between the currentframe and its adjacent frames. Apply to all frames — adds three-dimensional borders between allframes in the frameset.

For “Border Style (Applies to all borders in frameset):”Border width (in pixels) — The default is 7 pixels. Border color — choose a color from the drop-down color chart. Clickon the system (monitor) icon at the top of the color chart to get thedefault color. Click on the wheel icon at the top of the color chart tocreate a custom color.

4. At the Advanced tab, specify the Frame spacing and margin height andwidth.

Frame spacing. The default is minimal space between frames. Youspecify spacing between frames in pixels. This property is notsupported in the Notes client.

Margin height and width. The default is minimal space between theframe border and the frame content. You specify height and width inpixels. This property is not supported in the Notes client.

Launching a database into a frameset

You can have a frameset display automatically when you open a Notesdatabase:

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 viewlink, document link, or @command is used to open a database, the framesetmay not open.


Launching a form or page into a frameset

You can specify that a form (and the documents created with that form) or apage open automatically in a specific frame of a frameset.

1. Open a form (or page).

2. Choose Design - Form properties to open the Form Properties box.


4. In the Frameset field, select the frameset in which you wish to launchdocuments that are based on this form.

5. In the Frame field, select the frame in which you wish to displaydocuments based on this form.

Note that you can select only framesets that are located in the samedatabase as the form on which you are working. Make sure that you havealready given the frame a name in the Frame Properties box.


Chapter 8Designing Views

This chapter describes how to design views. Views help users find thedocuments they want and serve as summaries of the database contents.

For information on importing or exporting views, see Appendix B.

Views

A view is a sorted or categorized list of documents. Views are the entrypoint to the data stored in a database. Every database must have at leastone view, although most databases have more than one view.

Here are the general steps in planning your view:

1. Before you actually create the view, think about:

The type of view you want (shared, private, and so on).

Whether the view is a standard view or a calendar view.

The categories in the view.

Whether you want to create an embedded view on a form, subform,page, or document.

Whether the view will be displayed on the Web. If so you may wantto consider creating an embedded view on a form, subform, page, ordocument or consider creating a view applet or an embedded viewapplet.

2. Create the view by clicking the New View button in Designer.

3. Name the view.

4. Add columns to the view.

5. Set up which documents will display in the view by writing the view’sdocument selection formula.

6. Set up what will display in each column by programming the columnvalue.

7. Set up the sorting order for the columns.

8. Set the style for the view, row, and columns.

9. Close and save the view.

173

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

Standard viewsA standard outline view is a table of contents for a database and is the mostcommon type of view. It organizes documents by rows and columns. Eachcolumn displays a type of information about the document, such as authoror date of creation. Each row displays selected pieces of information fromone document. One column in the view is usually the organizing element —for example, a column entitled Date might organize the documents inchronological order. In a discussion database, you might use a columnentitled Topic to display the contents of the Subject field for each documentin the view. In a tracking database, it might be the customer or productname.

Here is the same view from a review database as shown through NetscapeNavigator and through Notes.


Standard views, whether in Notes or on the Web, contain the defaultsettings in the View Properties box. For example, the checkboxes in the “ForWeb Access” section of the Advanced tab of the View Properties box are notchecked. If you want to create a view for the Web, consider creating a viewapplet or embedded view applet.

To open a document in a standard view, Notes users double-click a row;Web users click a document link in one of the columns.

A standard view on the Web maintains the column and row format ofstandard Notes views (unless you use HTML formatting to customize aview), except that on the Web, a navigation bar on the top or bottom of thescreen contains buttons that users click to expand, collapse, and scroll theview.

On the Web, each time you open, scroll, expand, or collapse a view, Dominoconverts the view to an HTML page. Each “snapshot” of the view is a newlygenerated HTML page. The concept of a “selected document” in a view inNotes does not apply to a view on the Web.

To prevent line wrap on the Web, specify 1 in the “Lines per heading”setting in the View Properties box. Domino converts this setting to aNOWRAP HTML attribute. Specifying a number greater than 1 causes linesto wrap on the Web. The same guidelines are true for the “Lines per row”setting.

Chapter 8: Designing Views 175

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

When you create a calendar view, users have access to the followingfeatures:

Choices for viewing entries in a Two-Day, Week, Two-Week, Month, orYear format.

Point-and-click navigation among days, months, and years.

The ability to create new calendar entries and edit existing entries.

Integrated Task, Event, and Anniversary display.

The ability to print calendar entries for a selected range of days.

Web users can see all calendar entries. Domino converts calendar views toHTML tables. Therefore, Domino restrictions for tables also apply tocalendar views. You cannot create new appointments or scroll throughentries within a single day on the Web.


Converting a view to a calendar viewYou may have an existing view which you want to convert to a calendarview. A calendar view is similar to the standard outline view except that thecalendar view is limited to sorting only on a Time/Date field, which mustbe the first column in the view. The Mail template contains an example of acalendar view.

1. Create the first column based on a field with a value of both date andtime. (for example, creation date and time) and choose a Sort option (forexample, ascending or descending) in the Column Properties box. Makesure you specify both a date and a time, even if the time is 00:00.

2. Create the second column based on a field with a number value thatspecifies the duration, in minutes, of a calendar entry.

3. Create a document selection formula for the view. The formula shouldselect all documents containing the Time/Date field.

4. Choose Design - View Properties and select Calendar as the style.

If you select the column sorting option “Show multiple values as separateentries” for the first column, documents display under different dates.Otherwise, they display only under the first matching date. The Mailtemplate uses this technique for displaying repeating events.

Troubleshooting a calendar viewIf the calendar view does not display as you expect, there may be a problemwith the selection formula or with the definition of the first column.

Check the selection formula for the view. Make sure the documents youwant to display in the view match the selection formula. To test theselection formula, change the view to a standard view or refresh the viewwhile in Designer. If the documents display, the selection formula is valid.

Make sure the first column of the view is based on a Date/Time field and issorted in ascending order. Display the column in Designer. Both the dateand time should display. The date determines where the document displaysin the view, and the time sorts entries in the correct order, so that a 9:00 AMappointment displays before a 3:00 PM appointment.

The first two columns of a calendar view define the Date/Time and theduration of an appointment. Make these hidden columns. To display thetime, create a separate time column.


Shared and private views

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

Shared viewsShared views are available to any user with at least Reader access to thedatabase. Most views that you design for databases are shared views. Userswith Designer or Manager access can create shared views, as can Editors forwhom the manager has selected “Create personal folders/views” in theaccess control list.

You can create the following specific types of shared views:

Shared, contains documents not in folders

Shared, contains deleted documents (used in conjunction with “Allowsoft deletions” in the Advanced tab of the Database Properties box)

Shared, private on first use

Shared, desktop private on first use (saves private views in users’desktop.dsk files rather than in the database)

Shared, contains deleted documentsA “Shared, contains deleted documents” view allows you to view a list ofdocuments in the database which have been deleted. You can recoverdeleted documents by dragging them out of the trash to the folder whereyou want them. This view assumes that the database manager has alreadyselected “Allow soft deletions” at the Advanced tab of the DatabaseProperties box. The “Allow soft deletions” property lets deleted documentsremain in the database and not be permanently removed for a set numberof hours. The hours are set by the database manager in the Advanced tab ofthe Database Properties box. After that time, the document is permanentlydeleted from the database.

Shared, private-on-first-use viewsA “Shared, private-on-first-use” view begins as a shared view and becomesa private view as soon as a user accesses and saves the view. These viewsare a convenient way to distribute customized personal views to multipleusers. You usually create this type of view by using @UserName tocustomize the display for each user.


After a user saves a shared-to-private view, the user’s copy of the view nolonger inherits design changes. For example, if you add a column to theview, 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 theview and open the shared-to-private view again.

Shared-to-private views are not a security measure, as they do not protectdata. If you create a shared-to-private view that omits certain documents, auser can still create a private view that includes them.

Shared-to-private views are stored in the database as long as they areshared. 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 viewsIf you want the shared-to-private view to be stored in a user’s desktop.dskfiles rather than in the database, choose “Shared, desktop private on firstuse” as the View Type when you create the view.

Private views Users can create private views to organize documents in personalized waysby choosing Create - View.

If a user has rights to create private folders/views in the access control list,private views are stored in the Notes database. If the user does not have theaccess control list right to create private folders/views, personal views arestored in the user’s personal workspace file (desktop.dsk).

Private views are not supported on the Web.

Creating a viewTo design a view, you must have Designer access in the access control list ofthe database. For information on database access, see Managing DominoDatabases.

1. Select or open a database in Designer.

2. Click Views in the Design pane.

3. Click the New View button above the Work pane. The Create Viewdialog box appears.

4. Enter a name for the view in the View name field.

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, do not select anything inthis field. Otherwise, click the name of the view under which you wantthe new view to appear.

7. Click the “Copy style from” button.

Click Blank if you do not want to copy another view’s style. Otherwise,click the view whose style you want to copy. If the style uses selectionby formula, the view’s selection criteria appears in the “Selectioncriteria” field.

8. (Optional) You can use the Fields and Functions button and Formulawindow button to further refine the new view’s selection criteria.

9. Click OK to create the new view.

10. Double-click the new view in the Views list to open it.

11. Click the column labeled “#,” choose Edit - Clear, and Yes to confirm.

12. Choose Create - Insert New Column to create the first column.

13. Add other columns by choosing either:

Create - Insert New Column to create a column to the left of thehighlighted column.

Create - Append New Column to add the column after all existingcolumns.

14. To give each column a title, choose Design - Column Properties andclick the Column Info tab. Enter a name in the Title field.

15. Click each column in the Work pane. In the Programmer’s pane, addprogramming to determine the column value. For example, a columncan list the creation date or the size of each document.

16. Click the current view in the Objects list and expand it. Select ViewSelection and add programming for the view’s document selection.

17. Choose Design - View Properties and click the Style tab to style theview.

18. Click each column and choose Design - Column Properties. Click theTitle tab to determine the font, size, color, and alignment of the columntitle. Click the Font tab to do the same for values that display in thecolumn.

19. Close and save the view.


Default design for new viewsTo save design time, designate a view as the standard for newly createdviews or folders in the database. To use a view as the design standard, openthe view in Designer and select “Default design for new folders and views”on the Options tab of the View Properties box.

Copying and deleting views and columnsTo copy a view, click Views in the Design pane, in the Work pane click theview you want to copy, choose Edit - Copy, and then Edit - Paste. A copy ofthe selected view appears in the list of views. Until you rename it, thecopied view is named “Copy of <selected view name>”.

To delete a view, click Views in the Design pane, in the Work pane click theview you want to delete, click the view name, and choose Edit - Clear.

To copy a column, open the view in Designer, click the column, copy it tothe clipboard, select the column to the right of where you want the columnto appear, and choose Edit - Paste.

To delete a column, open the view in Designer, click the column, andchoose Edit - Clear.

Limits for views A view can display no more than 32 levels of responses and/orsubcategories. For example, if you have 6 levels of subcategories, you candisplay 25 levels of responses to a main document. If there are more levelsof 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 cascadefrom the top level cannot exceed 200; otherwise, the top-level menus do notdisplay 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 displayedon the View menu.

Naming a viewThe name you choose for a view is visible to Notes users in the View menuand in the folders pane (unless the view is hidden). The view name isvisible to Web users in the Views list. The name is case-sensitive and can beany combination of characters, including letters, numbers, spaces, andpunctuation. The full name, including all aliases, can have up to 64characters.


Naming tipsViews appear in alphabetical order in the View menu in Notes and inthe View lists on the Web. To force names to appear in a different order,number or letter them. For example:

1. Zebra

2. Antelope

If you start a name with a hyphen (-), the name appears before bothnumbers and letters.

When possible, assign a name that indicates how the view sortsdocuments — for example, By Company Name or All by Category — orspecifies which documents it includes, for example, New Customers.

Use consistent names across databases to make it easier for users torecognize views.

AliasesAn alias is another name, or synonym, for a particular view. Use an alias tochange or translate the view name without causing lookup formulas thatreference the view to stop working. Aliases follow the same naming rules asview names.

Enter an alias in the Alias field of the View Info tab of the View Propertiesbox. 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 therightmost name.

Main View | Top View | View1

Changing a view nameYou can edit the view name or alias in the View Properties box when theview is open in the Designer. If you change the name of the view, copy andpaste the previous name into the Alias box to the left of any other aliases,using | as the separator.

For example, your movie database is going to be converted to German. Thetranslators change the name “By Premiere Date” to display the view namein German on the View menu. They enter the new name in the Name fieldof the View properties box:

Nach Premierendatum

To keep both “By Premiere Date” and “DateView” as aliases, they enter thefollowing in the Alias field of the View properties box:

Nach Premierendatum | By Premiere Date | DateView


Naming guidelines

Hidden viewsWhen you surround a name with parentheses — for example, (All) — theview does not appear to Notes users in the Notes View menu or to Webusers or Notes users in the list of folders and views.

For other ways to hide views, see Hiding a view later in this chapter.

Shortcut keysWindows, OS/2, and UNIX users can type shortcut letters to select a view.The default shortcut, an underlined letter in a view name, is the first letterin the name that has not already been used by a preceding name on themenu. But if views or folders begin with the same letter, the defaultshortcut is the first letter that has not already been used by a precedingname. If views or folders begin with the same letter, the shortcut letters maybe difficult to see and remember. For example, the shortcut letters(underlined) for these views are

By Author

By Date

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

Authors

Dates

If you can’t change the names, you can specify a more meaningful shortcutby typing an underscore before the letter D to assign it as the shortcut forthe By Date view, entering the name as

By _Date

Cascading viewsCreating cascading views lets you arrange lists of views in a hierarchy; thatway, a group of related menu items are organized under one item. A userclicks on the higher-level name to display the cascaded list. You probablywant to cascade views when you have long lists of views or when you haverelated views that should be grouped together.

To create a cascading view, enter the name you want to appear on theCreate menu followed by a \ (backslash), followed by the view name. Forexample, the Personal Address Book template has two views related toservers:

Server\Certificates

Server\Connections


Columns

Columns display one type of information about the documents listed —such as the document subject, author, or creation date. One column in aview is usually the organizing element — for example, in a chronologicalview, the organizing column displays document creation dates.

To add a column to a view in Designer, choose Create - Insert New Columnor Create - Append New Column.

A view can have a single column or as many columns as you can fit in 22.75 inches (the allotted width of a view).

Adding titles to columnsA title is optional text at the top of a column that helps users identify thetype of information in the column. Assign a title using the ColumnProperties 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 theschedule.” To avoid cluttering the view, don’t include titles for everycolumn.

Omitting a titleIf you leave the title blank, the column doesn’t have any identifying text.Omit a title if the column is:

A responses-only column that indents response documents

A categorizing column

Hidden (and designers don’t need any identifying text when the view isDesigner)

Not relevant to users

GuidelinesColumn titles can contain up to 80 characters in any combination ofletters, numbers, and punctuation.

To change the font, size, or color of a column title, choose styles fromthe Title tab of the Column properties box.

To allow long titles to wrap to several lines in Notes, set the “Lines perheading” in the Style tab of the View Properties box to a numbergreater than 1.


Note that long titles do not wrap on the Web. To prevent line wrap onthe Web, specify 1 in the “Lines per heading” setting in the ViewProperties box. Domino converts this setting to a NOWRAP HTMLattribute. Specifying a number greater than 1 causes lines to wrap onthe Web. The same guidelines are true for the “Lines per row” setting.

The number of characters that fit on one line depends on the font andsize you select, as well as the width of the column. If a title is not set upto wrap to more than one line and the text is too long for the width ofthe column, the text is truncated.

Adding categories to viewsA category is a grouping of related documents. A view that displayscategories enables users to find those related documents. For example, in anemployee view, you can create a category called Ohio and include in thatcategory documents created by only those employees who work in Ohio. Acategorized view is neat and easy to scan. Users can collapse the categoriesto display only the category names, and then expand categoriesindividually, or expand the whole view.

To categorize a view, create a column to display categories and then selectthe option “Type: Categorized” on the Sorting tab of the Column Propertiesbox. The resulting column, called a categorized column, groups documentswith 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. Thiscolumn must always appear to the left of any sorted columns.


Other options include:

(Recommended) At the Text Properties tab of the Column Propertiesbox, choose a different color for column text and use bold face to makecategories stand out.

(Recommended) At the Sorting tab of the Column Properties box, selectthe column style: Sort: Ascending or Sort: Descending to organize thecategory names. (Sort: Ascending organizes the categories inalphabetical order and descending in reverse alphabetical order.)

(Recommended) At the Column Info tab of the Column Properties box,select “Show twistie when row is expandable” to display a triangle thatusers click to see categorized documents.

(Optional) At the Options tab of the View Properties box, select“Collapse all when database is first opened” to show only the categorynames when users open the view.

(Optional) At the Advanced tab of View Properties box, select “Don’tshow categories having zero documents” so that categories with nodocuments associated with them are not listed.

Categorizing in the All by Category viewTo let users categorize documents with Actions - Categorize, a databasemust have these components:

A form with a Categories field

Field name: Categories

Data type: Editable text or choice list field

Select “Allow multi-values”

Format: If you selected a choice list field, leave the choice list blank andselect “Allow values not in list”

A view named All by Category

In the All by Category view, a Categories column placed as the leftmostcolumn.

Width: 1 character

Column title: Leave the column title blank

Formula: Categories;

Sort the column by selecting “Sort: Ascending” and “Type:Categorized”


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

Setting up a Categories fieldYou can produce a categorized column based on a Categories field. To setup 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 populatethe field with values.

To categorize documents created with the form, choose Actions -Categorize.

Setting up categories in advanceTo set up a predefined list of categories, create a computed choice list fieldand enter the category names as its values.

Converting choice list field aliases to full category namesIf you base a categorized column on a choice list field that contains aliasesfor the fields, those aliases are used as the category names.

For example, a RequestType field that contains the following choice listfields 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 hiddenfield 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 boxTo let users enter their own categories in the Actions - Categorize dialogbox, include an editable, multi-value, choice list field called “Categories” onthe form and select the field option “Allow values not in list.”

Generating dynamic lists of categoriesTo generate dynamic lists of categories, create a choice list field namedCategories. Then, use the @DbColumn formula to calculate values for thefield.

Examples: Generating category namesDisplaying the names of monthsThis formula is useful for a categorizing column that displays the name ofeach month as a category name. Dates need to be converted to a text valueto be displayed in a view.

m :=@Month(@Created);

@If(m = 1; "January"; m = 2; "February"; m = 3; "March";m = 4;"April";m = 5; "May"; m = 6; "June";m = 7; "July";m = 8;"August";m = 9; "September"; m = 10; "October"; m = 11;"November"; m = 12; "December"; "")

To sort these in proper order, add a hidden column to the left of thiscolumn that sorts documents in ascending order with the formula

d :=@Month(@Date);

@If(d = 1; "A"; d = 2; "B"; d = 3; "C"; d = 4; "D"; d = 5;"E"; d = 6; "F"; d = 7; "G"; d = 8; "H"; d = 9; "I"; d = 10;"J"; d = 11; "K"; d = 12; "L"; "")

Adding subcategories to an All by Category viewIn your Furniture Catalog database, you want to add subcategories,indented under the main categories, to make documents easier to find in the All by Category view. Subcategories are indented under main cate-gories automatically in a categorized column. You can have 32 levels ofsubcategories.

The Categories field of the Furniture Description form is an editable choicelist field with the following entries:

Bedroom

Kitchen

Living Room


To add subcategories, rewrite the choice list choices as follows, updateexisting documents, and refresh the view. A backslash (\) after a main entrydenotes the subcategory name.

Bedroom\Beds

Bedroom\Dressers

Kitchen\Tables

Kitchen\Chairs

Living Room\Sofas

Living Room\Tables

Recategorize the documents that already exist to assign them to one of thesubcategories. You can do this manually with Actions - Categorize bytyping the full subcategory specification (Bedroom\Beds) into theCategories dialog box. If there are many documents, create agents that setthe new values for the Categories field of each document.

Press SHIFT+F9 to rebuild the view index so documents display with theirnew subcategory names.

Programming which documents display in a view

When you design a view, you can program it to show all documents oronly certain documents in the database. Most databases have one view thatshows all documents and other views that show a subset of documents.

The default selection for new views is the combination of the SELECTstatement and the @All formula: SELECT @All, which means “include alldatabase documents in this view.” To narrow down the kinds of documentsthe view displays, add a program that displays only particular documents.For example, in a task-tracking database, the Work in Progress view coulddisplay only those documents whose Status field does not contain“Complete.” In a brainstorming database, the Design Ideas view coulddisplay all documents categorized as “Design Suggestion.” Here is aprogram that displays only documents containing new features anddisplays them in a What’s New view:

SELECT @IsMember(“01 What’s new?” ; View)


Choosing the type of programWith a view you program the document selection in the Programmer’spane. Choose “View Selection” in the Objects box, select the type ofprogramming you want to add, and build the program in the windowbelow.

EasyEasy allows you to create a conditional document selection withoutknowing a programming language. In the Info List of the Programmer’spane, click the Run drop-down box and select Easy. Then click AddCondition for each selection you want to include. To delete a condition,click it and choose Edit - Clear.

FormulaFormula allows you to create a program for selecting documents. Theprogram uses 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 viewSelecting documents by form name and field valueIf a database contains an Action Item form that contains a Status field, aview in the database can select all documents that were created with theAction Item form whose Status field contains the value “Open.” Thedocument selection formula is:

SELECT Form ="Action Item" & Status="Open"


Selecting only non-response documentsTo select only documents that were created with main document forms andexclude documents created with response or response-to-response forms,use this formula:

SELECT !@IsResponseDoc

Selecting main and response documentsIf a database contains a form called Action Item, you can select alldocuments that were created with the Action Item form, as well asresponses to these documents, using the formula:

SELECT Form = "Action Item" | @IsResponseDoc

Selecting documents not created with a specified formThe Databases by Title view in the Database Library template selects alldocuments that were not created with the Librarian form using thisformula:

SELECT Form != "Librarian"

Table of document selection conditions for views

When you click Easy as the Run: View Selection formula, you have theseselection options. You can combine multiple conditions to narrow down theselection. Click Add Condition to see the full list.

Condition Selection 1 Selection 2

By Author containsdoes not contain

<author name> or choose fromAddress Book

By Date date createddate modified

is onis afteris beforeis not onis in the last <n> daysis in the next <n> daysis older than <n> daysis after the next <n> daysis betweenis not between

By Field <field name> containsdoes not contain

continued


Condition Selection 1 Selection 2

<date field name> is onis afteris beforeis not onis in the last <n> daysis in the next <n> daysis older than <n> daysis after the next <n> daysis betweenis not between

<number field name> is equal tois greater thanis less thanis not equal tois betweenis not between

By Form <form name> <field values> for multiple fields

By Form Used <form name>

Table of document selection conditionsEasy conditionsThe Easy condition determines whether a field contains one value. Becausethe Easy condition reads any separators you enter as text, it can’t look for allthe values in a multi-value field.

The Easy condition also can’t determine whether a particular field is presentin a document. You must click Formula and write a formula to do that.

Selecting documents by authorDocuments must have an Authors field for this selection method to work.

When selecting By Authors, enter a name or names, separated by commas.If you know a 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 PublicAddress Book to browse for person names, but do not select any groupnames.

For more information, see “Addressing a message by choosing names froman Address Book” in Notes Client Help.


Selecting documents by dateThe Date created condition selects documents based on the Created date inthe Document Properties box.

The Date modified condition selects documents based on the Modified datein the Document Properties box.

Selecting documents by field valueIf 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 isempty. You must click Formula and write a formula to do that. Forexample, to select documents where the Research field isn’t empty, use thisformula:

SELECT Research != ""

For example, to select documents that have the field Research, use theformula:

SELECT @IsAvailable(Research)

By form nameWhen selecting By Form as a condition for a selection formula, thecondition works only with forms that are part of the database design, notwith forms stored in documents.

Selecting main and response documents with a formulaBy default, selection formulas include only documents of the type MainTopic. You can include response documents in a selection formula createdwith one of the simple functions above by editing the formula Notes createsand appending

| @IsResponseDoc


Adding programming to columns

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

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

FieldField lets you populate the column with field values without writing aprogram. This technique works only with text fields because columns needa conversion formula to interpret other types of data — that is, dates, richtext, or numbers, or encrypted text.


FormulaFormula lets you create a program for a column using the @functionformula language. This is useful when you must process values in adocument (such as changing field values to a text value) or calculate avalue. Typical uses for formulas include converting field data to a text value(because only text values display in columns), writing a formula thatdisplays 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 tothe data type that your formula expects. For example, to append a numericvalue to a text value in a column, use a formula like:

Product + ": " + @Text(Quantity)

Examples: Adding programming to columnsDetermining text, based on a field valueIn a column, you can show custom text based on a condition or on anumber of conditions. For example, you can create a formula that displayscustom text if sales exceed a certain amount. This formula tests the value inthe Sales_February field (a number field) and displays text based on thatvalue:

@If(Sales_February>60000;"Great month!";"")

Determining text, based on the form nameThe Subject column in the All Documents view of the Mail template usesthe following formula. It displays a subject line based on the form thedocument 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 datesYou can combine text and field values in a column in a scheduling databaseto add an explanation about the documents. The formula below displays atext message and a date, with two variations that depend on the value inthe Sched field. The “D1S0” part of the @Text formula is a formattingoption that removes clutter from the view by showing the month and dayportion of the date field only and omitting the exact time.

@If(Sched = "Special schedule"; "Special schedule for the weekof: " + @Text(Date; "D1S0"); "My regular schedule, as of " +@Text(@Modified; "D1S0"))


Combining text and namesThe following formula results in three possible results, based on the statusof a request:

@If(Status=“Rejected” ;“Rejected by“ + LastApproveName;SignatureCount=0; “Original Request” ;“Approved by” +LastApproveName)

If the request has been rejected, the column displays “Rejected by” andthe name of the person who last signed the form.

If the request has no signatures (meaning that no approver has acted onthe request), the column displays “Original Request.”

If the request has been approved, the column displays “Approved by”and the name of the person who last signed the form.

Showing when a document was createdThe Created column in the By Author view of the Document Librarytemplate uses the following formula to display the date on which thedocument was created:

@Created

Expandable levels (variation on the simple function)The simple function Collapse/Expand (+/-) uses @IsExpandable withoutany arguments. If you want to display a + (plus symbol) when a documenthas responses, but suppress a - (minus symbol) when responses areexpanded, use the formula:

@IsExpandable("+";"")

Displaying two field values in one columnTo show people’s names and phone numbers together in one column, createa column that is sorted in ascending order (the recommended order foralphabetical listings). The following formula separates the two field valueswith a blank space:

Name + " " + Phone

Creating “fake” indentingWhen Notes indents response documents, the indentation is always thesame. If you want to make a document in a flat view appear indentedwithout using response documents, or display document titles in the samecolumn at different indentations, you can use a field on the form todetermine how much each document indents and use a column formulathat appends space characters to the document titles in the view. Thefollowing formula “indents” documents in three different ways dependingon the value in the Indent field. For example, if the value of the Indent fieldis 3, Notes prepends 18 space characters to the Subject of the document inthe column.


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

Numbering documentsIn a By Author view, the following formula numbers (as in 1., 2., 3.) each ofthe documents within each author’s category:

@IsCategory("";@DocNumber("") + ". ")

If the row is a category (the author’s name), @IsCategory returns a nullstring (“”). If the row isn’t a category, then the row represents a document,and @DocNumber returns a string that represents the entry number of thedocument. 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 returnsthe rightmost component of the entry number. The formula then adds aperiod and a space “. ” after the number.

Table of simple functions for columns

The following simple functions (that is, functions that let you addprogramming without knowing a programming language) can be used with columns.

Function name Description Example

AttachmentLengths

Displays the file size of documentattachments. The data type is anumber list.

Attachment Names Displays the file name ofdocument attachments. The datatype is a text list.

Attachments Displays the number of filesattached to each document. Thedata type is a number.

continued



Author(s)(DistinguishedName)

Displays document author namein hierarchical format, as in DeniseLee/Research/Acme.

Author(s) (SimpleName)

Displays the document authorname without its fullydistinguished format, as in DeniseLee.

Collapse/Expand (+/-)

Use in a column styled as aSorted/Categorized column.Returns a + (plus symbol) if theview entry has descendants thatare not visible because the maindocument is collapsed. Returns a – (minus symbol) if there are nosubordinate documents or ifsubordinate documents arecurrently visible. Useful when aview contains a large number ofresponse documents.

Creation Date Displays the time and date adocument was created.

Last Modified Displays the date when adocument was last saved.

Last Read orEdited

Displays the last time and date adocument was read or edited.

continued



Size (bytes) Displays the file size ofdocuments.

# in View Displays a number for eachdocument indicating its order inthe view. Responses are numberedin outline style under Maindocuments — for example, thefirst response to the first main is1.1.

# of Responses (1Level)

Displays the number of directdescendant (response) documentsfor a document or next-levelsubcategories for a category.

# of Responses (AllLevels)

Displays the total number ofdescendant (response andresponse-to-response) documentsfor a document or subcategoriesfor a category.


Displaying an icon in a column

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

An icon column has two requirements:

The column property “Display values as icons” is selected.

The column uses a formula that results in a number that corresponds tothe icon you want to display.

The graphics used in column icons can’t be customized, but you can choosefrom more than a hundred predefined column icons.

Programming columns to display iconsThe following formula determines whether a document has an attachmentand, 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. Theformula above returns 0 when the document has no attachments, so nothingis displayed.

A column that displays icons can’t display anything else, such as a plus (+)sign for an expandable categories column.

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


column. You can’t add your own icons; you must choose from the iconsshown below.

Sorting documents in viewsEvery view needs a sorting method that organizes documents in a way thatmakes sense to users. For example, a By Date view sorts documents by theircreation dates, and a By Author view sorts documents by author names. Toachieve this effect, designate at least one column as a sorting column. Thendefine it as a user-sorted column, an auto-sorted column, or both.

Views that display categories often use sorting methods to alphabetize thecategory names.

If the sort column displays values from a multiple-value list, select “Showmultiple 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 and sort bythe first value.

Note that sorting columns is not supported on the Web.


User-sorted columnsUsers 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 headerto sort” on the Sorting tab of the Column Properties box. Then selectAscending or Descending order, or select Both to allow users to cycleamong ascending sort order, descending sort order, and no sort order forthe column.

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

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


Using an auto-sorted column as the secondary sorting columnTo add a secondary sorting column, add a column to the right of the firstsorting column and then choose Sort: Ascending or Sort: Descending on theSorting tab of the Column Properties box. Documents and responses aresorted, then sub-sorted, in column order from left to right.

Designating a secondary sorting column for a user-sorted columnUser-sorted columns override the sorting built in to auto-sorted primaryand secondary columns. If the view has a user-sorted column and you wantto include secondary sorting, you can associate it with a secondary sortingcolumn. On the Sorting tab of the Column Properties box for a user-sortedcolumn, click “Secondary sort column” and choose the secondary sortcolumn and its sorting order.

Ascending and descending orderColumns sort documents in ascending or descending order:

Ascending order sorts in increasing order (1 precedes 2, A precedes B,earlier dates precede later dates).

For example, to display documents from oldest to newest, create a Datecolumn that uses the Creation Date as its value and sorts documents inAscending order.

Descending order sorts in decreasing order (2 precedes 1, B precedes A,later dates precede earlier dates).

For example, to display documents from newest to oldest, create a Datecolumn that uses Creation Date as its value and sorts documents inDescending order.

Character sorting rulesAfter the ascending or descending order is set, characters are sorted in thisorder:

numbers

letters

accented letters

punctuation/special characters


Case-sensitive and accent-sensitive sorting rules for Release 5 differ fromsorting rules in previous releases in the following ways:

Both case-sensitive sorting and accent-sensitive sorting are turned offby default (in previous releases, they were on by default).

“Case-sensitive sorting” sorts lowercase letters before uppercase letters — for example, “ab” sorts before “Aa.”

“Accent-sensitive sorting” sorts accented characters after non-accentedcharacters. For example, “ab” sorts before “äa.”

Overriding alphabetical sorting with a hidden column

The sorting column does not need to be visible. Sometimes you may want touse a hidden column as your sorting column.

For example, a Service Request form contains a Priority field, which usesthe following choice list:

UrgentHighMediumLow

You want the By Priority view to sort documents by the value in thePriority field, but you don’t want them to appear in ordinary alphabeticalorder (High, Low, Medium, Urgent). You want users to see Urgent-prioritydocuments at the top of the view, High-priority documents next, and so on.

You create a column that:

Is hidden

Has no title

Is one character wide

Uses this formula to determine the order of each priority:@If(Priority="Urgent";"1";Priority="High";"2";Priority="Medium";"3";"4")

Is sorted in ascending order

You add a column to the right of the hidden column that:

Is not hidden

Has the title “Priority”

Is 10 characters wide


Displays the value of the Priority field

Is not sorted

Customizing which column links to Web documentsTo open a document from a view, Web users click a column that links to thedocument. By default, Domino uses the leftmost column in a view as thelinking column, but you can change this default by designing anotherlinking column. After you set up customized linking, you cannot revert toDomino’s default behavior — you must continue to designate at least onelinking column in that view.

1. Click the column(s) you want to display as linking columns.

2. Open the Column Properties box and click the Advanced tab.

3. Select “For Web Access: Show values in this column as links.”

Adding pass-thru HTML to a column

To insert HTML in a column, click Formula in the Programmer’s pane,select Column value in the Object list, and add HTML as the column valuein the script area. Notes users may see the HTML if it is used in a view theycan see.

The following formula inserts the graphic new.gif if the document wascreated within the last five days; otherwise, no graphic is displayed.

@IF (@NOW > @ADJUST(@CREATED; 0; 0; 5; 0; 0; 0); "";"

[<img src=/gifs/new.gif border=0>]")

Using a column to switch to another view

To give users an easy way to see additional, related information thatdoesn’t fit in the initial view, use a column as an entry point to anotherview. 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 ColumnProperties box. Use the column title to alert users to this special kind ofcolumn. For example, you can title the column “Click here to switch to theBy Author view.”


Generating column totals, averages, and percents

To display totals, averages, or percents for a column’s numeric values, clickthe Sorting tab of the Column Properties box and select a Totals type otherthan None. Totals display in blue, unless you change the Column Totalscolor on the Style tab of the View Properties box.

Total calculates a grand total for all main documents and displays this totalat the bottom.

Average per document calculates an overall average by totaling the maindocuments and then dividing that value by the number of main documents.For example, if there are four documents and their total is 10, the averageper document is 2.5.

Average per sub-category calculates an average for each category. Withineach subcategory, the documents are summed; that value is divided by thenumber of documents.

Percent of parent category calculates a total for all main documents. Foreach category, Notes displays the category’s percentage as it relates to theoverall view total.

Percent of all documents calculates a total for all main documents. For eachcategory, Notes displays the category’s percentage as it relates to the overallview total.

You can select “Hide detail rows” to suppress subtotals for each categoryand subcategory to display totals without the clutter of extra numbers.

Totals calculate only for main documents; response documents are notincluded. Because column totals recalculate each time you open the view,they may affect database and overall server performance.


Table of view, row, and column styles

To make a view attractive and easy-to-use, consider the layout of the viewand its columns and rows. View, row, and column properties work togetherto display colors, widths, fonts, and so on. These options for views, rows,and columns are available in several properties boxes, as noted.

Option name Description Comments Location

View styles

Color:Background

Determines the backgroundcolor for the view.

White, light blue, andyellow are goodchoices.

Collapse all whendatabase is firstopened

Displays the top-levelcategory in categorizedviews or the maindocuments in a hierarchicalresponses view. Users clickthe category to seeindividual documentswithin the category.

Useful for large viewswith many categories ortopics. Not applicableto calendar views.

Row styles

Lines per row(1-9)

Determines how many linesa column can contain.

“Shrink rows tocontent” and “Color:Alternate rows” areuseful accompanimentsto multi-line rows.

Color: Unreadrows

Determines the color forunread documents.

Red is used for unreaddocuments in templatedesigns.

Color: Alternaterows

Determines the color thatalternates with thebackground color tohighlight every other row.

Useful for multi-linerows. Not applicable tocalendar views.

continued



Row styles (cont.)

Show selectionmargin

Shows the documentselection margin. Deselectfor cleaner-looking rows.

If you deselect “Showselection margin,” userscan still selectdocuments by pressingand holding SHIFT asthey click documentnames. The selectionmargin appearstemporarily whiledocuments are selected,and hides again whenall documents aredeselected.

Shrink rows tocontent

Keeps gaps from appearingbelow rows that are shorterthan the number of lines perrow you select.

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

Determines how muchspace there is between rows.

More space makes eachrow easier to read. Lessspace condenses theview contents to makeit useful for reports orWeb users.

Show twistiewhen row isexpandable

Shows a green triangle (bluetriangle on the Web) next toa column that displayscategories or responsedocuments.

Not applicable tocalendar views.

Extend lastcolumn towindow width

Fills out the last column toavoid empty space in theview.

Makes view easier toread.

continued



Column styles

Column width Determines how manycharacters fit in one row'scolumn.

(Optional) Select“Resizable” to allowusers to change thewidth as needed.

With the view inDesigner, you can alsoclick the column anddrag the columndivider line to thewidth you want.

Text style andcolor: Columntitle

Determines the font, size,color, and alignment of anindividual column title atthe top of the view.

Use “Apply to All”button to change thetext style for all titles inthe view.

Text style andcolor: Columnvalues

Determines the font, size,color, and alignment ofvalues that display in thiscolumn.

Use “Apply to All”button to change thetext style for allcolumns that displaytext in the view.

Hide column The column title and valuesdo not display to users.

Useful for columnsused for sorting thatcontain values usersdon't need to see. Thisis not a security feature.

Multi-valueseparator

For any documents thatdisplay multiple values inthe column, separates eachvalue with punctuation or anew line.

Useful for makingcolumns more readableif they contain severalvalues (usuallygenerated by amulti-value field).

Show columnheadings(Beveled, Simple)

Shows a bar at the top of theview with column titleswith either a beveled or flatlook.

Beveled--background isgray.

Simple--backgroundmatches view color.

Lines perheading (1- 5)

Determines how many linesa column title can wrap.

Useful for long columntitles or instructionsplaced in a column title.

Color: Columntotals

Determines the color of thetotal numbers for anycolumns that contain totals.

Calls attention to totals.


Using HTML formatting for views and columns

You can override the default row and column settings for a view by usingHTML formatting attributes stored in a column. In Notes, the view stilldisplays as a standard view. On the Web, the view uses the HTMLformatting attributes you specify in the column formula.

1. Open the view in Designer and choose Design - View Properties.

2. Click the Advanced tab and select “For Web Access: Treat viewcontents as HTML.”

3. Create a column.

4. In the Programmer’s pane, click Formula and write the HTML code inthe Script area. The HTML must define all formatting and documentlinking for the view.

Default viewsA default view is the view users see when they open the database for thefirst 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 alldocuments in the database, sorted by category, by date, or by author. In the Designer templates, the default view usually includes all documents inchronological order and shows main documents associated with responsesor supporting documents.

To specify the default view, use the option “Default when database is firstopened” in the Options tab of the View Properties box.

Defining what users see when they open views

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


Opening to a particular row in the viewTo highlight a particular row when a user opens the view, click On Open inthe Options tab of the View Properties box and select one of the followingfrom the list:

Go to last opened document (the default choice)

Go to top row

Go to bottom row

Collapsing the view to show only categoriesIf you have a view that displays categories, you can show the view incollapsed form every time users open it by selecting “Collapse all whendatabase is first opened” in the Options tab of the View Properties box.

Displaying the last-used viewIf you select “Restore as last viewed by user” (one of the “On DatabaseOpen” choices on the Launch tab of the Database Properties Box), Notesusers see the default view the first time they open a database, and thereafterthey see the last view they opened. This option isn’t available for viewsopened by Web users.

Page breaks in a viewYou cannot set page breaks for a view.

Formulas that look for values in columns and viewsLookup formulas are useful in choice list field formulas to search for valuesin another database or in the same database.

Referring to views in @function formulasTo 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 fullcascading name, with an additional “\” so that Notes can interpret thecascading name. For example:

"By Author"

"View1"

"By Author\\Last Name"


Referring to columns in formulasTo refer to a column in an @DbColumn or @DbLookup formula, use thecolumn number, rather than its title. Columns are numbered from left toright: the leftmost column is column number 1. Look at the view in thecolumn builder to make sure you see all its columns.

Some columns are not counted in a search, so skip them when you’recounting column numbers:

Skip any columns that display a constant value.

However, if a column contains a formula that happens to return thesame result for every document (so that it appears to be a constantvalue even though it is not), the column does not display a constantvalue. Include the column in your column count.

Skip any columns that consist solely of the following simple Notesfunctions 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, toretrieve data from a view, include a sorted column that the formula can useas the lookup key.


Indenting response documents

Indenting response documents beneath main documents is useful whenreaders want to see the progression of a discussion. You can display 32levels of responses, with each level indented three spaces under its parentdocument.

The following view in a discussion database displays the threads of adiscussion, organized by date.

Such a view requires that:

Users have access to response forms, whose types are Response andResponse-to-Response.

“Show response documents in a hierarchy” is selected in the Optionstab of the View Properties box and the document selection formula usesSELECT @All or contains a formula that allows response documents tobe included, such as:

SELECT Form = “Action Item” | @IsResponseDoc

The view has a responses-only column.

Create the responses column directly to the left of the column underwhich responses are to be indented. Leave its title blank, make its width 1, and select “Show responses only” in the Column Info tab ofthe Column Properties box. Write a column formula that displaysinformation about the response documents shown in the column, suchas their authors or creation dates.


Formulas for response columns

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

Including information about the authorA discussion database could show the response document author, date, andsubject line with the response column formula

From + " added this comment: " + Subject + " (" +@Text(@Created) + ")"

to show a response this way:

Stephanie Mahar added this comment: Great job! (10/10/97 04:43:15PM)

Tracking document statusIn an employee information database, a response column could show newemployee surveys and exit questionnaires for departing employees asresponse documents to the regular Employee Record in the Employees byName view. This formula shows two different messages depending on theform that was used for the response document and also displays themailing 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 mightlook like this:

New Hire Information, not yet mailed

Tracking the number of responsesYou can use @DocDescendants to keep track of numbers of responses, soauthors can quickly see how many responses they’ve received. This formulafor a main document column (not the responses column) is helpful inresponse-style views.

Subject + " (" + @Name([CN]; From) + @DocDescendants(")"; ", % response)"; ", % responses)")


If the document is a main document, the column displays the contents ofthe Subject field, the author name, and the number of response andresponse-to-response documents. If there is one response, the columndisplays “response.” Otherwise, it displays “responses.” Main documentrows might look like this:

Need Help with Trade Show (Indy Montoya, 1 response)

Changing the Product Name (Sandy Braun, 2 responses)

Displaying views in Web applicationsViews and folders created in Notes may not have as many features on theWeb. For example, a view or folder will display as a full screen with defaultnavigation buttons on the Web.

To gain more control on the Web, consider creating a view applet, anembedded view or folder, or an embedded view applet. When you embed aview or folder on a form, subform, page, or document, you maintain thesame functionality available in Notes applications, and you control the sizeand appearance of a view or folder display. When you define a view or anembedded view as a view applet, you preserve much of the HTML viewfunctionality and provide features such as resizeable columns, multipledocument selection, and scrolling.

Embedding a view or folder pane lets you combine views and folders withother form elements (such as styled text) and graphics to create a high-impact design. The Designer templates contain numerous examples offorms designed in this way.

If you have multiple views or folder panes you want to display in anapplication, you can create one or more view templates that control how theembedded objects display. A view template is actually a specially namedform that provides the design structure for displaying the embedded folderpanes or views in an application.


View applet

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


What the view applet does for Web applicationsWith the view applet, Web users can:

Resize columns with sliding panes

Collapse and expand views without the browser regenerating the page

Select multiple documents

Scroll vertically to view additional documents in the view

Use F9 to refresh the view

Use DEL to mark documents for deletion from the database

To display a view applet in a Web application1. Open a view in Designer.

2. Choose Design - View Properties to open the Property box.

3. Click the Advanced tab.

4. In For Web Access, select “Use applet in the browser.”

When you embed a view in a form, subform, or page, you can display theembedded view as an applet or override the setting when you setproperties for the embedded view.

To display an embedded view applet in a Web application:You can enable an embedded view applet independently of the element it isembedded in.

1. Open a form or page in Designer.

2. Place the cursor where you want the embedded view to display.

3. Choose Create - Embedded element - View and select the view youwant to embed.

4. Choose Element - View Properties to open the property box.

5. On the Info tab, specify in the Display drop-down box whether thisview should display as an applet by choosing one of the following:

“Using Java Applet” indicates the view’s setting should be used for thisembedded view.

“Using HTML” indicates that the view applet should not be usedregardless of the view’s setting.

“Using Views display property” indicates that the view applet shouldbe used in this embedded view regardless of the view’s setting.


Font support in the view appletThe View applet provides limited support for fonts. Since current versionsof the Java Developer’s Kit (prior to JDK 1.2) provide very limited supportfor text fonts, mapping between the Designer font set and the font setsupported by a specific Web browser is constrained by the JDK supportedby a browser. This can sometimes produce inconsistent results acrossdifferent Web browsers. For best results use one of the following font faces:Courier, Helvetica, or Times Roman.

Programming the view appletThe View applet is programmable through a number of @commands. Theseare:

@command Description

ViewCollapse Collapse the selected document

ViewExpand Expand the selected document

ViewCollapseAll Collapse all documents

ViewExpandAll Expand all documents

ViewRefreshFields Refresh view

Upon refresh, the view applet does not delete documentsmarked for deletion.

MoveToTrash Causes currently selected documents to be marked fordeletion

EmptyTrash Delete 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

Creating an embedded view or embedded folder paneWhen you embed a view or folder pane on a form, subform, page, ordocument, you maintain much of the view functionality available in Notesapplications. Embedding a view or folder lets you control the size andappearance of a view or folder display, especially on the Web.


Embedding a view or folder pane lets you combine views and folders withother form elements (such as styled text) and graphics to create a high-impact design.

1. Open a form, subform, or page in Designer, or open a document in Editmode.

2. Place the cursor where you want the embedded view or folder pane todisplay.

3. Choose one of the following:

Create - Embedded Element - View

Create - Embedded Element - Folder Pane

4. (Optional, for views) If you don’t want to display the same view in allcircumstances, click “Choose a View based on a formula.” When youclick OK to close the dialog box, write a formula in the Programmer’spane to display the appropriate view.

5. (Optional) Click the embedded element and choose Element - ViewProperties (or Element - Folder Pane Properties) to change thealignment or style, or to hide the element under certain conditions.

6. Close and save the form, subform, page, or document.

To delete an embedded view or folder pane, click the embedded view orfolder pane in the Work pane and choose Edit - Clear.

A form can have only one embedded view and one embedded folder pane.

Domino disregards the view title and background color of embedded viewsand uses settings on the Server document to determine the number of linesto display. Domino prevents the view opening if there are create or readaccess lists on a form in which views are embedded.

For compatibility with previous releases, the reserved fields $$ViewBodyand $$ViewList still work on forms.

An embedded view can be set as an embedded view applet.


Displaying the view navigation bar for embedded viewsIn a Web application, Domino doesn’t display the default view navigationbar for embedded views. To give Web users access to navigation functions,use these formulas to add view actions for Next, Prev, Expand, Collapse,and Search:

Action name Formula

Next @Command([ViewPageDown])

Prev @Command([ViewPageUp])

Expand @Command([ViewExpandAll])

Collapse @Command([ViewCollapseAll])

Search @Command([ViewShowSearchBar])

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

Show single category in embedded viewsYou can restrict an embedded view to a single category.

1. Open a form in Designer.

2. Choose Create - Embedded Element - View. The Insert Embedded Viewdialog box appears.

3. Highlight the view you want and click OK.

4. Choose “Show Single Category” as the event in the Programmer’s pane.

5. Enter a formula to compute the category. The formula can make use ofinformation about the current user and information from the currentdocument (the one embedding the view).

For the Show Single Category option to work, the embedded view mustfirst have been categorized. Note that the category name will not appear inthe embedded view. For example, if you check the Show Single Categorybox for a category named Kitchen, the embedded view will not have a linenamed Kitchen. Instead, you will see under Kitchen documents such asStove, Refrigerator, and so on.

You cannot use @Commands with Show Single Category.

If the Show Single Category formula evaluates to an asterisk (*), allcategories are shown. This is useful if, for example, you want to restrict anembedded view to a single category for Web users and show all categoriesfor Notes users.


Setting line counts in embedded viewsFor embedded views, you can specify the number of lines to display in thebrowser.

1. Create an embedded view in the usual way.

2. In the Info tab of the Embedded View properties box, enter the numberof lines next to “Lines to display in the browser.”

If you check Default, the embedded view acts in the same way it did inprevious releases, so that the line count value is controlled server-widefrom the NOTES.INI file.

Note that the line count property is ignored if you choose a view applet todisplay the embedded view.

In the Web server, you can determine the number of lines displayed bylooking (in order) at the following sources:

If the URL contains a “&Count” argument, use that number.

If there is no “&Count” argument, look at the number specified in theembedded view properties box.

If no number is specified in the embedded view properties box, use theserver-wide default for the number of lines.

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

Hiding a view from Notes usersDeselect “Show in View menu” on the Options tab of the ViewProperties box.

Omitting a view from the View menu applies only to Notes users, sinceWeb users don’t have access to Notes menus.

Open the design toolbox, click the view name in the right pane, andchoose Design - Design Properties. Select “Hide design element fromNotes R4.6 or later clients.”

Hiding a view from Notes clients is useful when you have a Web-onlyview or when you want to remove the view from both the View menuand the folders pane.

Give the view a name and surround it with parentheses — for example,(All).


Hiding a view from Web usersOpen the design toolbox, click the view name in the right pane, andchoose Design - Design Properties. Select “Hide design element fromWeb clients.”

Hiding a view from Web clients is useful when you have a Notes-onlyview, or when you want to remove the view from the folders pane andthe Open Database Views list.

Give the view a name and surround it with parentheses — for example,(All).

Showing a view only to users of older Notes releasesWhen you have a view tailored to users of older Notes releases, open theDesigner and click the view name. Choose Design - Design Properties. Clickthe Design tab and select “Do not show this design element in menus ofNotes R4 or later clients.” The view doesn’t appear to anyone using NotesRelease 4.0 or later.

Identifying unread documentsTo help users find new or modified documents, display the unread mark(an asterisk) next to unread documents in the view. A set of unread marksare maintained for each user, so even if one person has read a particulardocument, the asterisk still appears for other users who haven’t read it yet.

Choosing a style for unread marksThese options are set as a design property for a view. Open the Advancedtab of the View Properties box, and Select an “Unread marks” option.

You can display unread marks as:

“Standard (compute in hierarchy)”

Displays asterisks for unread main documents and response documentsand for any collapsed categories containing unread main or responsedocuments.

“Unread Documents Only”

Displays asterisks only for unread main or response documents.Unread marks do not appear next to collapsed categories. This choicedisplays the view faster than the Standard display and is a goodcompromise between showing unread marks at every level and notshowing them at all.


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

Choosing a color for unread marksTo change the color of unread documents in the view from the default colorred, click the Style tab of the View Properties box and select another colorfor “Unread rows.”

Disabling unread marks for modified documentsIf the unread status of modified documents is unimportant to users or if thedatabase resides on a server that users don’t access directly, turn off unreadtracking for all documents in a database to conserve disk processing time.Open the Design tab of the Database Properties box and select “Do notmark modified documents as unread.” This setting affects all views in thedatabase. Users see only new documents as unread; modified documentsdo not appear as unread.

Formatting date and time columnsTo format values that result in a time or date displaying in a column. selectthe Data and Time Format tab of the Column Properties box. You have thefollowing choices:

Option name Selections Description

Show Date and time

Date only

Time only

'Today’ and time

‘Today’ and time shows values resultingin the current date with the word“Today.” Values resulting in the previousday display “Yesterday.” All other valuesdisplay the date.

Date format month/day

month/year

month/day/year

If you have an international date formatset in your operating system, thesechoices change. For example, they maychange from month/day to day/month.

Time format hour:minute

hour:minute:second

If you have an international time formatset in your operating system, thesechoices change, for example, from 02:30 to14:30.

continued


Option name Selections Description

Time zone Adjust time to localzone

“Adjust time to local zone” displays thetime relative to the time zone of thereader. A document created at 3:00 P.M.in New York that is read by a user in LosAngeles adjusts to Pacific Standard Time;the creation time is displayed as “12:00P.M.”

Always show timezone

“Always show time zone” displays thetime zone where the document wascreated. With this option, the creator'stime zone is always shown. If a documentis created in New York at 3:00 P.M., auser in Los Angeles sees the creation timeas “3:00 PM EST.” A user in New Yorkalso sees the creation time as “3:00 PMEST.”

Show only if zone notlocal

“Show only if zone not local” displays thetime zone where the document wascreated only when the document is readby someone in a different time zone. Adocument created in New York at 3:00P.M. displays to all users in the U.S.Eastern standard time zone as “3:00 PM.”Users in all other time zones see thecreation date as “3:00 PM EST.”

Displaying numbers in columns

To format values that result in a number displaying in the column, select astyle in the Numbers tab of the Column Properties box.

General formatting displays numbers as they are entered; zeroes to the right of the decimal point are suppressed. For example, 6.00displays as 6.

Fixed formatting displays numbers with a fixed number of decimalplaces. For example, 6 displays as 6.00.

Scientific formatting displays numbers using exponential notation; forexample, 10,000 displays as 1.00E+04.

Currency formatting displays values with a currency symbol and twodigits after the decimal symbol; for example, $15.00. The currencysymbol and thousands separator displayed are based on settings inyour operating system.


Additional formatting optionsFor any formatting type other than General, select a number from 1 to 15from the “Decimal places” list.

Select “Percentage (value * 100)%” to display values as percentages; forexample, to display .10 as 10%.

Select “Parentheses on negative numbers” to display negative numbersenclosed in parentheses; for example, (5) instead of -5.

Select “Punctuated at thousands” to display large numbers with thethousands separator; for example, 1,000 in English, or 1.000 in French.

Refreshing view indexesA 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 viewindex must be refreshed to show them which documents are new orchanged. Refreshing a view index can occur manually when users press F9, as part of a condition built into the view design, or as part of the Updall(Update ALL) server process set up by the server administrator.

Refresh time optionsTo determine when to refresh an individual view, select a “Refresh index”option from the Advanced tab of the View Properties box.

Auto, after first use

Updates the view every time a user opens a view after the first time.

Automatic

Updates the view whether or not users ever open the database. Usingthis option, views open more quickly.

Manual

Relies on the user to refresh the view. This option is useful for largedatabases that don’t need to stay up-to-date. Using this option, viewsopen very quickly. Users just press F9 to refresh the view.

Auto, at most every n hours

Controls how frequently the view index updates. Choose this option forlarge databases that change fairly often. The view index updatesautomatically no more frequently than the specified interval. When auser opens a database in which changes have been made since the lastindexing, the refresh icon appears, and the user can press F9 to refreshthe view manually.


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

Refresh display optionsThe On Refresh options (on the Options tab of the View Properties box)determine how users see the changes in a view. Choices are:

Display indicator

Does not show view changes automatically. Instead, the refresh icon inthe left corner of the view displays to indicate that the view has changesand users must click the icon to see any changes.

Refresh display

Refreshes the display automatically before showing the view to users.

Refresh display from top row

Updates the view from the top down. This is useful in a reversechronological display where users are likely to look for changes at thetop of the view first.

Refresh display from bottom row

Updates the view from the bottom up. This is useful in a chronologicaldisplay where users are likely to look for changes at the bottom of theview first.

Discard index optionsTo delete indexes automatically for a particular view and save disk space,specify a “Discard index” option from the Advanced tab of the ViewProperties box. When users open a view whose index has been discarded,they may have to wait for Domino to recreate a view index. Thesesettingsoverride the NOTES.INI setting “Default_Index_Lifetime_Days,”which the server administrator sets and which, by default, deletes viewindexes after 45 days.

After each use

Deletes the view index as soon as the user closes the database. Thisoption saves the most disk space, but the index must be rebuilt the nexttime the view is opened. Choose this option for views that are usedinfrequently, but on a predictable basis — for example, a view that anagent opens only on Friday afternoons.

If inactive for n days

Deletes a view index if the view hasn’t been used in a specified numberof days. Domino rebuilds the view index the next time a user opens the


database. (This option doesn’t affect local databases.) Choose thisoption for databases that users infrequently or unpredictably need.

Never

Permanently preserves the view index and appends updates to theexisting index. Because this option takes up more disk space than theother options, use this only for views that users frequently need, so theydon’t have to wait for a new view index to be created when they openthe database.

When the view index is deletedThe Updall (Update All) server task, which runs by default on each serverat 2 AM, deletes the view index. Domino deletes the index the first timeUpdall runs after the index becomes eligible for deletion. For example, ifyou select “After each use” and the view is used at 10 AM Tuesday, theindex is not actually discarded until 2 AM Wednesday.

If you choose to delete the index after one day, Domino waits until theindex is at least one day (24 hours) old before deleting it. If the view is usedat 10 AM Tuesday, it is only 16 hours old at 2 AM Wednesday when Updallruns, so it is not deleted until the next time Updall runs at 2 AM Thursday.

For more information, see Administering the Domino System.

Designing foldersFolders are containers used to store related documents or groupings ofdocuments. Folders have the same design elements as views. You candesign folders in much the same way as views, using the Create - Design -Folder command. The difference between folders and views is that viewsalways have a document selection formula that collects and displaysdocuments automatically. A folder remains empty until users or programsadd documents to the folder.

Note that Web users cannot drag documents into folders.

For more information on folders, see Notes Help.


Designing a form as a view or navigator template

In Web applications, to create an association between a form and a view ornavigator, you can assign a reserved name to the form. Domino uses theform as a template when users open the view or navigator. This can be agood way to create a standard display for views and navigators in your site.

Use the following reserved form names to create an association between aform and a view or navigator.

Note that Domino requires an embedded view or the $$ViewBody field onthe form, but ignores the value.

Form name Design element required Comments

$$ViewTemplate forviewname

Embedded view or$$ViewBody field

Associates the form with aspecific view. The form nameincludes viewname, which is thealias for the view or when noalias exists, the name of the view.

$$NavigatorTemplatefor navigatorname

Embedded navigatoror $$NavigatorBodyfield

Associates the form with aspecific navigator. The formname includes navigatorname,which is the navigator name. Forexample, the form named“$$NavigatorTemplate for WorldMap” associates the form withthe World Map navigator.

Domino ignores create and readaccess lists on the form.

$$ViewTemplateDefault Embedded view or$$ViewBody field

Makes this form the template forall Web views that aren’tassociated with another form.

$$NavigatorTemplateDefault

Embedded navigatoror $$NavigatorBodyfield

Makes this form the template forall Web navigators that aren’tassociated with another form.


Chapter 9Designing Navigators

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

Navigators

Navigators are graphics that include programmed areas that direct uses tospecific parts of a database. They let users find documents or take actionswithout having to open views. If you are designing a navigator for the Web,consider either embedding a navigator or importing a navigator into aform, subform, page, or document.

Navigators usually include “hotspots”; that is, programmed areas that usersclick to execute an action. A hotspot can be text, graphics, or a combinationof both.

If you use navigators in an application, you usually want the navigator todisplay automatically when the application opens.

To use a navigator in a Web application, you must select “Web browsercompatible” as a navigator property. With this setting on, Domino convertsa navigator to an HTML imagemap. Navigators on the Web always displayas full-screen imagemaps. To control the size and display of a navigator onthe Web, you can embed a navigator in a form.

If your navigator inherits its design from a template, do not make anychanges to the design of your navigator, since any changes you make willbe over-written by the template.

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

229

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

Navigator actionsYou can add actions to all navigator objects except those pasted or importedas graphic backgrounds.

Designer provides the following simple actions that you can attach tonavigator objects:

Open another navigator.

Open a view or folder.

Serve as an alias for a folder.

Clicking the object displays the contents of the designated folder in theview pane.

Open a database, view, or document link.

Open a URL.

To create more complex flexible actions use @function formulas or aLotusScript program. LotusScript programs can perform tasks that aren’tpossible with @function formulas; for example, manipulating a database ACL.

For more information on writing formulas and scripts for buttons andhotspots, see the 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. Open a database in Designer.

2. Select Navigators in the Design pane.

3. Click the New Navigator button above the Work pane.

4. Choose Design - Navigator Properties.

5. Give the navigator a name that describes its use.

6. To use the navigator in a Web application, check “Web browsercompatible.”

7. (Optional) Choose an initial view or folder to open along with the navigator.


8. (Optional) Select “Auto adjust panes at runtime” so that users won’thave to manually resize a navigator that doesn’t fit a window.

9. Click the navigator window.

10. Use the Create menu or the SmartIcons® bar to draw objects or pasteobjects from the clipboard.

11. Click each object and choose Design - Object Properties to assign aname and style.

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

Select Simple action to choose a predefined automation, such asOpen a View.

Select Formula to define an action using the formula language.

Select Script to define an action using LotusScript.

13. Close and save the navigator.

Editing a navigatorTo edit an existing navigator, open the navigator in Designer. ChooseDesign - Navigator Properties and make changes as needed. To change anyobject, click on the object, select Design - Object Properties, and makechanges as needed.

Adding graphic objects to navigatorsYou can create graphic objects in another product, such as a drawing,charting, or mapping package, and import or paste the objects into anavigator as a graphic background for the whole navigator or as a buttonthat you automate with an action. A navigator can have only onebackground graphic, but it can have many buttons.

Designer includes a set of drawing tools, available on the SmartIcons bar oron the Create menu, that you can use to create or enhance graphiccomponents of a navigator. The drawing tools are displayed in theSmartIcons bar when the navigator is in Designer.

Note that you cannot click polylines on the Web, even though they displayon the Web.

Chapter 9: Designing Navigators 231

Adding and enhancing graphics in a navigatorThe following types of files can be pasted or imported into a navigator:

Bitmap (BMP)

GIF

JPEG

PCX

TIFF 5.0s

Note Graphic backgrounds cannot be moved; graphic buttons can bemoved.

To paste a graphic from another product1. Copy the graphic to the clipboard.

2. Open the database in Designer.

3. In the Design pane, click Navigators.

4. In the Work pane, double-click the name of the navigator you want toopen.

5. If you are pasting in a graphic button, move the cursor where you wantto place the graphic button.

6. Choose one of the following:

Create - Graphic Button to paste the graphic as a button on thenavigator.

Create - Graphic Background to paste the graphic as a backgroundfor the navigator.

To import a graphic1. Create a new navigator, or open an existing navigator in Designer.


3. Select the file to import and click OK.

4. Click Graphic Button to import the graphic as a button, or click GraphicBackground to import the graphic as a background for the navigator.

To edit a graphicDouble-click a drawn object to edit its properties. For example, you canchange colors or widths of lines on drawn objects.

Use drawing tools available from the Create menu or the SmartIcons bar toenhance existing objects.

To edit an object that is under another object, click the overlying object andchoose Design - Send to Back and then select the object you want to edit.Hotspots are always on top and cannot be sent to the back.


To delete a navigator objectTo delete a navigator object (such as a button or a rectangle), select theobject and choose Edit - Clear.

To remove a graphic, choose Design - Remove Graphic Background.

Tips for drawing new navigator objectsTo create several identical navigator objects quickly, hold the SHIFTkey down while choosing Create. Draw all the objects you need; chooseCreate - <shape name> to exit creation mode.

To draw a square or a circle, hold the SHIFT key down while draggingthe shape.

To move an object that isn’t locked into position, drag the object to anew location.

To resize an object, click the object, position the cursor on one of thesizing corners, and drag the object to the size you want.

To line up objects at a grid mark, choose Design - Navigator Properties,click the Grid tab, and select “Snap to grid.” Choose a grid size (1 pixelis the most precise).

To freeze an object at its current position and size, click the object,choose Design - Object Properties, and select “Lock size and position.”

Adding text to and highlighting a navigator objectYou can add text to most objects, including buttons, rectangles, polygons,and so on. You cannot add text to the following objects: polylines, hotspotrectangles, hotspot polygons, graphic buttons, and graphic backgrounds.You can also highlight an object. When an object is highlighted, itsappearance changes when the cursor is over it or when it is clicked.



3. Double-click the navigator name in the Work pane.

4. Click a navigator object.

5. Choose Design - Object Properties.

6. To add text to the object, enter text into the Caption box at the Info tab.

7. To define highlighting for an object, click the HiLite tab.

Select “Highlight when touched” to show the highlighted style whenthe user’s cursor passes over the object.

Select “Highlight when clicked” to show the highlighted style whenthe user clicks the object. The object remains highlighted until theuser clicks another.


8. (Optional) Change the highlight border width, highlight border color,and highlight background color.

9. (Optional) Click the Styles tab and do one of the following to define theunhighlighted style:

Select a border width, border color, and background color.

For a button, select a button face color, bevel width, and bordercolor.

Select “Make Default” to apply to all new objects of this type.


Tip Choose Design - Preview in Notes or Design - Preview in Webbrowser to enter testing mode and check the highlight settings.

Adding hotspots to navigatorsA hotspot is a programmed area that you click to execute an action.Hotspots are always topmost on a navigator — you cannot send them to theback. To automate a hotspot, attach an action to it. For example, if yournavigator is a map, you can create hotspots so that a user clicking on aregion in the map views information about that region.

To create a hotspot1. Open a navigator in Designer.

2. Select a hotspot tool from the SmartIcons palette.

3. Click on the navigator and drag to create the hotspot. The polygon toolallows you to create a line segment each time you click. Double-click tocomplete the drawing and close the polygon hotspot.

4. (Optional) Double-click the hotspot to edit its properties.

Automating navigatorsAfter you add objects to a navigator, you automate the objects by attachingactions to them. For example, to program a graphic button so that it opens aparticular view when a user clicks it, select Run: Simple Actions and thenchoose “Open a view or folder” in the Action field of the Programmer’spane. Then select a particular view in the Programmer’s pane.


Simple actions for navigators

Action: Open a view of folderWhen 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 folderWhen 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 theoriginal folder, use View - Go To.

Action: Open another navigatorWhen users click this object, the current navigator (if there is one) isreplaced by the new navigator. The replacement navigator must be from thesame database.

Action: Open a linkThe action prompts you to paste a link to a document, view, or database.When a user clicks this type of object, Designer presents the specifieddocument, view, or database.

Action: Open URLThe action prompts you to specify a URL to open. Clicking the navigatorobject opens the URL.

Custom actionsYou can use an @function formula or a LotusScript program to define acustom action. A navigator that runs an @function formula allows you tocreate specialized actions that aren’t related to switching to a view, a folder,a navigator, or a link.

To attach an action1. Open the database in Designer.


3. In the Work pane, double-click the name of the navigator you want to edit.

4. Select a navigator object.

5. In the Programmer’s pane, click “Run: Simple action(s).”

6. Select the simple action to run and supply any required information.



To attach a formula or script1. Open the navigator in Designer.

2. Select the navigator object.

3. To add a formula, select “Run: Formula” in the Programmer’s pane.

4. Type the formula and click the green check mark to confirm it.

5. To add a script, select “Run: LotusScript” in the Programmer’s pane.

6. Write the LotusScript program.


For more information on writing formulas and scripts for buttons andhotspots, see the Programming Guide.

Examples: Automating a navigatorOpening a viewA navigator that switches to another view gives users a graphical way tochoose a view so they don’t need to know the name of a view in the viewpane. The Main Navigator in the Discussion template uses objects to openthese views: All Documents, By Category, and By Author.

Creating a navigator object that opens a navigatorA 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 theinformation 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’ssales. Each bar in the first navigator is a hotspot rectangle that takes users tothe Weekly Details by Country navigator. When users reach the secondnavigator, they see another bar chart that displays weekly sales byindividual country. Clicking a bar in this chart opens the view for thecountry (for example, View by country\France). Each bar in the secondnavigator is a hotspot rectangle whose “Open a view or folder” actionspecifies the appropriate country view.

Creating a shortcut navigator with an @function formulaThis shortcut navigator allows users to click the icon instead of using theCreate 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 programWhen users double-click the navigator object (for example, a button), thisscript 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


Navigators, imagemaps, and outlines

Navigators are similar to imagemaps and outlines. Depending on the situation, you may want to use an imagemap or outline instead of a navigator.

A navigator is a graphical roadmap that directs users to specific parts of an application. A navigator — like a form, a page, or a view — is anindependent design element. It is a powerful tool for combining graphics,text, and action buttons. Navigators can also be embedded in a form or apage. Embedded navigators have the advantages of combining a navigatorwith other form or page elements and of letting you design a navigatortemplate to establish a uniform way of presenting navigators in anapplication. One disadvantage of navigators is that once you design anavigator, it is usually static and can be difficult to change.

An imagemap is a graphic you enhance with programmable hotspots.Unlike a navigator, an imagemap can reside only on a form or a page. You can easily combine an imagemap with text and other form or pageelements. You can also control the display of an imagemap using ahide-when or computed-for-display formula. For most situations, animagemap provides all the functionality you need to create a great-lookingnavigational structure for your application, but if you plan to combine a number of graphics and buttons, you might consider creating a navigator instead.

An outline lets you create an organizing structure for an application andgives you control over how elements display in a navigation pane. Anoutline also gives you the power to create a sophisticated site map thatcombines text, graphics, and automation, and lets you combine databaseelements with links to Web sites and to pages, documents, or views in otherdatabases. Because an outline is created from the contents of the database, it is easier to maintain than a navigator and is more flexible.


Displaying a navigator when users open a database

When users open a database, the navigator can display in the Navigatorpane or in a full-screen window. For example, the interface to an onlinehelp system might be a full-screen navigator. If you set up the database toopen a navigator, the initial view of that navigator overrides the defaultview or the current view for the database.

1. Select the database that contains the navigator you want to display andchoose File - Database - Properties.


To display the navigator in a navigation pane, select “On DatabaseOpen: Open designated Navigator”.

To display the navigator in a full-screen window, select “OnDatabase Open: Open designated Navigator in its own window”.

3. Select the navigator.

The “Open designated navigator in its own window” property causes thechosen navigator to display as a full screen. The regular navigation, view,and preview panes are not available from a full-screen navigator, but userscan choose View - <view name> to return to a specific view.

Hiding navigators

Designer includes several ways to hide a navigator from users. There maybe times when you want to present one navigator to Notes users andanother to Web browser users.

Hiding a navigator from Notes usersOpen a database in Designer and click Navigators in the Design pane.Highlight a navigator name in the Work pane and choose Design -Design Properties. Click the Design tab and select “Hide design elementfrom Notes R4.6 or later clients”.

Hiding a navigator from Web usersOpen a database in Designer and click Navigators in the Design pane.Highlight a navigator name in the Work pane and choose Design -Design Properties. Click the Design tab and select “Hide design elementfrom Web clients”.


Showing a view only to users of older Notes releasesWhen you have a navigator tailored to users of older Notes releases, openthe database in Designer, click Navigators in the Design pane, highlight anavigator name in the Work pane, and choose Design - Design Properties.Click the Design tab and select “Do not show this design element in menusof Notes R4 or later clients.” The navigator doesn’t appear to anyone usingNotes Release 4.0 or higher.

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

To embed a navigator in a form, subform, page, or document1. Open a form or page in Designer or open a document in Edit mode.

2. Place the cursor where you want the embedded element to display.

3. Choose Create - Embedded Element - Navigator. The Insert Navigatordialog box appears.

4. Select a navigator to embed.

5. (Optional) If you don’t want to display the same navigator in allcircumstances, click “Choose a Navigator based on a formula” in theInsert 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 boxappears. You can then change the alignment or style, or hide theelement under certain conditions.


To change the navigator, click the embedded navigator and choose anotherfrom the list in the Programmer’s pane.

You can embed multiple navigators anywhere on a form, subform, page, ordocument, including in tables, as part of collapsed sections, and as left-,right-, or center-aligned design elements. Avoid hiding embeddednavigators with the “Hide design element from Web browsers” option.Forms with hidden navigators won’t display on the Web.


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

$$ FieldsFor compatibility with previous releases, the reserved field$$NavigatorBody still works on forms. It duplicates functionality nowprovided by embedding.

Overriding an embedded navigator with a navigator templateA navigator template is a navigator that has the name $$NavigatorTemplatefor <navigator name>. In a Web application, when you embed multiplenavigators on a form or page, Domino displays the navigator that wasnamed in the form or page name in every embedded navigator. To overridethis behavior, designate only one embedded navigator as the one toreference the form name navigator or page name navigator and ignore itsoriginal value.

There is no equivalent procedure for $$NavigatorBody fields.

1. Select the embedded navigator and choose Element - NavigatorProperties. The Embedded Navigator Properties box appears.

2. Click the Info tab and select “Display navigator specified in form namewhen this form is used as a Navigator Template”.

Importing a navigator into a form, subform, page, or documentWhen you import a navigator into a form, subform, page, or document, acomposite image of the navigator is pasted in. The imported navigatoractually becomes a picture object so that you make all future changes to thepicture object. The navigator text boxes, graphic buttons, polygons, andother navigator objects are converted to imagemap hotspots on the newlycreated picture object.

An advantage of importing a navigator is that formulas and LotusScriptthat were originally attached to navigator objects become attached to theimagemap hotspots. Imported navigators, unlike navigators and embeddednavigators, allow you to make changes to the formulas and the LotusScript.An imported navigator, unlike an embedded navigator, has no links to theoriginal navigator.

Note that you can import only navigators that are Web-browser compatible.Check the “Web browser compatible” box at the Info tab of the NavigatorProperties box for the navigator you want to import.


When you import a navigator, navigator simple actions are converted toequivalent 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 document1. 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 ImportNavigator dialog box appears.

4. Select the navigator to import.

Note that the navigator you select must already be saved as “Webbrowser compatible”.


Testing navigatorsTo test a navigator while you design it, switch to testing mode to see a message describing what happens if the simple action, formula, or script runs.

For navigators that perform multiple steps or complex tasks, split theprocess into several small tasks and create an action for each. Test and fixeach small task first. When everything is working correctly, combine theformulas into one, and then test the automation again by creating a samplecopy of the database and testing all navigator behavior.

To test a navigator, follow these steps:



3. In the Work pane, double-click the navigator you want to open.

4. Choose Design - Preview in Notes or Design - Preview in Web Browser<Web browser>.


5. Highlight and click each object to see if the highlighting and actions areas you expected. You can preview in either Notes or a Browser to seehow the action actually performs.

6. If the test produces unexpected results, close the previewed item anduse the Windows taskbar to return to Designer.

7. Correct the problems and run the test again.

8. When the test shows no problems, close and save the navigator.


Chapter 10 Automation in Applications

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

Automation

Automation in an application speeds up repetitive tasks, handles workflow,updates information, performs calculations, runs programs, and checks for errors.

You can add automated components to most design elements in a Dominoapplication: a database, a page, a frameset, a view, a form, or a document.The automated components include:

Actions

Use an action with a form or view to set up a user-activated task. Youcan make the action available in the Actions menu or as a button in theaction bar. In particular, use actions to simulate Notes menu items forWeb browser users. Then, those users can complete Notes tasks whenaccessing Domino databases.

Hotspots

Use a hotspot in a form or document to set up a user-activated task. Thehotspot can be a link to another Web site, database, or element in adatabase; a button; a pop-up; or an action.

Agents

Use agents to set up user-activated tasks, or background tasks, in anypart of a Domino application. Agents can be simple, such as movingdocuments to a folder, or complex, using Java programs to run multipleautomated tasks at scheduled times. Agents are stored with databases,but you can use them to run automated tasks for views, documents,fields, and databases.

Programs that are activated by an event

Associate an automated task with an event that occurs when a designelement is used. For example, set up an error-checking automated taskto verify user input after a user has saved a document.

245

To set up the tasks associated with these automated components, use the following:

Simple actions

You can add automation to design elements without knowing aprogramming language. You can select one or more simple actions from a list. Simple actions can’t be customized and are not supported inWeb applications.

Formulas

You can write an @function formula that runs by itself or with a simpleaction. You cannot combine an @function formula with a LotusScriptprogram.

LotusScript

LotusScript is a complete scripting language that can support mostapplication-wide tasks.

JavaScript

Use JavaScript with agents and events to efficiently interact with the user for tasks such as form and field validation and simulatingdialog boxes.

Java

You can write Java programs or import Java files into agents.

Actions

Create an unshared action in a view or form to provide one-click shortcutsfor routine tasks in a view or in a document created with the form. Actionsare part of a view or form’s design and are not stored with individualdocuments.

You can also create a shared action in a database that can be used in severalforms and views. A shared action is stored as a resource with the database.

To build an action, you can use any of the following:

Simple actions that you select from a list

Formulas

LotusScript

JavaScript


When to use actionsBecause actions are available in a view or document, use them for anygeneral-purpose task related to a group of documents. For example, useactions:

When Web browsers accessing the database need substitutes for Notesmenu choices.

To present a shortcut as a clickable button.

When the automated task is relevant only to a subset of documents.

When users need to see all the available choices in a row at the top of adocument.

When the automated task isn’t limited to a particular section of a form.

If formulas are complex and you don’t want to save the formula witheach document.

Examples of actionsView actions — Let users create, print, delete, or categorize documents.

Form actions — Process an approval; mail a document; or give Webusers, who don’t have access to Notes menus, a way to click to edit,save, or close documents.

Simulate Notes menus for Web users.

Automatically send documents to reviewers.

Automatically process employee requests.

Notes on actionsSome views and forms in databases contain built-in actions, available eitherin the Actions menu, as buttons, or both. You can’t change the built-inactions or properties, but you can customize their appearance. LaunchDesigner and open the view or form. Click Objects and the built-in actionsare displayed in the list.

HotspotsHotspots are associated with text or an image in the body of a documentand can complete any of these types of automated tasks:

Link

Open a Web site, a database, or an element in a database (a page, view,frameset, form, document, folder, or navigator).

Text pop-up

Display information in a pop-up.

Chapter 10: Automation in Applications 247

Button

Complete a programmed task, using simple actions you select from alist, formulas, LotusScript or JavaScript.

Formula pop-up

Complete a programmed task using only formulas, with the resultsdisplayed in the pop-up.

Action hotspot

Complete a programmed task, using simple actions you select from alist, formulas, LotusScript, or JavaScript.

When to use hotspotsCreate a hotspot in a document when the hotspot is specific to thedocument. Create a hotspot in the a form when every document using thatform needs the hotspot.

Examples of hotspotsUse a document or database link to provide a cross-reference for moreinformation that is stored in a document in other database.

Use a URL link to cross-reference a Web site for downloading software.

Use a text pop-up to provide help information about what values tospecify in a field.

Use a button to submit a completed document for processing or add adatabase to a user’s workspace

AgentsAgents are stand-alone programs that perform a specific task in one ormore databases. Agents are the most flexible type of automation because:

They can be run by users in the foreground or run automatically in thebackground as scheduled agents.

They aren’t associated with a specific design element.

They can be run on a specific server, on several servers, onworkstations, or the Web.

They can call other agents.

They can consist of simple actions, formulas, LotusScript, or Javaprograms.


They can be distributed easily because they can be replicated.

They can be personal or shared.

A personal agent is created and run by the same user. No one elsecan run a personal agent.

A shared agent is created by one user and can be run by other users.

Because agents are so flexible and powerful, you might consider theircharacteristics first to decide the type of agent you want to build, and thenbuild it.

The Agent Manager supports all aspects of building, running, andtroubleshooting agents. The Agent Manager checks security, manages agentscheduling, monitors events and starts the appropriate agents when theirassociated events occur, records information in a log (the Agent Log), andperforms database operations to run the automated tasks associated withthe agent. Although you don’t work directly with the Agent Manager, youuse its components for building and troubleshooting an agent.

When to use agentsUse agents for database-wide and domain-wide automated tasks and forcomplicated automated tasks. You can use them to easily access, process,and manage data on other servers or in other databases.

See “Agents to run before Web users access Domino” for an example.

Notes on agentsSome databases and templates have built-in agents. For example, the mailtemplate has several built-in agents that let users manage their messagesand customize their mail databases.

To see the agents in a database, select the database and choose View -Agents.

EventsWhen users work in Domino design elements, Domino tracks theiroperations as events (for example, opening a database, opening a view,opening a document). You can attach programming tasks to these events.

To build a program for an event, you can use:

Formulas

LotusScript

JavaScript


When to use event programmingUse event programming to run tasks that users shouldn’t have to activatethemselves and that are very specific. Event programming is particularlyuseful when the timing of the program must be precise or the tasks areassociated with a particular design element.

For a table of events that can be automated, see “Event Descriptions” inVolume 1 of the Programming Guide.

Examples of event programmingError checking when a user completes a field or closes a document

Recalculating fields when a user saves a document

Prohibiting certain actions in a document

Prompting for user input

Displaying information when a user clicks a button

Types of eventsEvery design element has events that you can program, but they varyaccording to the design element. In the Programmer’s pane, click theObjects tab to review the events you can program.

Database eventsDatabase events pinpoint database-wide activities such as opening andclosing a database and deleting and undeleting documents.

ExamplesPostOpen — open a specific view to direct users to action items

QueryDocumentDelete — prevent users from deleting a particulardocument when the value of a status field on an action item is “Open”

PostDocumentDelete — archive a deleted document

QueryClose — prevent users from closing a database when there arestill action items in the action item view assigned to them

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

ExamplesQueryOpen — prevent users from opening a view in certaincircumstances such as from opening a “month end” view before thetwentieth day of the month


PostOpen — create a new document or open an existing one

QueryRecalc — inform users before a large view refreshes that it couldtake a while and ask them if they really want to proceed

QueryPaste — prevent users from pasting documents into the database

PostPaste — change the value of StartDateTime and EndDateTime inthe document when you paste an appointment on a particular day andtime slot.

QueryClose — prevent users from closing a view such as when thereare still action items in the action item view assigned to them

In addition to the events available for all views, calendar views havespecific events.

ExamplesRegionDoubleClick — create a new document when users click an areain a calendar view

QueryDragDrop — prevent someone from dropping an appointmenton an inappropriate day or time, such as a weekend day or a time thatis after 5 PM

PostDragDrop — change the value of StartDateTime and EndDateTimein the document after you drop an appointment on a particular day andtime slot

Folder eventsIn addition to the events available for all views, folders also haveQueryAddToFolder.

You could program the QueryAddToFolder event to prevent someone from dragging a document from one folder to another. For example, youcan prevent documents from moving to the Done folder if their status is still Open.

Form eventsForm events occur at the document level when users open or close adocument. They are useful for speeding up document display timesbecause they execute only when a specific form event occurs, unlike field recalculations that occur each time a document is saved, opened, or refreshed.

ExamplesInitialize — load an additional program before a document displays.

QueryClose — check for errors and validate fields before closing adocument.


QuerySave — reset a field value when users save documents ratherthan using conditional formulas in the field itself. For example, to resetthe status field if the document is being saved, create a script for aQuerySave event rather than include a formula that uses@If(@IsDocBeingSaved;“x”;“y”).

With QuerySave, you can also execute processing logic and avoid theunnecessary recalculations inherent in computed fields. For example,you have a form with a hidden computed field called State thatdetermines where documents are in the workflow and where they needto be sent. By replacing the field formula with a LotusScript programthat sets a field value during the QuerySave form event, set the fieldvalue in the document only when it is saved, not when it is opened orrefreshed.

Field eventsField events capture users’ movements into or away from a field.

ExamplesEntering — refresh hide-when formulas

Exiting — guide users to a certain field

Exiting — verify that users supplied valid information

Click eventsThe Click event occurs when users click actions or hotspots, or choose tasksfrom the Actions menu. Other events for actions, buttons, and hotspotsallow you to add programming to other events. After the object is loaded,the “initialize” event is triggered and then the click event is triggered.

ExamplesCompose a new document

Save a form

Make a calculation

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


Creating an unshared form action or view action

1. Launch Designer and open the form or view.

2. Choose Create - Action. The Actions Properties box appears.

3. At the Action Info tab:

Enter a name.

Select whether to make the action available as a menu item in theActions menu or as a button in the action bar, or both.

Select a target.

If the action is a button, select the graphic for the button. Click Notesgraphic to select a button design from a set available in Notes, orclick Custom. When you click Custom, you can:

In the Image field, specify the path name of a graphic you havecreated and stored in the file system.

Click the folder icon and select the name of a shared image resourcethat you have created and stored in the database as a Resource.

Click @ and specify a formula (or set of formulas).

Select the location and position for the action.

4. (Optional) At the Action Hide When tab, specify when to hide theaction.

5. (Optional) At the Advanced tab, specify how Notes workflow proceedsafter the user activates the action.

6. In the Info List of the Programmer’s pane, click Objects and select theaction you just created.

7. Choose one of the following from the Run pull-down list and add theautomated tasks:

Simple actions

Formula

LotusScript

JavaScript

8. Save the form or view.


Other action proceduresTo copy: select the action in the Action pane and choose Edit - Copy andEdit - Paste.

To delete: select the action in the Action pane and choose Edit - Clear.

To change properties: select the action in the Objects list and choose Design - Action Properties.

To change automation: select the action in the Objects list and edit theprogramming tasks in the right pane.

Actions menuThe Actions menu is a context-sensitive list of any actions and agentsavailable for a particular part of an application, as well as some menucommands included with the Notes software. From an open view, Notesusers see only those actions associated with the view, plus any manuallyrun agents. From an open document, Notes users see the actions associatedwith the form used to create the document, plus any manually run agents.Web users don’t see the Actions menu.

Calling an agentYou can use a form or view action to run an agent. Use the@Command([ToolsRunMacro]) or the OpenAgent URL command to call an agent.

Examples: actions

Simulate Notes menus for Web usersWeb users don’t have access to Notes menu choices when they work inDomino databases. Therefore, you should create menu equivalents for them.

Create actions with @command formulas and make them available asbuttons in the action bar. Keep in mind that Domino cannot translatecommands based on a selected document in a view because there is nonotion of a “selected” document on the Web. For actions such as “CreateResponse Document,” you must add a form action to the Main Topic formfor opening a Response document.

To Web-enable all buttons in a database as well as certain @commands,select the database property “Web access: Use JavaScript when generatingpages.” Without this property set, Domino recognizes only the first buttonin a document and treats it by default as a Submit button that closes andsaves the document.


Be aware that Domino displays all buttons, actions, and hotspots — eventhose that contain @commands and @functions that aren’t supported forWeb applications.

Complete these steps to create a button to open a new Main Topic in thecurrent database:

1. Launch Designer and open the view where you want to add the buttonfor Web users.

2. Choose Create - Action.

3. Complete the Action Properties box. At the Action Info tab:

Enter the name “Create Main Topic”.

Select “Include action in button bar.”

Select “Notes graphic” and select a graphic for the button.

4. In the Info List, click Objects and click Create Main Topic.

5. In the Run pull-down list, select Formula.

6. Enter this formula:@Command([Compose];"Main Topic")

7. Save the view.

Examples of other commonly used menu items:

Create a document@Command([Compose]; "formname")

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

Open a view@Command([OpenView]; "viewname")

@Command([OpenView];"":"database"; "viewname")

@Command([OpenView];"By Date")

Delete an open document@Command([EditClear])

Close an open document or view@Command([FileCloseWindow])


Sending a document to reviewersYou want to simplify the process of distributing proposed concert schedulesto a review board.

1. In the Concert Schedule form, create a field of type Names that willspecify all the reviewers.

2. In the Concert Schedule form, choose Create - Action and specify thefollowing in the properties box:

Name — Enter “Distribute for Review.”

Display — Select “Include action in button bar”; deselect “Includeaction in Action menu.”

Button Graphic — Select Notes graphic and pick a graphic from thepull-down list.

3. In the Info List, click Objects and select “Distribute for Review(Action).”

4. In the Run pull-down list, select “Simple action(s).”

5. Select the Add Action and Send Document actions

6. Save the form.

Approving and denying requestsYou want to improve a Requisition form to make it easy for managers toapprove or deny requests that are mailed to them. You create two formactions: “Approve Request” and “Deny Request.”

The “Approve Request” action uses this formula to change the document’sstatus to Approved and routes the document to the next approver:

FIELD Status:="Approved";@MailSend(NextApprover;"";"";"For your review";"Click ApproveRequest to approve this requisition or click Deny Request toreturn the request to " +Initiator;"Initiator":"Body";[sign]);

The “Deny Request” action changes the document’s status to Denied androutes a notification to the initiator.

FIELD Status:="Denied";@MailSend(Initiator;"";"";"Re: Your request";"Your request wasunable to be approved. Contact " + PreviousApprover + "formore information.");


Action bar

The action bar is a horizontal button bar that lies below the SmartIcons bar.If there are built-in actions or you created actions to be displayed asbuttons, users see the buttons when they open the view or create adocument using the form.

You can change the color and style of the action bar, and enable the Dominoaction bar applet for Web users.

1. Launch Designer and choose Design - Action Bar. The Action BarProperties box opens.

2. At the Action Bar Info tab:

Alignment - lets you choose whether to have the action bar align to theleft or right.

Background - lets you set the background color for all buttons on theaction bar.

Bottom Border - in the Width field, you can choose:

“None” does not place a divider line under the action bar.

“Fit to window” places a divider line under the whole action bar.

“Under buttons only” displays a divider line that is only as long asthe icon display.

“Set length” displays a divider line that is a specific number ofinches.

You can also set the Color of the border and choose the Style of theborder line.

Web Access - select whether to use the Domino applet to provide abetter action bar to display to Web users.

Select “Using Java Applet” to enable the applet. With the applet, Webusers can:

Scroll across the action bar, when needed.

For actions that have pull-down list selections for Notes client users,the action selections are displayed as a second row of buttons whenthe user clicks the main action. The second row of buttons aredisplayed at 75% the size of the main action buttons. Web users canview all the selections and click one to select it.

Select “Using HTML” to disable the applet.


3. At the Button Background tab, you can customize the followingproperties for all buttons on the action bar:

Button Size - sets the height and width in pixels of all the buttons onthe action bar and sets the margin size.

Button Border - lets you control when the button border displays.You can choose to display the button border On Mouse Over,Always, or Never.

Button Background - lets you either select a color for the buttonbackground or use an image for the background. To use an image,click the folder icon and select the name of a shared image resourcethat you have created and stored in the database as a Resource, orclick @ and specify a formula (or set of formulas). Note that using animage is not supported on the Web.

4. At the Button Font tab, you can change the font, size, color, and style ofthe text in the buttons.

Creating and inserting shared actions

Shared actions are stored in databases as Resources. Once you create ashared action, any other view or form in the database can access it.

Create a shared action1. Open the database where you want to store the shared action.

2. Click Resources; then click Other.

3. From the list of other resources, select Actions.

4. For the first shared action, the Actions properties box appears.

For subsequent shared actions, choose Create - Shared Action and theActions properties box appears.

5. At the Action Info tab:

Enter a name.

Select whether to make the action available as a menu item in theActions menu or as a button in the action bar, or both.

Specify a target.

If the action is a button, select the graphic for the button. Click Notesgraphic to select a button design from a set available in Notes, orclick Custom. When you click Custom, you can:

In the Image field, specify the path name of a graphic you havecreated and stored in the file system.


Click the folder icon and select the name of a shared image resourcethat you have created and stored in the database as a Resource.

Click @ and specify a formula (or set of formulas).

Select the location and position for the action.

(Optional) Click the Action Hide When tab to specify when to hide the action.

Click the Advanced tab and specify how Notes workflow proceedsafter the user activates the action.

6. In the Info List of the Programmer’s pane, click Objects and select theshared action you just created.

7. Choose one of the following from the Run pull-down list and add theautomated tasks:

Simple actions

Formula

LotusScript

JavaScript

8. Save the shared action.

Insert a shared action1. Open the form or view where you want to use the shared action.

2. In the Info List, click Objects and select an action, or select an action inthe Action pane.

3. Choose Create - Insert Shared Action.

4. In the Insert Shared Action dialog box, select the shared action and clickInsert. The shared action is added to the view or form Objects list.

The next time you use the form or view, the shared action is available.

Editing shared actions To edit a shared action, launch Designer and open the database with theshared action. Click Resources, click Other, and select Actions.

To change its properties, double-click the action in the list and theAction property box appears.

To change its automated components, click Objects and select it fromthe list.


Creating a link

1. Launch Designer and open the design element you want to add the linkto (a page, view, frameset, form, folder, or navigator) or edit adocument.

2. Select text or an image for the link.

3. Choose Create - Hotspot - Link Hotspot.

4. At the Hotspot Info tab of the HotSpot Resources Link Properties box:

At the Type field, choose one of the following:

Link

Link requires that you paste in a link that you’ve already copied tothe Clipboard. Click the Paste icon to paste in the link. The links youcan paste in from the Clipboard include: View, Document, Database,or Anchor.

Named Element

A named element is a design element that you have already createdand 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 namedPAGE1, enter it into the Value field). Alternately, you can click oneof the following icons:

Formula (@) icon to use a formula that evaluates to a name.

Paste icon to paste in a name which you previously copied to theClipboard.

Folder icon to open the Locate Object dialog box and select a designelement from a list of elements.

URL

Enter the full URL specification (for example,http://www.lotus.com). You can also paste in a URL or use aformula that evaluates to a URL.

Frame: Specify the frame in which you want the data to displaywhen the user clicks the link hotspot.

Select whether to show a border around the hotspot.

(Optional) Click the Paragraph Hide When tab to specify when tohide the link.

5. Save the design element or document.


Other link proceduresTo change properties: click the link and choose Hotspot - HotspotProperties.

To delete, but keep the associated text: click the link and choose Hotspot -Remove Hotspot.

Example: linksFor each concert schedule you send out, you want to provide across-reference for more information about the performer. Create a link inthe document you create for a specific concert and specify a URL withdetailed information about the performer.

1. Edit the document announcing the concert.

2. Select text for the link hotspot.

3. Choose Create - Hotspot - Link Hotspot.

4. At the Hotspot Info tab of the Hotspot Resources Link Properties box:

Type: Select URL.

Value: Specify the Web address; for example, specifyhttp://www.concertseries.org/performers/luke.html

5. Save the document.

Creating a button1. Open the design element you want to add the button to (a page, view,

frameset, form, folder, or navigator) or edit a document.

2. Click where you want to add the button and choose Create - Hotspot -Button.

3. At the Button Info tab of the Button properties box:

Button Label: Enter a name for the button.

Button Width: Specify a value, in inches, for the width.

4. (Optional) At the Paragraph Hide When tab, specify when to hide thebutton.

5. In the Info List, click Objects and select the button you just created.

6. Choose one of the following from the Run pull-down list to add theautomated tasks:

Simple actions

Formula


LotusScript

JavaScript

7. Save the design element or document.

Other button proceduresTo change properties: click the button and choose Button - ButtonProperties.

To change automation: in the Info List, click Objects, select the button in theObjects list and edit the programming tasks in the script area.

To delete: click the button and choose Edit - Clear.

Call an agent: use the @Command([ToolsRunMacro]) or the OpenAgent URL.

Example: buttons

Using a button to add a database to a user’s workspaceThe Human Resources department sends new employees a mail messagethat welcomes them to the company and gives them orientationinformation. You decide to add a button to the Welcome form to make iteasy for new users to find Benefits information. New employees see thebutton when they read their Welcome message. Double-clicking the buttonadds Server1’s Benefits Information database to the user’s workspace (if itisn’t already there) and opens it to the View by Category view. The buttonuses this formula:

@Command([FileOpenDatabase];"Server1":"BENEFITS.NSF";"View byCategory")

Creating a text pop-up1. Open the form you want to add the pop-up to or edit a document.

2. Select text or an image to associate with the text pop-up.

3. Choose Create - Hotspot - Text Pop-up.

4. At the Hotspot Pop-up Info tab of the HotSpot Pop-up Properties box:

Enter the text for the pop-up.

Select whether to pop up the text when the user mouses over orclicks the hot spot.

Select whether to identify the hotspot with a border and whether touse the highlight color or a default green.


5. (Optional) At the Paragraph Hide When tab to specify when to hide thepop-up.

6. Save the form or document.

Other text pop-up proceduresTo change properties: click the pop-up and choose Hotspot - HotspotProperties.

To delete, but keep the associated text: click the pop-up and choose Hotspot - Remove Hotspot.

Example: text pop-upsUsers register for conferences using a form you designed, but theyfrequently specify their incorrect email address. You want to give usersmore information about what you need in the field. Create a text pop-up todisplay the information when they mouse over the field label.

1. Open the form.

2. Select the field label.


4. At the Hotspot Pop-up Info tab of the HotSpot Pop-up Properties box:

Enter the following text:Specify your Notes mail address, not your internet mail address. For example, specify "Ken Jones@ABC" not "[email protected]".

Select “Pop-up on mouse over.”

Select “Show border around hotspot” and “Use highlight color.”

5. Save the form.

Creating a formula pop-up1. Open the form you want to add the pop-up to or edit a document.

2. Select text or an image to associate with the formula pop-up.

3. Choose Create - Hotspot - Formula Pop-up.

4. At the Info tab of the Hotspot Pop-up Properties box:

Select whether to pop up the formula when the user mouses over orclicks the hotspot.

Select whether to identify the hotspot with a border and whether tohighlight the text.


5. (Optional) At the Paragraph Hide When tab, specify when to hide thepop-up.

6. In the Info List, click Objects and select the hotspot you just created.

7. Enter its formula


Other formula pop-up proceduresTo change properties: click the hotspot and choose Hotspot - HotspotProperties.

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 editthe formula in the script area.

Other considerations:

Use formulas that display information, such as @Time.

Do not use formulas that take action, such as @OpenView.

Example: formula pop-ups1. Open the form you want to add the pop-up to.

2. Select text.

3. Choose Create - Hotspot - Formula Pop-up.

4. At the Info tab of the Hotspot Pop-up Properties box:

Specify the frame in which you want the data to display when theuser clicks the link hotspot.

Select “Show border around hotspot.”

5. In the Objects list, click the hotspot and enter the following formula:@Time(@Now)

6. Save the form.


Creating an action hotspot

1. Open the form you want to add the action hotspot to or edit adocument.

2. Select text or an image to associate with the action hotspot.

3. Choose Create - Hotspot - Action Hotspot.

4. At the Hotspot Info tab of the Action HotSpot Properties box: Specifythe frame in which you want the data to display when the user clicksthe link hotspot.

5. (Optional) At the Hide When tab, specify when to hide the hotspot.

6. In the Info List, click Objects and select the action you just created.

7. Choose one of the following from the Run pull-down list to add theautomated tasks:

Simple actions

Formula

LotusScript

JavaScript


Other action hot-spot proceduresTo change properties: click the hotspot and choose Hotspot - HotspotProperties.

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 editthe programming in the Script area.

To call an agent: use the @Command([ToolsRunMacro]) or the OpenAgentURL command.


Creating a program for an event

1. Open the design element to which you want to add automation.

2. In the Info List, click Objects and select the event.

3. In the Run pull-down list, the programming you can use for automatingthe event depends on the event. Choose one of the following:

Simple actions

Formula

LotusScript

JavaScript

4. Save the event.

Examples: Creating an event script or formula

Displaying a message when users close a documentThe following QueryClose event script for a form displays a message whenusers close a document they’ve edited:

Sub QueryClose(Source As Notesuidocument,ContinueAsVariant Dim workspace As New NotesUIWorkspace Dim doc as NotesUIDocument Set doc = workspace.CurrentDocument If doc.EditMode Then Messagebox("Call Pat at x-314 if you have anyquestions.") End IfEnd Sub

Filling in fields automaticallyThe following script for a field Entering event fills in the FullName field byconcatenating the FirstName field, a space, and the LastName field:

Sub Entering(Source As Field) Dim workspace As New NotesUIWorkspace Set doc = workspace.CurrentDocument firstName = doc.FieldGetText("FirstName") lastName = doc.FieldGetText("LastName") fullName = firstName & " " & lastName Call doc.FieldSetText("FullName", fullName)End Sub


Requiring a field to be filled inThe following script for a field Exiting event requires users to fill in aLastName field after they fill in the FirstName field:

Sub Exiting Dim W As New NotesUIWorkspace Dim UIDoc As NotesUIDocument Set UIDoc = W.CurrentDocument If (UIDoc.FieldGetText ("LastName") <> "") Then UIDoc.GotoField "FirstName" Else UIDoc.GotoField "LastName" Messagebox "You must enter the person's last name.", 0,"ERROR" End IfEnd Sub

Building an agent1. Select the database where you want to create the agent.

2. Choose Create - Agent.

3. In the Name field, enter a name for the agent.

4. (Optional) If the agent searches for text in documents, click Options and specify what to search for.

5. Select Shared Agent if this agent will be used by other users. Once you save the agent, you cannot change this setting. If you don’t select“Shared Agent”, the agent will be a personal agent that only you can run.

6. Select how, when, and where to run the agent:

Select how to run the agent from the “When should this agent run?” list.

For the On Schedule More Than Once a Day, On Schedule Hourly,On Schedule Daily, On Schedule Weekly, On Schedule Monthly, andIf Documents Have Been Created or Modified options, click Scheduleto set up when to run the agent. These options are not supported onthe Web.

For any scheduled agent, select where to run the agent from the“Run on” pull-down list. Specifying servers is particularly importantwhen agents run on multiple servers and they are changingdocuments in databases that are replicated.


7. Select the documents in the database the agent will process from the“Which document(s) should it act on?” list. These options are notsupported on the Web:

All unread documents in view

All documents in view

Selected documents

Pasted documents

8. (Optional) To further specify the choice of documents, click Add Search.

9. From the Run pull-down list, choose one of the following to define theagent’s automated components:

Simple actions

Formula

LotusScript

Java

Imported Java

10. Press ESC to save the agent.

Other agent proceduresCopy: choose View - Agents, select the agent and choose Edit - Copy.

Delete: choose View - Agents, select the agent, and choose Edit - Clear.

Select multiple agents: choose View - Agents, click the first agent,CTRL+click the next agent, and so on.

Enable/Disable:

If you have Designer access or above, you can disable scheduled agents toprevent servers from running them. This is useful for debugging a problemwith an agent. Designers can still run disabled agents by choosing View -Agents, selecting an agent, and choosing Actions - Run. After you re-enablethem, scheduled agents resume their schedule.

To disable individual agents:

1. Select the database and choose View - Agents.

2. Select the enabled agent and choose Actions - Disable.

The checkmark disappears next to the agent name.


To disable all automated agents in a database:

3. Select the database and choose File - Database - Properties.

4. Click “Disable background agents for this database.”

To enable a disabled agent, click the agent and choose Actions - Enable.

Options for running agentsYou can set up an agent to run manually, based on a database activity, or ona schedule.

When you schedule an agent for more than once a day, hourly, daily,weekly, or monthly, keep these points in mind:

You can also specify which servers the agents run on.

When agents run on multiple servers and they are changing documentsin databases that are replicated, you should specify the servers they run on to prevent replication conflicts. Then, set up the databasesreplication schedules so they don’t interfere with the agents’ scheduled runs.

Agents are scheduled according to the interval you set up, not the exacttime of day. For example, if you schedule an agent to run hourly, it runsabout one hour after the last time it ran.

Run option When to use

Manually from ActionsMenu

For user-activated agents or for WebQuerySave orWebQueryOpen agents.

Not supported on the Web.

Manually from Agent List For agents that are called by other agents and foragents that are still being developed.


Before New Mail Arrives For processing mail before it is listed in the maildatabases; for example, to move incoming mail to a folder.

With this option, the agent runs before the message islisted in the database. Therefore, do not use the“Mark Documents Read” simple action becausedocuments will always be marked unread when theyare listed in the database.

continued



After New Mail Arrives For processing incoming mail: to respond to it,forward it, or file it.

Interactive functions and functions that impede theprogress of the mail router are ignored whendocuments are mailed into the database. For example:

@DbColumn

@DbCommand

@DbLookup

@MailSend

@Prompt

@Command

@PostedCommand

If Documents Have BeenCreated or Modified

For workflow tasks where a task is performed basedon new or changed documents.

If Documents Have BeenPasted

For documents that are pasted into the databaseroutinely and they need to be modified as they arebeing pasted.

Paste-activated agents cannot use @Command or@PostedCommand.

On Schedule More ThanOnce a Day

Optionally, set up whichserver to run on.

For high-priority databases, such as those critical to abusiness process and for databases that replicateseveral times a day, such as workflow applicationsthat route documents for approval.

Be aware that if you schedule very frequent runs (forexample, every 5 minutes), the server’s performancecould be affected.

A scheduled agent that uses @DbColumn or@DbLookup formulas can only access a databasestored on the same workstation or server.


On Schedule Hourly


For high-priority databases as described for “OnSchedule More Than Once a Day.”



continued



On Schedule Daily


For activities that are important but that will notcause a delay if they are only generated once a day.Examples include mailing newswire articles orgenerating low-priority assignments.



On Schedule Weekly


For routine tasks. Examples include generatingsummary reports and sending reminders.



On Schedule Monthly


For low-priority maintenance tasks. Examples includearchiving documents and distributing companynewsletters.



On Schedule Never For agents that you do not want to run in particularcircumstances. For example, use this run option foragents that do not run on the Web or for agents thatare called by other agents.

Selecting where to run a scheduled agent When you click Schedule to schedule an agent, you can also select one ofthe following options for where to run it:

Local in “Run on” list — Run only on your workstation.

Note When you select Local, Notes does not check security restrictionswhen the agent is run.

Any Server in “Run on” list — Run on any server that the agent isavailable on.

When agents run on multiple servers and they are changing documentsin databases that are replicated, the agents could cause replicationconflicts. Therefore, be careful about using this setting in thiscircumstance. Alternatively, you can specify the servers to run on toprevent replication conflicts. Then, set up the databases’ replicationschedules so they don’t interfere with the agents’ scheduled runs.


Specific server name in “Run on” list — Run only on the single serveryou select from the list of available servers.

Choose when agent is enabled — Prompt users to select a server whenthe agent is enabled. This option is useful for distributing agents inready-to-use applications.

Examples of agents to run before Web users open or save documentsTo perform error checking, field validation, and other processing beforeWeb users open or save documents, create a shared agent that runsmanually. Then write a formula that uses @Command([ToolsRunMacro]) torun the agent and attach it to the WebQueryOpen or WebQuerySave formevents. This simulates the LotusScript QueryOpen and QuerySave formevents that aren’t supported on the Web.

WebQueryOpen eventsA WebQueryOpen event runs the agent before Domino converts adocument to HTML and sends it to the browser. Domino ignores anyoutput produced by the agent in this context.

Examples for using this agent include performing large computations thataren’t possible with @commands or collecting statistics about who openeddocuments and when they did so.

Note WebQueryOpen agents run when the user opens a form ordocument, but do not run when the user saves a document. This means thatcomputed fields set by a WebQueryOpen agent are not saved when the usersubmits a document. To make sure computed fields are saved, you caneither recalculate them in the WebQuerySave agent or set the form property“Generate HTML for all fields.”

WebQuerySave eventsA WebQuerySave event runs the agent after field input validation formulas are run and before the document is actually saved to disk ormailed. The agent can modify the document or use the document data toperform other operations. The document is automatically saved after theagent runs. Do NOT have the agent explicitly save the document (forexample, by calling NotesDocument.Save) because an explicit save couldcause incorrect results.

A WebQuerySave agent can product output to be sent back to the user. Forexample in a LotusScript agent, you can use the Print command to returnraw HTML. If the agent produces output, then the form should not have a$$Return field because Domino will return only the agent output andignore the field.


Examples for using this agent include:

Performing complex field validation. If the document does not passvalidation, you can prevent Domino from saving the document byadding a SaveOptions field with a value of “0” to the form.

Simulating CGI programs that run on user-supplied data byprogramming a WebQuerySave event and adding a SaveOptions field with a value of “0” to the form. When the agent runs, you cancollect field values from the filled-out form without generating a newNotes document.

Collecting statistics based on data submitted by browsers, such as CGIvariables, by writing a program that uses CGI variables and attaching itto a WebQuerySave event.

Setting up agent security

Users who create and run agents in Notes databases stored locally on theirworkstations can create and run any type of agent without any restrictions.The restrictions described in this section do not apply.

For agents created and run in Notes databases stored on servers or run fromthe Web, you can set up several levels of security controls to preventunauthorized operations.

Who can create agentsTo control who can create agents that run on servers, use database ACLs:

To create personal agents, users need Reader access or higher and have“Create personal agents” enabled.

To create shared agents using simple actions and formulas, users needDesigner access or higher.

To create shared agents using LotusScript or Java agents, users needDesigner access or higher and have “Create LotusScript/Java agents”enabled.

Web users cannot create agents.


Who can run agentsTo control who can run agents on servers, use the Server document In theAddress Book and database ACLs.

Personal agentsTo control who can run personal agents, open the Server document in theAddress Book and click the Security tab. In the Agent Restrictions section:

If everyone who can access the server can run personal agents, leave“Run personal agents” blank.

If only specific users can run personal agents, specify their names in“Run personal agents.”

Web users cannot run personal agents.

Shared agentsTo control who can run shared agents, use the database ACL. Users withReader access or higher can run shared agents.

If users are allowed to run shared agents, assign them Reader access or higher.

If users are not allowed to run shared agents, do not list them in theACL or assign them Depositer access.

LotusScript/Java agentsLotusScript and Java include operations that have full access to the server’ssystem and can manipulate system time, file I/O, and operating systemcommands. Users or groups with unrestricted access can run an agent thatincludes any of these operations in the LotusScript and Java components.Users or groups with restricted access can include most operations. Theonly restricted commands are those that allow access to the server’s system.

If no one is allowed to run any type of LotusScript or Java agent, leaveboth “Run restricted LotusScript/Java agents” and “Run unrestrictedLotusScript/Java agents” blank.

If users are allowed to use most LotusScript and Java commands, thenthose users have restricted rights. Specify their user names in “Runrestricted LotusScript/Java agents.”

If users are allowed to run any LotusScript and Java agent, then thoseusers have unrestricted rights. Specify their user names in “Rununrestricted LotusScript/Java agents.”

Caution Unrestricted Java and LotusScript agents can potentially violate security. Only a limited number of trusted users should haveunrestricted rights.


Where can agents runTo control whether agents are allowed to run on servers, use the Serverdocument in the Address Book. Click the Security tab. In the Server Access section:

If everyone running an agent that accesses the server is allowed toaccess the server, leave “Access server” blank.

If you don’t want users accessing the server either directly or throughagents, specify the user names in “Access server.” Then, if a user who isnot specified attempts to run an agent that accesses the server, the agentis not run. You can also specify user names in “Not access server.”

What operations can agents runTo control which documents agents can process, Domino checks the ACL ofthe database where the documents are stored, as follows:

For agents that use simple actions, LotusScript, and Java, Dominochecks the user’s ACL

For agents that use formulas, Domino checks the replica ID of thedatabase in which the agents were created. Therefore, to ensure thatagents using formulas to access documents in other databases, youmust list the database replica ID in each database the agent will access.

To control whether agents are allowed to create databases, use the Serverdocument in the Address Book. Click the Security tab. In the Server Access Section:

If everyone is allowed to create databases, leave “Create newdatabases” blank. Then, anyone running an agent that creates newdatabase can do so on the server.

If you don’t want users creating databases, specify the user names ofpeople allowed to create databases in “Create new databases.” Then, ifa user who is not specified runs an agent that creates a database, anerror is reported and the database is not created.

When restrictions are checkedDomino checks the security restrictions differently depending on where theagent is running:

If the agent is running locally or on the server

If the agent is running in the foreground or background

If the agent is started from the Web or the Notes client


Local or serverAn agent runs locally when:

It runs on a database stored on a workstation.

It runs on a database stored on a local server.

You specified “Local” in the “Run on” list for a scheduled agent.

User starts it from the Actions menu, agent list, or the When documentsHave Been Pasted trigger.

When an agent runs locally, Domino does not check security restrictions,unless you have set the Enforce Local ACL option.

An agent runs on the server when it is running in a database stored on aserver and it is started by one of the following:

Before new mail arrives

After new mail arrives

If documents have been created or updated

On schedule more than once a day

On schedule daily

On schedule weekly

On schedule monthly

If the agent is running on a server, Domino checks all security restrictions.

Foreground or backgroundAn agent runs in the foreground when a user starts it from the Actionsmenu or selects it from the Agents list. When running in the foreground,Domino does not check security restrictions.

An agent runs in the background when it is scheduled or it is triggered byan event (for example, when documents are modified). When running inthe background, Domino checks security restrictions.

From the Notes client or the WebWhen a user runs an agent from the Notes client, the agent runs with the rights of the agent creator. Complete these steps to find out who the creator is:

1. Select the agent in the agent list and choose Agent - Agent Properties.

2. Click the Fields tab.

3. Select the $UpdatedBy field and check the user name in the right pane.

When a Web user runs an agent, the agent runs using the rights of theagent’s creator and Domino checks the creator’s rights to access thedatabase. However, you can set up the agent so that Domino checks the


invoker’s rights to access the database instead of the creator’s rights.Checking the invoker’s rights can provide more security.

Complete these steps to specify that Domino verify the invoker’s access tothe database:

4. Select the agent in the agent list and choose Agent - Agent Properties.

5. Click the Design tab

6. Select “Run Agent as Web user.”

After selecting “Run Agent as Web user,” Domino prompts a Web user fortheir name and password when they attempt to run the agent. Domino usesthe login information to check for the invoker’s rights in the database ACL.

Security controls for agents that are called by agentsWhen agents call other agents, Domino checks the security restrictions foreach agent. However, when the creators of agents are different, Dominochecks security as follows:

If the first agent uses simple actions or formulas

Domino checks all agents that are called against the rights of the creatorof the first agent.

If the first agent uses LotusScript or Java

Domino checks each agent that is called against the rights of the creatorof each agent.

Troubleshooting agentsYou can experience problems running agents at several points during agentdevelopment, deployment, and implementation. There are several tools tohelp diagnose the problems in each stage.

Simulate an agent run: for all types of agents

Before running an agent on a live database, test it by simulating a run.The test also diagnoses whether the agent will run by checking securityand schedule settings.

Agent Log: for all types of agents

The Agent Log displays information about when the agent last ran andwhether it ran successfully.

Notes server console: for all types of agents

There are 3 server console commands available to display informationabout agent scheduling, status of agent queues and control parameters,and status of agent debugging settings that are in effect.


Agent Manager debug information: for all types of agents

You can specify that the Agent Manager record debug informationabout any combination of the following: control parameters, events,loading reports, memory warnings, performance statistics, executionreports, and scheduling.

LotusScript debugger: for agents built with LotusScript that run in theforeground

Choose File - Tools - Debug LotusScript and run the agent. TheLotusScript debugger appears and you can run any debuggingcommand in the agent as you would for any LotusScript program.

NotesLog classes: for agents built with LotusScript or Java that run inthe background

The NotesLog class is added to your agent code and can captureinformation you want to track. The NotesLog class records theinformation in the Agent Log.

Simulating the running of an agentYou can simulate a run in two ways:

For agents that do not call other agents and use only simple actions orformulas, use the Test menu item.

For agents that use LotusScript, use the LotusScript debugger.

For more complicated agents, create a test copy of the database.

Use the Test menu item1. Select the agent and choose Actions - Test.

2. Read the Agent Log and check for:

How many documents would be processed

What action would be taken if the agent were actually run

3. If necessary, make corrections and re-run the test.

LotusScript agents1. Choose File - Tools - Debug LotusScript.

2. Run the agent and the LotusScript debugger appears. You can thensingle step through the agent.

Create a test databaseFor agents that have multiple steps or complex tasks, split the process intoseveral smaller tasks and create an agent for each. Test and fix each smalleragent first. When everything is working correctly, combine the agents intoone. Then test the agent again.


1. Choose File - Database - New Copy to make a test copy of the database,with documents.

For all agents except those that act on mailed documents, the test copycan be local.

If the agent works on mailed documents, the test database must be on a server, and a Mail-in Database document must exist in the Address Book.

2. Create test documents:

If the agent works on mailed documents, mail a few documents tothe test database.

If the agent works on pasted documents, paste a few documents intothe test database.

3. Run the agent.

4. Use the other debugging tools to catch errors and make corrections.

5. Re-run the agent until it is working correctly.

6. Copy the tested agent to the live database.

Agent LogEvery time an agent runs, it writes a report with the following information:

When it ran

The number of documents it processed

The actions it took on the documents

Each new run of the agent writes over the previous log report. Dominostores the Agent Log with the database.

To view the most recent Agent Log:

1. Select the database and choose View - Agents.

2. Select the agent whose log you want to check and choose Agent - Log.

3. Review the information in the Log.

If you are running agents built with LotusScript or Java and the agents runin the background, you can add the NotesLog class to your agent code torecord run-time information in the Agent Log.


Notes server console commandsThese server console commands support agent debugging:

tell amgr schedule

Use this command to see if the agent is scheduled to run. If it doesn’tappear in the list when it should, then you know to check its schedule.This command does not list agents that are manually run from theActions menu or Agents list.

tell amgr status

Use this command to see where your agent is running (that is, in whichqueue) and what parameters are in effect.

tell amgr debug

Use this command to display and change the debugger settings. Thesesettings apply to the Agent Manager debugger that you enable in theNOTES.INI file.

Tell amgr scheduleTell amgr schedule lists each agent that is scheduled to run on the currentday. It lists only agents that run in the background. Check the list for thefollowing information to make sure the agent is scheduled correctly.

Display Description What to check for

First column:

E S V

The Agent Manager queue thatthe agent current is in.

E: Eligible to run

S: Scheduled to run

V: Waiting to run

If the agent is scheduled,make sure it is listed with anE or S. If it is listed, check thatthe correct time is listed. If theagent is not listed, check the“When should this agent run”setting.

If the agent runs when newmail arrives or a document iscreated or updated, it shouldbe listed with a V. If it isn’tlisted, check the “Whenshould this agent run” setting.

Second column:S M U

The event that activates the agent.

S: Daily, weekly, monthly, ormore than once a day schedule

M: New mail has arrived

U: One or more documents havebeen created or updated

If the agent has an incorrectevent or isn’t listed when itssupposed to be, it means thatyou selected an incorrect“When should this agent runsetting.”

continued


Display Description What to check for

Time of day If the agent is scheduled to rundaily, weekly, monthly or morethan once a day, the time of daythe agent will run is listed.

Check and make sure theagent is listed.

Today If the agent is scheduled to run daily, weekly, monthly, ormore than once a day and thetime it is supposed to run hasn’tgone by, then “Today” is listed.

Check and make sure theagent is listed.

Agent Name The agent name that is scheduledto run.

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

Make sure the agent isworking in the correctdatabase.

Tell amgr statusTell amgr status lists the number of agents in queues and other run-timestatistics. Even though agent names are not listed, you can check the queueinformation to determine if the queues are processing the number of agentsyou would expect. You can also check the run-time statistics to how theAgent Manager is set up.

For example, Agent Manager status information includes:

The number of agents in queues waiting for events, such as New Mailand Document Update

The number of agents in queues waiting for a scheduled time to elapse,such as the Scheduled Task queue

The time period, such as Daytime or Weekend

The maximum amount of time that a LotusScript/Java agent is allowedto run

Tell amgr debugTell amgr debug lists the Agent Manager debugger settings you specifiedwith the Debug_AMgr statement in NOTES.INI. Use this command to makesure the debugger settings are correct and to change them using the sameoptions that are available for the Debug_AMgr statement, except *.

For example, to add options for the Agent Manager that you have alreadyset up to display agent debugging information (-e option):

tell amgr debug -e, -l, -m, -p


Agent Manager debugging informationYou can specify that the Agent Manager record debugging information inthese ways:

Specify Debug_AMgr in NOTES.INI

Use this statement to provide debugging information about agentloading, scheduling, and performance. When you specifyDebug_AMgr, you can use the tell amgr_debug command at the Notesconsole to change the settings.

Note If you specify that the Agent Manager display all possibledebugging information, agent performance can be significantlyaffected.

Specify Log_AgentManager in NOTES.INI

Use this statement to provide a subset of debugging information of theinformation recorded with Debug_AMgr. Log_AgentManager does notaffect agent performance as much as Debug_AMgr could.

If you specify both statements, the Debug_AMgr settings take precedence.

Debug_AMgrTo specify that the Agent Manager record debug information, edit notes.iniand add the following statement:

Debug_AMgr=option

where option can be one or more of the following:

c — list agent control parameters

e — list Agent Manager event information

l (lowercase L) — list agent loading information

m — list agent memory warnings

p — list agent performance statistics

r — list agent run-time reports

s — list Agent Manager scheduling information

v (verbose) — list more information about agent loading, scheduling,and queues

* — list all of the information for all options

After you specify Debug_AMgr in NOTES.INI and you run an agent on aserver, check the Notes console and Notes Log for the debugginginformation. Optionally, you can redirect the debug information to be


recorded in a separate file on the server. When you redirect the debugginginformation to a separate file, performance can be affected. To redirectinformation, 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, youmust redirect the output because the Notes console is only on the server.

Log_AgentManagerTo specify that the Agent Manager record less debugging information thanwith Debug_AMgr, edit NOTES.INI and add the following statement:

Log_AgentManager=option

where option can be one of the following (but not more than one):

0 — do not list debugging information

1 — list partial and complete information about successful agent runs

2 — list complete information about successful agent runs

NotesLog ClassUse the NotesLog class in LotusScript and in Java agents that run in thebackground. Add the NotesLog class to your agent code to record run-timeinformation. It is particularly helpful for capturing variable values, errorhandling, and verifying code logic. By default, the NotesLog class recordsinformation to the Agent Log. When you set up items you want recorded,make sure you don’t exceed the Agent Log limit.

To use NotesLog, follow this LotusScript example that tracks the documentsan agent is processing by capturing the documents’ Subject. Theinformation is recorded in the Agent Log.

Dim agentLog As new NotesLog("Agent log")Call agentLog.OpenAgentLogSet s=New NotesSessionSet db = s.CurrentDatabaseSet collection = db.UnprocessedDocumentsSet note = collection.GetFirstDocumentcount = collection.CountDo While (count >0)Subject = note.SubjectCall agentLog.LogAction("Processing:"+Subject(0))Set note = collection.GetNextDocument(note)count = count-1LoopCall agentLog.Close


Agent Log limitThe Agent Log can hold only 64KB of information. When the informationwritten to it exceeds this limit, the following message is displayed and theagent stops running:

Error executing agent <agent-name> in <database-name>. Memory allocationrequest exceeded 65,000 bytes.

Make sure that the information you want recorded to the Agent Log doesnot exceed this limit. If it does, rework the NotesLog class code to recordless information per run.

AgentRunnerAgentRunner is a Java application program for debugging Domino agentsin a Java IDE. There are two versions of AgentRunner for different packageclasses:

lotus.domino.AgentRunner for lotus.domino (Notes/Domino, Release 5.0)

lotus.notes.AgentRunner for lotus.notes (Notes/Domino Release 4.6.x)

Also included is a set of debug classes that access Notes context informationwhile running in a Java IDE.

To use AgentRunner:

1. Create agent code to extend DebugAgentBase.

2. Run the agent to generate an AgentContext document in theAGENTRUNNER.NSF.

3. Run AgentRunner that runs your agent code outside Notes. TheAgentRunner code accesses the AgentContext document to make theprogram behave as though it were running as an agent. This allows youto build and run without having to switch between the IDE and Notes,and to use IDE run-time tools such as the debugger.

Create a project for your agentIn Java IDE:

1. Add the fully-qualified file specification for NOTES.JAR (for example,for JDK or Cafe) to your Java IDE’s CLASSPATH or Import (forexample, for VisualAge) the JAR file to your project.

2. Create an agent (see the Domino Designer Programming Guide) thatextends DebugAgentBase, instead of AgentBase.

Note To select the correct version of DebugAgentBase:


For Notes, Release 4.6-style agents — use the “import lotus.notes.*;” format.

(Recommended) For Notes, Release 5 — use “importlotus.domino.*;”

3. Build the project as an application. It does not matter if the agent has amain() method, but if your IDE requires one, add a dummy one. Noteswill not use it.

4. If required (for example, for VisualAge), export the .CLASS files.

Generate an AgentContext documentIn Notes:

1. Build a Java agent in a Notes database and import the .CLASS filesfrom your project. Ensure that the base class is the class that extendsDebugAgentBase.

2. Run the agent to generate an AgentContext document inAGENTRUNNER.NSF.

Note When the agent runs in Notes, a call to getSession() from anagent class that extends DebugAgentBase returns NULL aftergenerating an AgentContext document. Therefore, any use of thereturned session results in a thrown exception. Because the purpose ofrunning the agent is only to generate the context document (and not torun any of the agent code), you can ignore the exception.

3. Open AGENTRUNNER.NSF and examine the most recentAgentContext document. Note the name of the server, the file path ofthe database, and the name of the agent. “Local” is the name of theserver for a local database.

4. Edit the AgentContext document and change the “Agent Runs On” and “Search Criteria” fields to generate the UnprocessedDocumentscollection that you would like to use for debugging. You must supplythis information because it cannot be determined from running the agent.

Note the “Agent Runs On” and “Search Criteria” that you specified inthe agent that you ran to generate this document will produce the“Selected” document list.

5. Save and close the document.

You can generate another AgentContext document later if you want tochange the run-time environment. You can edit fields other than “AgentRuns On” and “Search Criteria” to change the run-time environment, but itis not recommended.


Run AgentRunner to debug your agentIn Java IDE:

1. Specify <Agent> [<Database> [<Server>]] arguments, as displayed inthe “AgentContexts” view of AGENTRUNNER.NSF, to theAgentRunner program to select the AgentContext document that youwant to use for debugging your agent code. If running from acommand line, enter:java lotus.domino.AgentRunner <Agent> [<Database>[<Server>]]

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

2. Set a breakpoint on the first executable line of code in the NotesMain()method of your agent.

3. Build the project.

4. Run or debug the project. If you are debugging and no breakpoints areset, you should step into NotesMain() to access your code.

5. In certain IDE’s (like Symantec’s Visual Cafe), you can’t specify that aproject’s main() entrypoint be in a class in the JAR or ZIP file. For theseIDEs, you must create a dummy main application with the onlypurpose to call the main() method in AgentRunner. For example: import lotus.domino.*;public class Main{ public static void main (String[] args) { try { AgentRunner.main(args); } catch (Exception e) { e.printStackTrace(); } }}


Simple actions for automation components

Use simple actions with shared and unshared actions, buttons, actionhotspots, and agents. Web applications do not support simple actions.

Copy to DatabaseCopies the selected document to the database you specify. You can copyand paste selected documents in the same database or another database onthe same server where the agent is running (that is, you cannot copydocuments to a database on a server other than the agent’s own). They aremarked as read in the target database.

To specify:

1. Click Choose Database.

2. Select the server and target database.

Copy to FolderCopies the selected document to the folder you specify. You must createnew folders before you can select them. Copying a document from onefolder to another does not remove the document from the source folder. Aduplicate of the document is not created; instead the document is displayedin a new place.

Delete from DatabaseDeletes the selected documents from the database. If there are replicas ofthis database on other servers, documents deleted in this database are alsodeleted in the replicas unless “Do not send deletions made in this replica toother replicas” is selected in your database replication settings (choose File -Replication - Settings and click Send to see what the settings are).

Mark Document ReadMarks selected documents as read. Use this action to mark an unreaddocument as read without opening it or for reverting a document that wasmodified back to its read status because it doesn’t actually need to be readagain — for example, if it has been modified by an agent.

Combine this action with one that changes field values. Then when userschange 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 UnreadMarks selected documents as unread. Use this action for flagging adocument that users want to read again.

Modify FieldReplaces or appends a single field value with a new text value you specify.This action replaces only text values for documents in Edit mode. Toreplace a value with something other than text, use an @function formula orLotusScript program. This action can modify the value of a hidden field, ifyou can specify the field’s name.

The Append Value option does not work for rich text, number, or timefields or for fields that are not available within documents already saved inthe database. Also, Append Value is not available if a database does notcontain any documents (for example, a database template).

To include Append Value in databases without documents:

1. Create a placeholder document containing the field.

2. Create the agent using the field from the placeholder document.

3. Delete the document.

Optionally, you can use a formula instead of a simple action.

To specify a value:

4. Select the field to be modified from the Field pull-down list.

5. In the Value text box, enter the new value.

6. Select “Replace value” or “Append value.”

Modify Fields by FormReplaces several field values on a form with new text values you specify.This action replaces only text values. To replace a value with somethingother than text, use an @function formula or LotusScript program. Thisaction marks processed documents as read.

To specify:

1. Select the form.

2. Enter the new value in the fields.


Move to FolderMoves 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 thespecified folder. The document is not deleted from the database.

Remove from FolderRemoves selected documents from a folder you specify but does not deletethe documents from the database. If a document is included in severalfolders, this action removes the document from the specified folder, butdoes not remove the document from other folders. If a document isincluded in only one folder, this action removes the document from thefolder and changes its category to Uncategorized.

Reply to SenderSends a reply to a mail memo automatically. Replies are not sent to a mailmemo that was generated by an agent. The Body field accepts only plaintext. 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 originalmessage to your reply.

4. Select “Reply only once per person” if a person is included in multiplemailing groups.

Run AgentAllows you to chain agents together with other agents or combineLotusScript programs, @function formulas, and Java in one agent. Theagent to be run must already exist in the database.

The documents that additional agents process are determined by the firstagent. All subsequent agents use the same documents, regardless of theirown settings. The first agent completes its search and actions first and thenpasses that information to the second agent. For example, Agent A searchesfor all documents with the word “green,” replaces “green” with “yellow,”and then runs Agent B. Agent B launches its own search queries and actionsonly on the documents that Agent A processed.


Send DocumentMails the current document to the recipients designated in the document’sSendTo field. This action works like the @MailSend function. To predict therecipient, the document must have a SendTo field. If it doesn’t, Notes usesthe contents of the internal $UpdatedBy field as the recipient. If thedocument also contains the CopyTo or BlindCopyTo fields, it is routed tothose recipients at the same time.

If the document contains the DeliveryPriority, DeliveryReport, orReturnReceipt fields, they control the delivery priority, generation of adelivery report, and generation of a return receipt. If the document doesn’tcontain these fields, they default to normal priority, no delivery report, andno return receipt, respectively.

Send Mail MessageMails 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 formulasfor the To:, cc:, bcc:, and Subject: fields.

3. Enter a subject.

4. In the Body field, enter the message text.

5. (Optional) Click “Include copy of document” to append the documentto the message.

6. Select “Reply only once per person” if a person is included in multiplemailing groups.

Send Newsletter SummarySearches a database for documents matching conditions you specify, thensends a summary document with links to the individual documents. Thesummary information includes items such as a one-line description of theDate, Author, and Title columns.

The “Gather at least” option does not apply to sending a documentsummary from a view or folder with an action because the action can act on only the highlighted document, and “Gather at least” acts onmultiple documents.


To specify:

1. Specify recipients in the To field.

2. (Optional) Click More to specify more addresses using text or formulasfor 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 textsummary of each document. Deselect it to send only document links.

6. Choose a view.

@Function FormulaAdds a customized @function formula.

LotusScript for automation componentsUse LotusScript for shared and unshared actions, buttons, action hotspots,events, and agents. LotusScript can be used to access data in Notesdatabases and in external applications. For example: you can useLotusScript to change a value in one document based on values in otherdocuments or modify database ACL lists.

Refer to the Programming Guide and the LotusScript Language Guide for moreinformation about LotusScript.

Working with HTMLYou can use the LotusScript Print statement with HTML as follows:

To display HTML information

For example, add this line to display the message “Thank you for your submission”:Print "<H1>Thank you for your submission</H1>"

To provide instructions to a browser

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


Restrictions for using the Print statement include:

It must be attached to a user-run automated component, such as anaction, a button, a manually-run agent, or a WebQuerySave event thatuses @Command([ToolsRunMacro]).

If it is attached to a manually-run agent, it must also be a shared agent.

It cannot be attached to a WebQueryOpen event.

Restricted LotusScript and Java agent operations

Restricted backend class and method

Task LotusScript Java

Using a disk-based log file

NotesLogOpenFileLog(path)

Log openFileLog(path)

Using Environmentvariables

NotesSessionGetEnvironmentString()

NotesSessionSetEnvironmentVar()

NotesSessionGetEnvironmentValue(SystemVariable,true)

SessiongetEnvironmentString()

SessionSetEnvironmentVar()

SessionGetEnvironmentValue(SystemVariable,true)

Encrypting or signing NotesDocument Sign()

NotesDocument Encrypt()

Document sign()

Document encrypt()

Embedded Objectmanipulation

NotesRichTextItemEmbedObject()

NotesEmbeddedObjectExtractFile(path)

RichTextItem embedObject()

EmbeddedObjectextractFile(path)


Restricted programming language operation

Task LotusScript Java

File I/O Open statementChdir statementChdrive statementclose statementcurdir statementdir statementeof statementfileattr statementfiledatetime statementfilelen statementfreefile statementget statementgetfileattr statementinput statementinput # statementinputb statementline input # statementloc statementlock statementlof statementmkdir statementreset statementrmdir statementseek statementsetfileattr statementunlock statementwidth statementwrite statement

No file I/Ooperations allowed

Network I/O N/A No network I/Ooperations allowed

Setting system date/time Date and Date$ statements

Time and Time$ statements

Not allowed

Calling a “C” routine External C calls Declarestatement

Not allowed

Executing anotherapplication

ActivateApp statement

Shell statement

Not allowed

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


Formulas for automation components

Use formulas for shared and unshared actions, buttons, formula pop-ups,hotspots, events, and agents.

Using @Command formulas with actions and hotspotsWhen an action or hotspot uses an @Command formula, the formula worksonly when it runs in the appropriate context. Keep the following in mind:

A hotspot or action can process a field or an entire document, but not aselected area. When you point to the button to activate it, you lose theprevious selection — that is, the previous highlight disappears, andonly the button is highlighted. To work around this, use @Commandwith parameters such as EditLeft or EditRight which move the focuswithin a document. Then when the user activates the hotspot or action,Notes uses the formula to determine what is affected.

Formulas designed to edit a field don’t work when the document is inread mode. To work around this, use @Command([EditDocument]) toput a document in edit mode.

About security features that affect automation formulasAutomated components with formulas run by users work only if usersactivate them in the correct context and have enough privileges to performthe automated task. For example, if a formula in a hotspot uses @SetField tochange a field value, the hotspot doesn’t work when the user activating ithas only Reader access or the document is in read mode.

An automated component with formulas cannot usually completeunauthorized tasks on a database stored on a server because most users donot have privileges that allow them to run such tasks. However, in a localdatabase where you have Manager privileges by default, an automatedcomponent with a formula could potentially change documents. If you areunfamiliar 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:

@Command

@PostedCommand

@DbCommand, @DbColumn, @DbLookup (only if it refers to anon-Notes database)

@MailSend

Dynamic Data Exchange (DDE) including all @DDE functions

Object Linking and Embedding (OLE)

Launching attached files

The user doesn’t see a message, but the formula won’t run.

JavaScript for automation components

Use JavaScript for shared and unshared actions, buttons, action hotspots,and events. JavaScript Version 1.3 is currently supported.

JavaScript is particularly useful for providing interactive components, such as:

Form and field validation

Mouse effects (such as image rollover buttons and friendlier URLs)

Numeric calculations

Dialog box simulations

When you use JavaScript, more processing can be done at the workstationinstead of the server, thereby reducing network traffic and improvingrun-time task processing.

JavaScript works with Notes objects, such as a window, document, or field.The objects that you can attach JavaScript to vary, according to thecomponent you are working on. In the Info List, click Objects to see what isavailable. For example, set up a JavaScript automated task for an OnClickevent in a hotspot.

You can also check this table to see what JavaScript objects are available ineach automated component and whether they are supported in differentbrowsers and the Notes client.


Table of supported JavaScript objects for automated componentsThis table lists the JavaScript objects that are available for automatedcomponents and which browsers support the event.

JavaScript Object Button ActionHotspot

Form Action

SharedAction -Form

ViewAction

SharedAction -View

onBlur Works in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

Doesn’t work in Notesbrowser,Notesclient,Netscape

Notesbrowser,Notesclient,Netscape





onClick Works in

Notesclient,Netscape,InternetExplorer

Notesbrowser,Notesclient,Netscape,InternetExplorer





Doesn’t work in Notesbrowser

Notesbrowser

Notesbrowser

Notesbrowser

Notesbrowser

onDblClickWorks in

Netscape,InternetExplorer






Doesn’t work in Notesbrowser,Notesclient

Notesbrowser

Notesbrowser,Notesclient




onFocusWorks in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







continued



Form Action

SharedAction -Form

ViewAction

SharedAction -View

onHelpWorks in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







onKeyDownWorks in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







onKeyPressWorks in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







onKeyUpWorks in

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







onMouseDownWorks in













continued



Form Action

SharedAction -Form

ViewAction

SharedAction -View

onMouseMoveWorks in

InternetExplorer


InternetExplorer

InternetExplorer

InternetExplorer

InternetExplorer







onMouseOutWorks in













onMouseOverWorks in













onMouseUpWorks in














Importing Java programs

Agents running on Domino servers can run Java programs. Dominosupports Java, Version 1.1x and later.

1. After you select Imported Java from the Run pull-down list, clickImport Class Files.

2. In the Define Java Agent Files dialog box:

Select “Local Filing System” from the Browse pull-down list.

In Base Directory, enter the path for the Java files.

In Base Class, enter the name of the main class.


Click Select All to add all the Java files.

Select them one-by-one and click Add/Replace File.

4. Make sure the files in the Current Agent Files List are in the same orderthat they should run. If not, re-order them using the Reorder Up andReorder Down buttons.

Creating Java programs for agents

RequirementsTo use Java programs, write class files in advance that meet theserequirements:

Use Java Version 1.1.x or later.

Use the Java Notes classes to access Notes — Extend thelotus.notes.AgentBase class.

Java Notes classes parallel the LotusScript Notes back-end classes. Youcan use these classes from any Java program, within Notes or outside,as long as Notes Release 4.6 or later is installed.

When the agent runs, it should run code in the NotesMain() method.

There must be a Base Class file, which is the starting point for the agentcode.

Other files can include other source (*.java) files, Class (*.class) files andArchive (*.jar) files.

See the Domino Designer Programming Guide, Volume 3 for detailedinformation on the Java classes.


Create the Java program1. After you select Java from the Run pull-down list, Designer sets up:

Base Class file with the name of the agent and the .java extension.

A Classes list with the required NotesMain() method.

Stub code for the Base Class and the NotesMain() method in theright-hand pane of the Programmer’s pane.

2. Complete the code in the NotesMain() method.

3. Click New Class to add classes.

4. Click Edit Project to associate Java files with the Base Class.

5. (Optional) Click Export to store the Java file independently of the agenton your computer.

6. Save the agent.

Actions and agents namesThe names you give to manually-run agents appear as choices in theActions menu. The names you give to form actions and view actions appearas choices in the Actions menu and on the action bar. The names arecase-sensitive and can be any combination of characters, including letters,numbers, spaces, and punctuation.

Naming tipsChoose short names for form and view actions that you design toappear as action bar buttons.

Choices on the Actions menu appear in alphabetical order. To forcenames to appear in a different order, number or letter them.

Use consistent names across databases to enable users to recognizeidentical agents and actions.

Naming techniques

Alias namesAn alias is an internal name for an agent. Using an alias, you can change ortranslate the name that users see without disabling formulas that referencethe original name. Aliases follow the same naming rules as regular names.Alias names don’t work with form and view actions.


To create an alias name, add the alias name and a | (vertical bar) symbol tothe left of the original name. Always keep the original name as therightmost name.

Archive Documents | Agent1

Shortcut keysA 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 letteryou want to assign as the shortcut. For example, S is the shortcut for thisSave action:

_Save

Notes ignores the underline when it displays the name of an action on theaction bar.

Cascading namesIf you don’t want to overwhelm users with long lists or if you have relatedactions or agents that should be grouped together, group them so thatrelated menu choices appear under one main menu choice. You can createonly one level of cascading names.

Enter the name you want to appear on the Actions menu followed by a \(backslash), followed by the action or agent name. For example:

Mail Tools\Add Sender to Address Book

Mail Tools\Choose Letterhead

Actions that also display in the action bar show only the name after thebackslash.

The Calendar Profile agent in the Combined Mail (4.6) template contains aname that has a shortcut key, a cascading name, and an alias:

_Calendar Tools\Calendar Profile . . . | Calendar Profile


Hiding automated components

When you create most automated component, you can hide them undervarying conditions. Use the Hide tab of the Properties box to specify whento hide it.

Hide from Notes R4.6 or later

Hides a component when it is viewed from a Notes workstation. This isuseful for hiding components such as action bar buttons that youprovide to Web users as substitutes for Notes menu choices.

Hide from Web Browsers

Hides a component when it is viewed from a Web browser. This isuseful for hiding components that aren’t relevant to Web users.

Hide when opened for reading; Hide when previewed for reading

Hides a component when a document is opened in read mode from thePreview pane or as an open document. These options are useful forcomponents that are relevant only to new documents or documents inEdit mode — for example, actions that modify a field.

Hide when previewed for editing; Hide when opened for editing

Hides a component when a document is opened in edit mode from thePreview pane or as an open document. These are useful for componentsthat are relevant only to completed documents — for example, movingdocuments to another database, creating response documents, ormarking documents as unread.

Hide when printed

Hides the component when users print a document. This is useful forremoving clutter from a printed document.

Hide when copied to the clipboard

Hides the component when users copy a document. This is useful forremoving clutter from a copied document.

Hide if formula is true

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


Chapter 11Including Java Applets in Applications

This chapter describes adding Java applets to forms, documents, and pages.Although Java applets are used mostly for Web applications, you can alsoinclude them in Notes applications.

Java applets overview

You can include Java applets in the following elements of a Dominoapplication:

Form — The applet is included in each document created with thatform.

Document — The applet is available only in the document.

Page — The applet is available only in the page.

Although Java applets are mostly used for Web applications, you can alsoinclude them in Notes applications.

To include a Java applet in an application:

1. Enable Java applets on your workstation.

2. Import the applet from files on your workstation or on a file server, orlink to an applet on the Web.

3. Use the Programmer’s pane and the Properties box to set appletparameters, attributes, and properties. Some applets will run with nomodification, but most require that you set parameters or attributesbefore you can run them.

4. Correct problems with the Java applets. If the applet doesn’t run, youmay need to include additional files or set additional parameters.

5. Optionally, you can set up shared applet resources, that is, set uprelated files so that they can be used by several applets.

For more information about Java or to find applets you can use, see the JavaWeb site at http://java.sun.com.

303

A Java applet usually consists of a collection of files, with one file thatcontains the main class, or the starting point for the applet. There can alsobe image files, archive files, and Java source files. You can store Java appletfiles as follows:

When you import an applet, the files are attached as hidden files to theform, document, or page where you include the Java applet.

When you link to an applet, files are stored on the Web and a URLreference to those files is stored in the form, document, or page whereyou include the Java applet.

When you set up shared applet resources, the files are stored in thedatabase where you include the Java applets that use those files.

Requirements and restrictions for Java applets To create a Java applet, use the NetObjects BeanBuilderTM or anotherauthoring tool. You cannot use Designer to create a Java applet.

To include Java applets in an application, you must install Designer.

Supported browsers include Internet Explorer 3.0 or 4.0 and Netscape3.0 or 4.0.

Java applets created with Notes 4.6 and 5.0 will not work with previousreleases of Notes, unless the applet is stored on the Web and it has noparameters.

Java applets created with Notes 4.5 will work with Notes 5.0. If you useNotes 5.0 to change the applet parameters, the applet is saved as a 5.0applet and will no longer work in 4.5.

Enabling Java appletsBefore you can add a Java applet to a Domino or Notes application, youmust set up your workstation.

1. If you want to link to applets on the Web, make sure your Locationdocument specifies a valid Web proxy. See your system administrator ifyou 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 selectEnable Java applets.

Note If Enable Java Applets is not listed, check with your systemadministrator.

4. Click OK.


Importing an appletBefore you import a Java applet, you must enable Java applets on yourworkstation and make sure all the related files are available on yourworkstation.

1. Launch Designer and open a page or form, or click in the rich text fieldof a document.

2. Choose Create - Java Applet.

3. In the Create Java Applet dialog box:

Select “Import an applet from the file system or use an appletresource.”

In Base Directory, enter the path for the applet files.

In Base Class Name, enter the name of the main class.

To avoid typing the path and class name, click the folder icon tobrowse for the main class file for the applet. Clicking the main classfile inserts the class and the path in the correct fields.

4. Click Locate to see all related files for the applet.

5. Select the related applet files and click Add/Replace File. If you areinserting 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 nameOne way to make sure you have the correct name for the main class (whichyou enter in the Create Java Applet dialog box) is to use any text editor toopen 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 isArcTest.class.

<applet code=ArcTest.class width=400 height=400></applet>

Selecting related filesApplet files can be of the following types:

Class — *.CLASS

Archive — *.JAR, *.ZIP, *.CAB

Resource — *.JPG, *.JPEG, *.GIF, *.AU

Source — *.JAVA

Chapter 11: Including Java Applets in Applications 305

For most applets, you must select all class and resource files. Select thesource files only if you plan to send the applet to another user who wants toexport them and change the applet.

If you are inserting an applet that is packaged as a .JAR file, you can enterthe path and the main class name as described above. Note that browsingfor the .JAR file inserts the filename with a .CLASS extension in the ClassName field. In some cases, the file name and the main class name are thesame; in other cases, they are different and you must edit what appears inthe Class Name field to be the correct main class name.

If you have more than one applet in a form, document, or page, Notesstores only one copy of common files.

Importing applets packaged as .CAB or .ZIP filesIf you import an applet that is packaged as an archive file (such as either a.CAB or .ZIP file), consider the browsers the application users have:

For Internet Explorer users, include the .CAB file.

Note Domino does not display an embedded applet that is packagedas a .CAB file.

For Netscape users, include the .ZIP and .JAR files.

If users are likely to use either or both browsers, include .CAB, .JAR,and .ZIP files. Domino creates the appropriate parts of the APPLET tagfor these files. Netscape ignores the CABBASE (or CABINETS)parameter and Internet Explorer ignores the ARCHIVE attribute.

Linking to an applet on the WebBefore you link to a Java applet on the Web, you must enable Java appletson your workstation.

1. Launch Designer and open a page or form, or click in the rich text fieldof a document.

2. Select Create - Java Applet.


Select “Link to an applet on a Web server.”

In Base URL, enter the URL where the applet files are stored.


4. Click OK.



For the URL, specify the name of the URL where the applet resides, not thedocument that references the applet. For example, use

http://java.sun.com:80/applets/Bubbles

instead of

http://java.sun.com:80/applets/Bubbles/index.html

Java is case-sensitive, so check the capitalization of the class file.

Setting applet parameters

Some Java applets have parameters that use default values. You do notneed to specify values for these parameters. For applets that haveparameters without default values, however, you must set parametervalues or the applet will not run. You can manually enter parameters andvalues, or you can paste all of the parameters and edit associated values.

To set individual applet parameters1. 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 Info List of the Programmer’s pane.

3. Use any text editor and open the HTML file associated with the Javaapplet.

If you imported the applet, check the HTML file on your file system.

If you linked the applet, use a Web browser and check the HTML fileon the Web. For example, on Netscape you can choose View - PageSource to see the HTML file.

4. Click Add.

5. Enter the parameter name. For example, enter bgcolor for the followingHTML tag:<param name=bgcolor value="black">

6. Enter the corresponding value in the Parameter Value window. Forexample, enter black for the example HTML tag in Step 5.


To set all applet parameters1. 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 theClipboard. 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.

DetailsTo change a parameter value, click its name. Then change its value in theParameter value window.

The parameter value is a formula; therefore, you must enclose text values indouble quotes. In addition to text strings, a parameter value can be an@function or a field name.

If you are running an applet through a browser, you can add JavaScript to aform or document to interact with the applet by calling its public methodsor setting/getting its public properties.

Setting applet parameters, attributes, and propertiesAfter importing or linking an applet, you may need to set one or more ofthe following so that the applet runs correctly:

Parameters specify values the applet needs at start-up and for correctlydisplaying the applet in your application. The HTML file listsparameters for the applet in <param> tags.

To set parameters, use the Programmer’s pane and click AppletParameters.

Body attributes specify values that are specific to a browser, such asalignment 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 BodyAttributes.


Alternate HTML are attributes usually used by browsers that do notsupport Java. Domino uses the Alternate HTML attributes to generateHTML code that is placed in the <applet> tag.

To set Alternate HTML attributes, use the Programmer’s pane and clickAlternate HTML.

Properties specify how the applet appears in the page, form, ordocument where you have imported or linked it. You can also use Javaapplet properties to hide the applet under specific conditions.

To set properties, use the Java Applet Properties box.

Setting HTML attributes1. 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 attributesUse 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 text to notify users that they cannotuse their browser with the Java applet:"You're trying to run a Java applet with a browser thatdoesn't support Java. You can run this applet with Domino,Netscape Versions 3 and 4, or Internet Explorer Versions 3and 4."

Use the “Text to display when applet is not running” property in the Javatab of the Java Applets Properties box to specify text that a browser displayswhen it supports Java but cannot display the Java applet.


Setting propertiesUse the Java Applet Properties box to set some applet properties (forexample, height, width, and display) and application properties (forexample, alignment and whether to hide the applet).

1. Select the Java applet and choose Java Applet - Java Applet Properties.

2. Edit the properties.

For example, enter the following in the “Text to display when applet isnot running” field:This Java Applet is not currently available.

Java applet propertiesThe properties you can set for a Java Applet include the following:

Base class

The name of the main class file.

DocBase

Provided for information only. You cannot edit it.

CodeBase

CodeBase is the path storing the class files, relative to the base class file.If you linked to an applet on the Web, the URL of the directorycontaining the applet is displayed, and you can edit the URL name.Otherwise, the field is provided for information only.

Size

The Height and Width fields set the height and width of the appletdisplay area in the Domino application where the applet is running. Ifthe applet is too large to run in the default size, you must reset thesesettings, using the height and width settings from the HTML file. Todetermine the applet size, use any text editor or Web browser to viewthe HTML file. Check the width and height values specified in the<applet> tag. Enter these values in the Width and Height fields. Youcan also specify a size for the applet as a percentage of its parentwindow.

Text to display when applet is not running

Domino displays the text you specify when it can’t run the applet. Entera simple text string, such as “This applet is not working at this time.”

Applet uses Notes CORBA classes

Select this to let Web users access the applet. If you don’t select thissetting and a Web user tries to run the applet, an error is generated.


Applet uses CORBA SSL security

If you select “Applet uses Notes CORBA classes,” this setting becomesavailable.

Folder tab

If you import an applet, the folder tab displays all applet files.Otherwise, the page is blank.

Hiding an applet under certain conditionsYou can hide an applet so it appears only under certain conditions in theform or page. Click Paragraph Hide When tab in the Java Applet Propertiesbox and choose one of the following options:

Hide paragraph from

You can hide the applet according to how a user is accessing it: fromNotes or from a Web browser.

Hide paragraph when document is

You can hide the applet according to how the document is being used.For example, you might hide the applet when the document is open forediting.

Hide paragraph if formula is true

You can customize the conditions for hiding the applet by writing ahide-when formula that specifies the criteria for hiding the applet.

If you want to hide an applet based on the browser accessing it, completethese steps:

1. Create a field named HTTP_USER_AGENT in the form where youimported or linked the applet, or in the form used by the documentwhere you imported or linked the applet.

2. For the field type, select Text and Computed for display. Optionally,you can hide the field.

3. Enter the following formula for its value:HTTP_USER_AGENT

When a user accesses a document that uses this form, the Web serverfills in the field with a string describing the browser type and version.The format of the string differs according to the browser. Someexamples: Mozilla/3.0Gold (WinNT; I)

Mozilla/2.0 (compatible; MSIE 3.02; Update a; Windows 95)


4. In the Java Applet Properties box, enter a formula that uses this field tohide 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 InternetExplorer: @Contains(HTTP_USER_AGENT; "MSIE")

Setting up shared applet resourcesFor large Java applets with multiple files, consider storing some of therelated files as shared resources in the database. When you set up files asshared resources, all the applets can use a single copy of the file, instead ofeach applet storing its own copy. Then, if a file requires updating, you onlyneed to update one file.

To create a shared applet resource1. Launch Designer and select the database where you want to set up the

shared resources.

Note If you do not see a Recent Databases list on the left side ofDesigner, drag the Design pane to the right.

2. Click Resources - Applets.

3. Click New Applet.

4. In the Base Directory field, enter the path where the Java applet files arestored.

5. Select the files you want to set up as shared resources from theAvailable Java Files list and click Add/Replace file.

6. Click OK and enter a name. Click OK and Domino stores all the files asa shared resource to which you can refer, using the name you entered.

To include a shared applet resource1. In the database where you created the shared applet resource, open a

document and click in a rich text field.

2. Choose Create - Java Applet.


Select “Import an applet from the file system or use an appletresource.”

In Base Directory, enter the path for the applet files.


4. Click Locate to see all related files and shared resources for the applet.

5. Select “Local Filing System” in the Browse list and select the relatedapplet files. Click Add/Replace File.


6. Select “Shared Resources” in the Browse list and select the sharedresources that this applet uses. Click Add/Replace File.

7. Click OK twice.

Selecting, running, deleting, and copying applets

Selecting an applet 1. If the applet is running, you cannot select it. Choose View - Show - Java

Applets Running to stop the applet.

2. Click directly to the right of the applet.

3. Use the left arrow key to select the applet.

Running an appletWhen you open the page, form, or document containing an applet, it startsrunning automatically. To restart an applet after you stopped it,double-click it.

Stop running appletsTo stop running all applets in a page, form, or document, choose View -Show - Java Applets Running.

Deleting an applet and its related filesTo delete an applet, select it and choose Edit - Delete or Edit - Clear. Youcannot undo the deletion of an applet. When you delete an applet that youhave imported, the related files are also deleted, unless another appletshares the files. If you want to delete shared files, you must delete them ineach page, form, or document that contains an applet that uses them.

Copying an appletYou 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 itsrelated files are copied. When you copy an applet you have linked to on theWeb, only the link is copied.

1. Select the applet in the page, form, or document.

2. Choose Edit - Copy.

3. Click in the page, form, or document where you want to copy theapplet.




Refreshing and exporting applet files

To refresh applet filesRefresh the applet when you need to update existing files or add new filesto the applet.

1. Select the Java applet and choose Java Applet - Refresh.

2. Select files to add or replace, and click Add/Replace File.

3. Click Refresh.

To export filesExporting an applet allows you to copy all the applet files to yourworkstation or any other place to which you have access.

1. Select the Java applet and choose Java Applet - Export.

2. Choose the directory to export the files to and click OK.

Domino exports all the applet files and creates subdirectories asneeded.

Setting security for applets To protect the security of the file system, Java security generally does notallow applets to access Notes classes. However, you can set up the applet sothat it can access Notes classes, thereby allowing it to open a database andchange data in it.

Setting security for applets in NotesTo set up secure access for applets that will access the file system or NotesJava 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 theworkstation.

1. In the database storing the Java applet, choose File - Database - AccessControl and set up the ACLs.

2. Choose File - Preferences - User Preferences.

3. Click Security Options.

4. Select Java applet security.

5. Enter the users and/or groups that will have access to the file system orNotes classes.

6. In the Allow list, select the options the users can use while running theJava applet.

7. Click OK twice.


When a user runs the applet, Domino checks for execution rights of theperson or group that signed the applet. If an applet is signed by a person orgroup without the correct authorization, Domino alerts the user of theillegal 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 theexecution control list.

Setting security for applets in Web applicationsComplete these steps to set up secure access for applets that will access thefile system or Notes Java classes through a browser.

1. Use CORBA to write a Notes/IIOP applet that accesses the Notesclasses.

2. Import the Notes/IIOP applet in a page, form, or document, using thesame procedure as for any other applet.

3. When you click Locate to Include the related applet files, make sure toinclude 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 ableto use a supported browser to view these embedded CORBA applets on aDomino server. You do not need to set alternate HTML for the CORBAapplet to run. When you check the setting that specifies the applet as aCORBA applet, Domino automatically provides the HTML source code thatthe applet needs to make an IIOP connection back to the server.

Extending the AppletBase classAn applet intended for run-time access of lotus.notes.noi extendsAppletBase and puts its functional code in the methods notesAppletInit()and notesAppletStart(), as shown in the sample code below, and innotesAppletStop(). AppletBase is new with Notes Release 5.0 and thelotus.notes.noi package. You do not have to distinguish between local andremote access. AppletBase will make local calls if the applet is runningthrough 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 { // Can also do getSession(user, pwd) Session s = this.getSession(); if (s == null) { //we were not able to make theconnection, warn user ta.append(“Unable to create a session with theserver”); return; } String p = s.getPlatform(); ta.append(“Platform = ” + p); } catch(Exception e) { e.printStackTrace(); } }}


Saving applet dataVarious actions in a Notes document, form, or page, such as resizing orediting applet parameters, cause the applet to reinitialize to the state it wasin when you opened the document, form, or page. When the appletreinitializes, it loses data the user entered and its current state. There aretwo methods for saving applet data:

Externalization

The applet stores specific information that it needs in order to return tothe state it was in before it was reinitialized.

Serialization

The applet stores all information, for example, each variable and itscurrent value, each class, and all header information.

To maximize efficiency, it is recommended that you use externalization.

ExternalizationThere are three parameters available to direct Notes to save and reuseexternalized data:

ReadExternalData

Directly after reinitialization, the applet uses this parameter to loaddata previously saved.

ExternalData

Any time after reinitialization, the applet uses this parameter to loaddata previously saved.

WriteExternalData

After a Notes save event, the applet uses this parameter to save currentdata. The data is saved as an external object with an attachment in thedocument that references it. The attachment is hidden and cannot beseen by the user.

Usually you do not need to use both ReadExternalData and ExternalData.Use either one depending on when you want the applet to load data.

Generally, the values you assign to the parameters are the same.

1. Select the Java applet and choose Java Applet - Java Applet Parameters.

2. Click Applet Parameter in the Programmer’s pane.


3. If you want the applet to load data as soon as it has completedinitialization, click Add and set up the following parameter:

In the Parameter Name field, enter ReadExternalData and click OK.

In the Parameter value window, enter the value forReadExternalData. Its value is the name of a file that is attached tothe 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 afterinitialization, click Add and set up the following parameter:

In the Parameter Name field, enter ExternalData and click OK.

In the Parameter value window, enter the value for ExternalData. Itsvalue is the name of a file that is attached to the page, form, ordocument 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 Addand set up the following parameter:

In the Parameter Name field, enter SaveExternalData and click OK.

In the Parameter value window, enter the value forSaveExternalData. Its value is the name of a file that is attached tothe page, form, or document where the applet is stored. For example,

mydata

If the file attachment does not exist, Notes creates it and stores the datain it.

Example HTML code to set up parameters:

<PARAM NAME="readexternaldata" VALUE="mydata">

<PARAM NAME="writeexternaldata" VALUE="mydata">


SerializationThere are two parameters available to direct Notes to save and reuseserialized data:

Object

The applet uses this parameter, a standard HTML parameter, to load(using Java VM and VM) previously saved applet data in the serializedobject. Object must exist before the applet attempts to load it, or theoperation fails.

WriteObject

After a Notes save event, the applet uses this parameter, a Notesextension, to save the data. The data is saved as a serialized object in ahidden attachment to the document. The user cannot see theattachment.

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 ParameterName field and click OK:Object

4. In the Parameter value window, enter the value for Object. Its value isthe name of a file that contains the previously saved state informationfrom 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 ParameterName field, and click OK:WriteObject

6. In the Parameter value window, enter the value for WriteObject. Itsvalue is the name of the file that is attached to the page, form, ordocument where the applet is stored. For example, enter:mydata

Example of HTML code to set up parameters:

<PARAM NAME="object" VALUE="mydata">

<PARAM NAME="writeobject" VALUE="mydata">


DetailsAlthough you can set up an applet for both externalization andserialization, Notes cannot support both. An error is not reported, but oneapplet cannot do both.

In the Java applet itself, you must write methods to support the JavaExternalize interface. If the applet does not have these methods, you canstill run the applet. However, the data cannot be saved, even if you set upthe parameters.

If you save data, keep these points in mind:

If the applet is imported in a subform, the data from the subform hasprecedence over the data in the form. Therefore, modifying an applet ina subform modifies all of the forms that include that subform.

Data from an applet contained in a document takes precedence over thedata stored in a form or subform.

If you imported the applet in a document and you are saving data, the datafile will be copied if you export the applet. If you imported the applet in aform, the data file will not be copied if you export the applet from adocument you created with the form.

Tips and troubleshooting for Java appletsWhen the applet runs, the status bar displays messages such as “Loaded<applet-name>,” “Initialized <applet-name>,” and “Started<applet-name>.” If the applet does not run as expected, a dotted grayrectangle is displayed. The rectangle means the applet did not loadproperly. Review the sections below and use File - Tools - Show Java DebugConsole to examine the applet and determine the problem.

Troubleshooting an applet that is not runningIf the applet is linked to a Web site, check that your Web proxy isrunning. Get the name of your Web proxy from your Locationdocument. If you are running Windows, go to the DOS prompt and usethe ping command followed by the proxy name to determine if yourconnection is valid. If the ping command returns an error rather than areply, contact your system administrator for help restoring your Webproxy.

Check that you included all the necessary applet files. Choose JavaApplet - Refresh to add additional files to the applet. To make sure youhave all the files, select All for File Types and click Select All to includeeverything.


Check that you entered the correct name for the applet files. Java iscase-sensitive, so the file names must match exactly.

Make sure you correctly specify the parameters required by the applet.Choose File - Tools - Show Debug Java Console and view the messagesreported by the Java applet. Check for missing parameters and add inparameters that are required.

Accessing resource filesJava applets frequently use resource files such as images and audio files.There are three common ways that applets access these files:

By specifying a full URL for the file, for example,http://www.someplace.com/image.gif.

By using the applet class getDocumentBase method to construct a URLrelative to the location of the document in which the applet is found.

By using the applet class getCodeBase method to construct a URLrelative to the code base of the applet, that is, the location from whichthe applet’s files were loaded.

Depending on what method you use, Domino may not be able to locateresource files for the applet. The getCodeBase method is the most reliablemethod for specifying resource files. If you experience problems withapplets not finding resource files, modify your applet to use getCodeBase.Recompile the files and choose Java Applet - Refresh to replace these files inthe document.

Specifying a full URLIf your applet specifies a full URL to locate a resource file, for example,getImage(“http://www.someplace.com/images”, “image.gif”), the appletattempts to find the file at that URL. This usually works when runningapplets 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 theInternet.

Similarly, you can access images attached to Notes documents byconstructing 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 accessthe Domino server in order for an applet running in the Notes client to beable to access this file.


The drawbacks of specifying a full URL for an applet resource file are that itmay be slow to access this file through the Internet and not all Notes clientsare set up to directly access the Internet. Also, this course of action assumesthat the location of this file will not change. If these are not concerns, this isa reliable way to access resource files.

Using getDocumentBaseThe least reliable means of specifying resource files is the getDocumentBasemethod. The getDocumentBase method of specifying resource files returnsthe base URL (that is, the full document URL minus the document filename) of the document in which the applet is located. For example, if anapplet 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, forexample, getImage(getDocumentBase(), “image.gif”). Using the above URLas 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 referto a file; instead, it is a command for the Domino server to generate theHTML representing a document. If you use the getDocumentBase methodas a Domino URL, you get unexpected results. For example, suppose youlinked 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 thegetImage call returns:

http://www.someplace.com/database.nsf/MasterView/image.gif

The applet cannot find the file because the document ID is gone and theimage is an attachment to a document, requiring a $File qualifier as part ofits name.

Because the document’s ID has been removed (and since the image is in anattachment in the document and thus needs “$FILE” to qualify the filename), the requested image cannot be found by the applet.


Using getCodeBaseThe most reliable means of specifying a resource file for an applet is thegetCodeBase method. The getCodeBase method returns the base URL fromwhich the applet was loaded. The codebase for an applet can be specifiedby the CODEBASE attribute in the APPLET tag. When Domino generatesthe HTML for an applet which has been inserted into a Notes document, itgenerates a full URL for the CODEBASE attribute. For example, given theexample 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 filesSome applets include parameters that refer to resource files or to directoriescontaining resource files. For example, an applet may include a parameterspecifying 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 thecodebase, rather than to the document base.

If you are not building the applet yourself, for example, if you are linking toan applet on the Internet, or if you obtained a set of .class files without thesource code, you might need to edit a parameter value after inserting theapplet 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. Dominoconverts any occurrences of the $notes_codebase string in a parameter intothe codebase for the applet. The parameter value“$notes_codebase/images/image.gif” is therefore converted by Domino to:

http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE/images/image.gif

Since this effectively means that you are providing a full URL whenspecifying the parameter value, the getDocumentBase method in the appletis overridden, and the applet will be able to find the resource file.


Chapter 12Including OLE Objects in Applications

This chapter illustrates ways to design applications that use OLEtechnology to integrate data from other applications.

Designing applications using OLE

Using OLE (Object Linking and Embedding) and OLE-related tools lets youextend the capability of Designer. OLE technology lets you integrate datafrom other applications, such as spreadsheets, graphics tools, and otherdata sources, into your application.

For information on scripting OLE objects and using OLE custom controls,see the Programming Guide.

Note Some of the OLE-based technologies available in Domino areplatform-dependent. Windows offers the greatest range of options forsharing information and launching objects. Unless otherwise noted,activities covered in this chapter apply only to Windows.

Using OLE and OLE-related tools in Designer, you can:

Link and embed objects in forms

Using object linking and embedding (OLE), you can design a form thatdisplays the same object in every document created from that form.When you link an object, every document created from the form refersto the source of the link. When you embed an object, the object itselfappears on every document created from the form. Linking andembedding objects is supported for Notes applications only.

Launch objects automatically

Using object linking and embedding, you can design a form thatautomatically launches an embedded object or a new object createdusing any OLE-registered desktop application. The autolaunch canoccur when users create, edit, or read a document based on the form.Autolaunch helps create a smooth workflow involving multipleapplications. It also allows users who are familiar with other productsto work within those applications without leaving your Notesapplication. This autolaunch feature is not available for Webapplications.

325

Add custom controls to a form

If you use Notes with Windows NT or Windows 95/98 and have OLEcustom controls installed, you can create custom control objects indocuments or on forms. An OLE custom control, also known as OCX oras ActiveX, is a small, self-contained software module with its owndata. Lotus ComponentsTM, which are examples of controls, allow youto use other Lotus products, such as a Lotus spreadsheet or chart, whilecontinuing to work in a Notes database. For information on creatingand using the Lotus Components, see the online Help that comes withthe Lotus Components software or go to the Lotus Web site athttp://www.lotus.com.

Your organization may create OLE custom controls from variousmanufacturers and use the controls in Notes. Some OLE customcontrols may not provide online Help for their application.

Set up forms to exchange field information with other Notes documents

You can create forms in Designer that automatically share informationwith documents created in other OLE-registered applications. Then,when users modify the contents of a field in a Notes document, thechanges are automatically made to the corresponding fields in the otherapplication’s document. Data exchange can occur in both directions:users can edit fields in Notes or the other application, and themodifications are automatically exchanged. OLE-registeredapplications must support NotesFX in order to use field exchange inNotes. This feature is not available for Web applications.

Publish an action

This is the most powerful of the OLE-based tools because it is the mostflexible. You can automate complicated or repetitive tasks that involvemultiple operations across multiple applications. You design an actionusing formulas or scripts, and then publish it. The action appears on theAction menu in any Notes/FX 2.0-enabled application. This feature isnot available for Web applications.

Embed JavaBeans

JavaBeans are self-contained objects, similar to ActiveX controls, thatcan be used with other beans to create applications. Like ActiveXcontrols, you can embed JavaBeans into Notes documents and rich textfields, forms, subforms, and pages, and then attach scripts and events tothem. You must install the Java Runtime Environment (JRE) before youcan embed JavaBeans in a Notes document or in a Designer form.


Linking and embedding objects in forms

Object linking and embedding (OLE) is a powerful design tool. When youlink or embed an object in a form, every document created from the formdisplays the object. Whether you link or embed an object depends on howthe form will be used.

Linking maintains the object in the source application and displays theobject in the host application, which in this case is the Notes form. Forexample, a form might contain a 1-2-3 spreadsheet that you updatefrequently. The advantage to linking is that you can maintain control overthe source. When you update the object in the source application, all links tothe object automatically update. The disadvantage to linking is that all usersmust have access to the file containing the object, as well as the applicationused to create it. In this example, the users need the spreadsheet file and1-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 theform. For example, if you embed a graphic in a form, users need acompatible version of the source application to view the graphic. Designeraccess is required to modify the graphic.

To link an object in a formTo link to an object, it must already exist in the source application.

1. Use a source application that supports object linking and embedding(OLE) to create an object.

2. Copy the object to the Clipboard.

3. Open the form in Designer, click where you want the object to appear,and select Edit - Paste Special.

4. Save and close the form.

To embed an object in a formYou can create an embedded object from within Designer.

1. Click where you want the object to appear on the form, and then selectCreate - Object. Designer lists the available applications that supportOLE. This list of applications appears in a list entitled Object type.

2. Choose an application. Designer will launch the application intoin-place edit by default if the application supports this; otherwise,Designer will open the application.

3. Create data in the application.

Chapter 12: Including OLE Objects in Applications 327

4. If you are using in-place edit, click outside the OLE application toreturn the focus to Designer. If Designer originally opened the application, exit the application.


For more information on creating objects, see Notes Client Help.

OLE and LotusScriptTo build on the power of OLE, use LotusScript to create or enhanceworkflow applications. You can use LotusScript to create, manage, andupdate objects within Notes documents.

For more information on using LotusScript with OLE objects, see theProgramming Guide.

Adding OLE custom controls to a formYou can add a custom control, such as a Lotus Component, to a form tomake the control available in documents created from the form. Afterinserting the control, you can edit properties that control its display.

To create an OLE custom control object1. In a rich text field or on a form, choose Create - Object.


Select “Create a new object.” In the Object type list, choose a customcontrol. The custom controls have starburst icons next to them.

Select “Create a new control.” In the Object type list, choose a customcontrol and click the Add control button.

3. Click OK.

Note Some custom controls do not display in the Create Object dialog box.You cannot use this method to insert these controls. Instead, use LotusScriptto insert them because these types of controls do not support a UI and areonly programmable.

To see online Help for Lotus Components1. In a rich text field or on a form, select a Lotus Component object.

2. Choose a command from the Help menu, or press F1.

To access an existing control, select it.

When a custom control is active, the Help menu is a combination ofDesigner (File and Applet) and the custom control. The control may includeone menu item for itself — for example, “Spreadsheet” for a spreadsheetcontrol — and Help. The control’s Help is substituted for Designer Help.


Use the Applet menu choice to:

Copy and cut the entire object. Use the Edit menu to copy and cutselected text in the object.

Access Notes properties for the control, including the name of thecontrol.

Access the control’s own properties.

Set the control’s mode.

Freeze and unfreeze the control’s events.

If a control is active when you embed it in a form, a list of events appears inthe Info List of the Programmer’s pane. You can attach scripts to theseevents.

For information on attaching scripts to a custom control, see theProgramming Guide.

Modifying a form to size an embedded objectIf an object’s server application supports OLE2 “in-place” editing, Designercan expand the object when you edit it.

1. With the form in Edit mode, click the object.

2. Choose Edit - Properties or select the dynamic menu presented for theOLE application. For example, clicking a Lotus 1-2-3 object adds themenu choice “Workbook.” Select Workbook, then Object Properties.

3. In the Properties box, choose “Size object to window.” When youchoose “Size object to window,” the following occurs:

When a user uses this form to create a document, the user mustdouble-click the object to display it in the full application window.

If the document contains information below the object, the user willnot be able to see that information.

4. Close the Properties box.



Modifying a form so that it sizes an OLE custom control or JavaBean1. Open the form and click the custom control.

2. Choose Applet - Object Properties.

3. Do one of the following in the Properties box:

Choose “Size object to window.”

Choose “Size object below field.”



When you use the form to create a document, the control expands, based onthe property you chose.

Note the following:

The property you choose takes effect after you save and close the formor document.

If you choose “Size object to window,” the following occurs:

When a user creates a document or opens an existing document inEdit mode, the custom control automatically expands to fill the entireapplication window.

If the document contains information below the custom control, theuser cannot view that information while the custom control isexpanded.

If you choose “Size object below field,” the following occurs:

When a user creates a document or opens an existing document inEdit mode, the custom control automatically expands to fill the areaof the Notes window below the layout region. If the document doesnot contain a layout region, the custom control expands to fill theentire application window.

If the document contains information below the layout region, theuser cannot see that information while the custom control isexpanded.

If the document contains two or more layout regions, the customcontrol expands below the first layout region. The user cannot see theother layout regions.


Modifying a form to run a custom control or JavaBean in Read mode1. 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.



When a user opens a document, the object automatically launches in Readmode. The user can change the object and print the changes, but cannotsave the changes without first putting the document into Edit mode.

Note This option is available only for custom controls and JavaBeans.Some custom controls and JavaBeans do not render anything for display inRead mode. With this setting, you can force the custom control or JavaBeanto display in Read mode.

Letting documents update objects created by formsYou can create an object or custom control in a form and let documentscreated with the form update the object or custom control. A user canchange the OLE object or custom control and save those changes with thedocument. The OLE object or custom control in the form does not overwritethe revised OLE object or custom control in the document.

1. Open the form and click the object or custom control.

2. Choose Edit - Properties.

3. In the Properties box, choose “Update object from document.”



Launching objects automaticallyYou can have a form automatically launch (autolaunch) an embeddedobject or a new object when a user creates a document or opens one forreading or editing. A new object is one that is blank until users add data.

The user can change the embedded object and add data to a new objectdirectly in the application that created the object. The Notes documentautomatically displays the changes. Note that autolaunch is not available inWeb applications.


When you design a form that autolaunches an embedded object, the objectmust be the first OLE object in the form. To autolaunch other objectsembedded in the form, you must write a script. Users can launch embeddedobjects 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 adocument, the object launches. If you don’t create the object in a rich textfield, when users create a document, Notes launches the first object thatappears in the form. When users subsequently open the document forreading or editing, the first object in the document launches.

The following are ways to launch OLE objects:

Launch an object automaticallyThe object can be a spreadsheet, a word-processing document, a graphicpresentation, a database, or a multimedia object. You can autolaunch objectscreated in any registered OLE application.

Launch a new object automaticallyA new object is blank until users add data. You can autolaunch a new objectin any registered OLE application.

Launch an object in-place or out-of-placeThe object launches in-place if it launches within the Notes document. Theobject launches out-of-place if it launches in the application that created it.

Define the conditions under which objects are launchedThe object launches only when it is created or when it is opened in Read orEdit mode.

Use the form open in a modal dialog box to create documentsThe object launches into a modal dialog box that the designer can customizeto allow specific actions users can take with the object.

Hide the Notes document You can hide the Notes document when the object is launched or when thelaunched object is closed.

Hide the original embedded object in documentsYou can hide the original embedded object and display only the mostrecent, updated version of the object in a document.


Designing a form that launches an object automatically1. Open the form containing the embedded object you want to launch

automatically.



4. Select “First OLE object” in the Auto Launch box.

5. (Optional) To create the object in a rich text field, do the following:

Position the insertion point where you want to create a field todisplay the object, and choose Create - Field.

Enter a name for the field.

Select Rich Text in the Type box.

Select Form in the “Properties for” drop-down list.

Click the Launch tab.

Select the name of the rich text field in the “Create object in field”box or choose “First Rich Text Field.”

Select “None” if you do not want to display a current representationof the object in documents.


Displaying the object in documents created using the formWhen the object is autolaunched, modified by the user, and saved, it isdisplayed in the document in the field you specify in the “Create object infield” box. You can specify “First Rich Text Field” to display the savedobject in the first rich text field in the document.

To display the current representation of an object in the document, store theform with the document. This causes updates to the object to replace theoriginal embedded object in the document. Storing the form with thedocument uses a large amount of disk space and processing time.

To store the form with the document, open the form, choose Design - FormProperties, click the Defaults tab, and select “Store form in document.”

Objects and full text searchFull text searches can include embedded objects and attachments. When afull text search finds a match in an embedded object or attachment, theobject or attachment opens, but the matching word or phrase does notappear highlighted.


Nested objectsIf the OLE server application is also a client application, an object in a Notesdocument may have other objects within it. In this case, when an object isupdated, the object in the Notes document reflects the changes even if theywere made in an other application.

When an object that contains other objects is autolaunched, only theapplication that created the object embedded in the Notes document islaunched.

Examples: Designing a form that launches an object automaticallyYou need a Spring product line database that sales representatives use tocreate custom presentations from a standard set of slides. Create a SalesPresentation form and embed a Freelance® Presentation file containing thestandard slide presentation. Specify the Freelance Presentation object toautolaunch only when a document containing it is created.

When you use the Sales Presentation form to create a document, FreelanceGraphics® launches and you save the object without modifying it. Then use the name “Standard Presentation” to save the Notes document. Younow have a document stored in the database and accessible by salesrepresentatives all over the world, containing standard slides for a salespresentation.

Sales representatives who want to modify the presentation use the SalesPresentation form to create a new document. The Freelance Graphics objectlaunches automatically, and the sales representatives can customize theslide presentation. They then save the object, and specify a new name whenthey save the Notes document containing it. Their custom version of theslide presentation is now in the database, where other sales representativescan access it.

Designing a form that launches a new object automatically1. Open the form.



4. Select the OLE server application in the Auto Launch box.

The list includes all registered OLE server applications on your harddrive.

5. Position the insertion point where you want to create the field that willdisplay the object, and choose Create - Field.

6. Enter a name for the field.


7. Select Rich Text in the Type box.

8. In the Form Properties box, click the Launch tab.

9. Select the name of the rich text field in the “Create object in field” box.


When a document autolaunches a new object, the application initiallydisplays an empty object. The user adds the appropriate data, and thencloses and saves the object. The new object is embedded in the rich text fieldyou specify in the “Create object in field” box. To display the object in thefirst rich text field in the document, you specify “First Rich Text Field.”

Then when a user reads or edits the document, the object in the first richtext field launches automatically. If the document was opened in edit mode,this allows the user to enter data or make changes.

Nested objectsIf the OLE server application is also a client application, an object in a Notesdocument may have other objects within it. In this case, when an object isupdated, the object in the Notes document reflects the changes even if theywere made in another application.

When an object that contains other objects is autolaunched, only theapplication that created the object embedded in the Notes document islaunched.

Launching an object in-place or out-of-placeBy default, objects are launched in-place, so that the object can be editedright in Notes. If the object does not support in-place editing, then the objectwill be launced out-of-place, so that focus shifts to the application used tocreate the object and Notes goes into the background.

Only applications that support OLE2 can launch in-place. Applications thatsupport OLE1 always launch out-of-place, regardless of the “Launch inplace” 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.



4. Select “Launch in place,” or deselect it to launch out-of-place.



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 usercreates a document. By default, existing objects autolaunch each time a userreads or edits a document containing an object.

1. Open the form containing the object.



4. Select Creating, Editing, and/or Reading in the “Launch when” box.


DetailsYou can control whether the object in the first rich text field in a formautolaunches when a document is created, edited, or opened. If the formyou’re designing autolaunches a new object, make sure the “Launch when”setting includes “Creating,” because this is the only event that launches anew object. After the user creates the document, the new object is savedwith the document. Other “Launch when” settings, such as “Reading” or“Editing,” take effect when a user subsequently opens the document.

If you set the form to “Automatically enable Edit mode” (on the FormDefaults tab of the Form Properties box), make sure the “Launch when”settings are compatible. For example, if you design the form so that theobject launches only when users open the document in Read mode and youset the document to enable Edit mode automatically, the document alwaysopens in Edit mode and the object never autolaunches.

Examples: Specifying the event that causes an object to autolaunchDesign 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 enteringfinancial information. Create a rich text field in the form, and specify thatthe field display the object. Also specify that the object autolaunch onlywhen a user uses the form to create a document.

When a user uses the form to create a document, the 1-2-3 objectautolaunches so the user enters the information in 1-2-3. The user closes andsaves the 1-2-3 object, and then closes and saves the new document. Whenpeople 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 thedocument in Edit mode and double-clicks the object to launch it.


Designing a form for documents that open as modal dialog boxesTo control what the user can see or do when creating, editing, or reading adocument, design a form to open as a dialog box.

1. Open the form.



4. Select “Present document as modal dialog.”


When users create or open a document that opens in a dialog box, theycannot access Notes menus. Instead, they have access to a small set ofactions that include:

Entering or modifying data

Launching the first embedded OLE object by clicking the Launchbutton on the dialog box

Choosing a command from the Action menu at the bottom of the dialogbox

As the designer, you can control the list of commands available on theAction menu.

For more information about showing form actions, see “AddingAutomation to Applications.”

Designing a form to hide the Notes documentTo allow users to move seamlessly from the Notes view level to anautolaunched application and back again, design a form to hide the Notesdocument. You can hide the Notes document when users create, read, oredit the document.

1. Open the form.



4. In the “Hide when” list, select an option. (Click the option again todeselect it.)



You can design a form to hide the Notes document during any of theseactivities:

Users create a document (Opening Create).

Users open a document to edit it (Opening Edit).

Users open a document to read it (Opening Read).

Users close a document after creating it (Closing Create). This option isavailable only if “Opening Create” is selected.

Users close a document after editing it (Closing Edit). This option isavailable only if “Opening Edit” is selected.

Users close a document after reading it (Closing Read). This option isavailable only if “Opening Read” is selected.

Mixing Hide/Show optionsYou can design a form that hides the Notes document in somecircumstances and shows it in others. Use this type of form when document creators, editors, and readers play different roles in maintaining the information in the Notes database.

Hide Notes documents when:

The main focus of the document is the object, and users don’t need tofill in anything else.

The form contains only one object.

Users aren’t familiar with Notes and want to work in a familiarapplication.

The Notes database is functioning solely as a container system for otherapplication files.

All users have access to and can launch the other application andalways work in that application.

Show Notes documents when:

Readers need to see more than the data object itself.

The form contains multiple objects.

Revising the data in the object is optional; therefore, you don’t need tolaunch every time the Notes document opens.

Users who create and edit documents need to fill in other fields on theform.

Some users have operating systems, such as OS/2, that don’t supportOLE objects, but they still need to read the information or edit otherfields in the Notes document.


ExamplesYou create a report-tracking database that allows users to use 1-2-3 to createand update their own expense reports. When users create or updateexpense reports, they don’t need to see the Notes document; instead, theywant to autolaunch the expense report object in 1-2-3.

To design a form that mirrors your users’ workflow, create an ExpenseReport form, embed a worksheet object in the form, and set the formproperties to automatically launch the worksheet. In the “Hide when” box,you select “Opening Create,” “Closing Create,” “Opening Edit,” and“Closing Edit.”

When users choose Create - Expense Report, Notes automatically starts1-2-3 and launches the embedded worksheet object. Users enter informationdirectly 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 worksheetobject embedded in the form updates, users are returned to the view levelin Notes. If users want to edit their expense reports, they open thedocument 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 Notesdocument or in the Notes view. The Notes database contains all of theexpense reports.

Hiding an embedded object in a documentYou embed an object in a form for autolaunch so that users can makemodifications to the object. You then specify a rich text field to display thelatest representation of the object. If you want to display only the latestversion — not the original version — of the object, you must design theform to hide the original embedded object. After the user makes changes tothe object and returns to the document, only the changed version appears inthe document.

1. Open the form containing the object you want to hide.

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.



Publishing actions

When you publish an action, you make it available on the Action menu inany open OLE server application. For example, you might automate adocument review process so that a Notes user opens a document thatautolaunches a Word Pro file. After editing the file, the user clicks the Sendto Next Reviewer menu choice in Word Pro, which routes the documentcontaining 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 ofwhat you can do with a flow of work and enhances your ability to controlthat flow. Teamed with autolaunching, publishing actions allows you tofocus or limit user-access to commands, thereby controlling the flow ofwork. By simplifying and automating multi-step tasks, you improve thesecurity of your system and reduce the chance of user error. Actions allowyou to integrate file creation and storage in other desktop products with thedocument sharing, storage, security, and management tools of Notes.

Actions can incorporate functions, @commands, and LotusScript. Notes alsosupplies a number of simple actions, such as Move to Folder, which allowyou to incorporate useful actions in your form design withoutprogramming in LotusScript.

For information on actions, see “Overview of Automation.”

When the action executesOn the Advanced tab of the Action Properties box, you can specify whathappens when an action runs. Select “Close OLE object and return toNotes” 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 focusto remain with the OLE object. This property is useful if users need tochoose more than one action before returning to Notes.

When designing actions, keep in mind the state of the application whenreturning to Notes. For example, if you use the autolaunch feature with anaction, decide whether you want users to return to Notes, whether youwant the Notes window hidden, whether users are in a document or a view,and whether the document has been saved or is new. Write documentationor field help in the form to provide guidance to users.


Bring document window to frontOn the Advanced tab of the Action Properties box, choose the property“Bring document window to front” if you want the focus to return to Noteswithout closing the OLE object. By shifting the focus back to Notes, youprovide the opportunity for user-input in Notes. When you use thisproperty, remember that the OLE object has not been saved, unless youexplicitly saved the object as part of the action. Therefore, you may have toprovide a way for users to return to the object to save it.

Note The “Bring document window to front” property applies only whenthe document window in Notes has not been hidden.

Steps in publishing an action1. 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.


6. Select “Publish Action with OLE object.”

7. Select a property that controls what happens after a user chooses anaction.

8. (Optional) Select “Bring document window to front” to change thedefault setting.


For information about creating an action, see “Adding Automation toApplications.”

If actions do not get published even after you select “Publish action withOLE object,” make sure Notes/FX 2.0 is enabled. Choose Design - FormProperties and click the Defaults tab. The “Disable Field Exchange” checkbox should not be checked.


ExamplesA Word Pro document needs to be routed for approval. The Notes formyou create has an embedded Word Pro document set to autolaunch whenedited and an action called Send to Next Reviewer. When a user opens theNotes document in Edit mode, the Word Pro document automaticallylaunches. When reviewing the Word Pro document, the user selects theSend to Next Reviewer action from the Action menu in Word Pro. Thisaction sends the Notes document to the next reviewer and closes the object.

To provide other routing options, you can add the actions Ready for NextReviewer, Return to Previous Reviewer, and Archive Document to theNotes form.

Exchanging data using Notes/FXNotes/FX is supported only for Notes applications. Using Notes/FX, youcan design forms so that field contents in an OLE server application fileautomatically appear in corresponding fields in a Notes document, andvice-versa. Depending on the type of field, you can update the contentsfrom Notes or from the other OLE application.

To exchange data, there must be a one-to-one correspondence between theshared fields. Both the OLE server application file and the Notes form mustcontain the same shared fields. A Notes/FX field can be:

One-way

Two-way

User-defined

One-way fields These fields provide information for exchange in only one direction.One-way fields supply information about a file — for example, file size andcreation date. These fields exist by default in the OLE server application;you create the corresponding fields in your Notes form.

For example, Word Pro documents have a field called SizeInK, whichcontains the size of the Word Pro document in kilobytes. To exchange thedata 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 theWord Pro field appear in the Notes field; however, changes made to theNotes field do not affect the Word Pro field.


Two-way fieldsThese 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 fieldsupdate. Fields defined as two-way exist by default in many OLE serverapplication files; therefore you create corresponding fields in your Notesform.

For example, the Document Description field in a Word Pro documentcorresponds to the Subject field in a Notes document. After you set up fieldexchange, changes to one field automatically appear in the other field. Thefields must have the same name.

User-defined fields These fields exchange data in two directions, but you must create thesepairs of fields, since they do not exist by default in the OLE serverapplication file. User-defined fields usually exchange working data, such astext or numbers. You create and name these fields in the OLE serverapplication file and in the Notes form.

For more information about fields in OLE server applications that exchangedata 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 aDesigner form must have a corresponding field with the same name in theother application file.

Note If you are using a form copied from a Designer template, fields mayalready be set up for field exchange.

Enabling field exchange1. Open the form and choose Design - Form Properties.


3. Make sure “Disable Field Exchange” is not checked.


Note You can disable Notes/FX 2.0 field exchange without removing theNotes/FX fields from the form by checking the “Disable Field Exchange”property.


Setting up field exchange1. Open the other application file.

2. Write down the name of each field you want to exchange and close theapplication.

3. In Designer, open the form you want to prepare for Notes/FX fieldexchange.

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


Examples: Exchanging dataThe following table lists one-way and two-way fields found in most Lotusapplications. 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 applicationembedded in Notes

Subject Text Description of the document

Categories Text (allowmulti-values)

Keywords that Notes uses to categorizedocuments

Exchanging data for an expense formYou create a form to file and distribute trip reports. The reports containdescriptions of the important business aspects of the trip, as well as the totalexpenses. 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 Notesdocument.


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 isa custom Notes/FX field, you need to tell 1-2-3 to use this range name forNotes/FX. Select File - Workbook Properties and then select the Notes/FXFields tab. Select the New Field button and then select the range nameTotal_Exp. Select OK twice. The row below the cell entitled Total_Exp willhold the actual data that is exchanged between Notes and 1-2-3. Save andclose this 1-2-3 Workbook.

In Designer, create a form called “Trip Report” and embed the recentlycreated 1-2-3 expense report. The Trip Report form contains text fields forentering 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 anumeric field named “Total_Exp” which corresponds with the name of thefield in the 1-2-3 expense report template.

When users use the form Trip Report to create reports, the total expensesare automatically inserted in the document.


Chapter 13Restricting Access to and Securing Parts of an Application

This chapter describes Designer features for limiting access to parts of anapplication. It does not provide a comprehensive description of Designersecurity features.

For more information on security, see Managing Domino Databases andAdministering the Domino System.

Security in an application

Designer offers a multi-layered approach to security. You can secure fields,sections, forms, views, databases, servers, and domains. Securing serversand controlling access to a domain is the responsibility of the serveradministrator. As a database designer, you can control who has access to anapplication you create, right down to the contents of a single field. You canalso control access to application-specific features, such as the databasedesign and agents that run on a database.

The features you use determine how secure your application is. Thedatabase access control list and encryption features provide true security.Creating form access lists and hiding design elements let you hinder accessbut are not true security features.

To restrict or limit access to parts of a database, use these features:

The database access control list (ACL) specifies who can or cannotaccess the database. For users who can access a database, access levelsand roles determine the specific actions they can perform — forexample, creating or deleting documents.

Note that, if the Web user is being authenticated with Basicauthentication (that is, name and password), the Advanced section ofthe ACL lets you specify a maximum access setting for Web users. Evenif you explicitly give Web users higher access, they never have anaccess level greater than what you specify as the “Maximum Internetname & password access.”

347

If the Web user is being authenticated using SSL Client certificates, thenthe “Maximum Internet name & password access” field does NOTapply to them. These users have the full access granted to them in theACL. In other words, if the access list says that they have “Manager”access, they truly have Manager access to the database and not theaccess specified in the “Maximum Internet name & password access”field.

The Secure Sockets Layer (SSL) is a security protocol that protects databy encrypting it as it passes between servers and Web clients. The SSLmust be set up at the server as well as set for a database.

Form access lists, in conjunction with the database ACL, control whocan read or edit all documents created from a form.

Document access fields (Readers and Authors fields), in conjunctionwith the database ACL, control who can read or modify specificdocuments.

Encryption allows you to secure information for Notes clients at thefield level. You can encrypt the contents of any field so that onlyreaders who have the encryption key can access the message or field.Database managers can encrypt an entire database. Encryption is notsupported in Web applications.

Electronic signatures confirm that documents or document sectionsmailed from one user to another are not tampered with before reachingtheir destination.

To restrict access to parts of the design, use these features:

Restrict who can create agents and where the agents can run. Mostusers can create private agents to run on local databases; some userscan also create shared agents that run on servers for use by other users.

Secure the design of a database to prevent users from changing designelements.

For information on restricting agents, see the topic Agents. For informationon securing a database using the access control list, see Managing DominoDatabases. For information on setting up the SSL, see Administering theDomino System.


Controlling access to a database during design

Every database has an access control list (ACL) that defines who has accessto the database and describes the activities they can perform. While you aredesigning the database, strictly limit access so that only you, otherdesigners, and the database manager have access to the database. When thedatabase is ready to be released, the database manager can adjust accesscontrol settings to provide general access to the application.

Keeping a database private during developmentIf the database you are developing is stored on a server, take these extraprecautions so users aren’t able to see the database until it is ready. Whenthe database is ready to be released, the database manager can adjust thesesettings to make the application public.

1. Select the database and choose File - Replication - Settings.

2. Click Other and select “Temporarily disable replication.”

3. Click OK.

4. Choose File - Database - Properties and click the Design tab.

5. Deselect “List in Database Catalog.”

6. Deselect “Show in ‘Open Database’ Dialog.”

For more information on access control, see “Controlling and monitoringaccess to databases” in Managing Domino Databases.

Giving designers access to a database1. Select the database and choose File - Database - Access Control.

Note that if the database is on a server and not local, you must alreadyhave manager access to the database.

2. Highlight your name in the People, Servers, Groups list.

3. Select Manager as the Access level, if it is not already selected.

You must do this locally; you cannot assign yourself manager access toa database on a server.

4. Select Person as the User Type.

5. Select all the Create and Delete options.

6. Highlight -Default- and select No Access as the Access level.

7. If there are other designers, click Add and select the location of theirnames from the drop-down list of Address Books (for example, yourPersonal Address Book and the Domino Directory).

Chapter 13: Restricting Access to and Securing Parts of an Application 349

8. Click the left column next to each designer’s name to select it, and clickAdd.

9. Click OK when you have added all the designers.

10. For each designer’s name in the People, Servers, Groups list, highlightthe name, select Designer as the Access level, and select all Create andDelete options.

11. To remove an entry, highlight the name and click Remove.

12. To change an entry’s access level, highlight the name and select a newaccess level.

13. Click OK.

To preview in the Web browser, you need to set up an Anonymous userwith Author access and make sure that create documents is selected.

For more information on restricting access using the ACL, see ”Controllingand monitoring access to databases“ in Managing Domino Databases.

Enforcing encrypted Web transactions using SSL

The Secure Sockets Layer (SSL) is a security protocol that protects data byencrypting it as it passes between servers and Web clients.

One option the server administrator may choose in setting up SSL at theserver is to enable the SSL port in the Server document of the DominoDirectory, create an SSL certificate, and distribute the certificate to Webusers. To protect transactions in individual databases — for example, indatabases used for commercial transactions — open the property box forthe database and select ”Web Access: Require SSL Connection.“ To openSSL-protected databases, Web users must include the SSL certificate in theirbrowser configuration.

Note that the server administrator actually has three options in allowingaccess over the SSL port:

Anonymous access over the SSL port - Web users can connect to theserver using the SSL port, however, the server allows anonymous users.

Name and password access: Web users connect to the server over theSSL port, and authenticate using name and password.

Access through client certificates: Web users have been issued an X509client certificate and connect to the server over the SSL port. They areauthenticated using this client certificate.


Depending on which of these types of access the server allows for the SSLport and what the database ACL allows, the user may access this databaseanonymously, may be authenticated with name and passwordauthentication, or may use a Client certificate.

For more information, see Administering the Domino System.

Restricting access to documents

Domino provides a layered security model that allows you great flexibilityfor controlling access to all or part of an application. The highest level ofsecurity is managed through the database access control list (ACL). UsingACL settings, you can carefully control who has access to an applicationand specify the type of access allowed. For example, one user might haveaccess to read, create, and edit documents in a database, while another canonly read documents.

You can restrict access to documents in the following ways:

Create a read access list for a view or folder that restricts who can seethe view or folder.

Create a write access list for a folder that restricts who can update thecontents of a folder.

Create a form access list to specify who can create new documentsusing that form. This setting also restricts who can read the documentscreated from the form.

Create Readers and Authors fields to limit access to specific documentscreated from a form.

Restricting who can see a view or folder If you want some users and not others to see a view or folder, you cancreate a read access list. Users who are excluded from the access list will nolonger see the view or folder on the View menu. A view or folder readaccess list is not a true security measure. Users can create private views orfolders that display the documents shown in your restricted view, unlessthe documents are otherwise protected. For greater security, use a readaccess list for a form.

You can add users to the read access list for a view or folder as long as theyalready have at least Reader access in the database access control list.


To create a read access list1. Open the view or folder.

2. Choose Design - View Properties or Design - Folder Properties.

3. Click the Security tab.

4. Deselect ”All readers and above.“

5. Click each user, group, server, or access role you want to include.

A checkmark appears next to each selected name.

6. Click the Person icon to add person or group names from a PersonalAddress Book or from the Domino Directory.

7. To remove a name from the list, click the name again to remove thecheckmark.

8. Check ”Available to Public Access Users“ if you want this view orfolder available to users with public access read or write privileges inthe access control list for this database.

9. Save the view or folder.

Do not create a read access list for the default view of a database.

Servers that need to replicate a database need access to views that areread-restricted so that view design changes can replicate.

Example: Restricting access to a viewTo improve his Technical Services department’s reputation, Rajeev Jain hasdesigned a ”Tech Services Review“ form, which is included in thecompany’s custom Mail template. Each quarter, Rajeev sends acompany-wide memo asking people to complete a Tech Services Reviewform 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 tothis view. He defines a read access list for the Tech Service Performanceview. Then, since there is no group in the Domino Directory for the peoplehe wants to include in the access list, Rajeev defines an access role in thedatabase ACL called [TS Managers], and adds that role to the view’s readaccess list. The access role is stored within the Service Request Trackingdatabase; it does not get added to the Domino Directory.

For more information on restricting access to a database, see ”Controllingand monitoring access to databases“ in Managing Domino Databases.


Restricting who can update the contents of a folderTo allow some users and not others to update the contents of a folder, createa write access list for the folder. You can add users to the a write access listfor a folder as long as they already have at least Author access in thedatabase access control list. Users specified in the write access list for thefolder can move and copy documents into the folder and can removedocuments from the folder. They cannot update the document’s themselves.

1. Select a database.

2. In the Design pane, click Folders.

3. Double-click the view or folder in the Work pane.

4. Choose Design - Folder Properties.


6. In the ”Contents can be updated by:“ section, deselect ”All Authors andabove.“

7. Click each user, group, server, or access role you want to include. Acheck mark appears next to each selected name.

8. Click the Person icon to add person or group names from a PersonalAddress Book or from the Domino Directory.

9. To remove a name from the list, click the name again to remove thecheck mark

10. Save the folder.

Restricting access to all documents created from a formTo restrict access to all documents created from a form, you can create aform access list. Create this list at the Security tab of the Form Propertiesbox. The form access list lets you restrict:

Who can access the form in order to create documents using the form. If users are not on this list, then when they select the Create menu, theywill not see this form on the list. This is one way to shorten the list.

Who can read documents created from this form. If you choose thisrestriction, a ”read access list“ that restricts who can read the documentis created.


Restricting access in this way is not a true security measure because a usermight create a copy of the form and remove the restriction, but it is a usefultool for limiting easy access. For example, you might use a form access listto restrict access to documents containing personnel information. Inaddition to restricting who can read or edit documents created from a form,you might want to restrict actions users can take with documents. Forexample, you might want to allow users to view a company phone list, butprevent them from printing, copying, or forwarding the list.

Restricting access to a formUsing a form access list, you restrict access to all or part of a form by settingsecurity parameters that work with the database ACL. The database ACLpredominates — only users with access to the database have access to formswithin a database. Form security is a lower level of access control than is thedatabase access control list. You can create form access lists that specifywho can create, edit, print, forward, or copy information. Limiting who cancreate documents from a form also shortens the Create menu by removingrestricted forms from the menu.

Authorized readersThe following people can read a document that has restricted read access:

Users assigned read access in the form access list

Users listed in the form’s Readers field

Readers field names are added to a document’s read access list.

Users listed in the form’s Authors field

Creating fields for Readers and Authors is described later in this chapter.

Replicating restricted documentsAdding names to a read access list or to a Readers field limits access to theusers, groups, and servers named in that list or field. Servers that need toreplicate this database must be included in the list or field to have readaccess. Otherwise, documents that are read-restricted won’t replicate.

Restricting who can create or read all documents from a form1. Open the form.



4. Deselect ”All authors and above“ in the ”Who can create documentswith 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 fordocuments created with this form“ section.

7. Click each user, group, server, and access role you want to include.

8. (Optional) Check ”Disable printing/forwarding/copying to clipboard“if you want to disable these features.

9. (Optional) Check ”Available to Public Access users“ if you wantdocuments in this view or folder available to users with public accessread or write privileges in the access control list for this database.

Preventing printing, forwarding, and copying of documentsYou can discourage users from printing, forwarding, or copying documentscreated with a form. This feature helps to prevent accidental distribution ofconfidential information, but it is not a true security feature since users cancircumvent it by using screen capture programs.

1. Open the form.



4. Click ”Disable printing/forwarding/copying to clipboard.“

Using a Readers field to restrict access to specific documentsTo limit access to specific documents created from a form, include aReaders field on the form. A Readers field explicitly lists the users who canread documents created from the form. For example, to limit access to anemployee’s personnel file to members of the Human Resources department,the employee, and the employee’s manager, list those people in a Readersfield. Without Reader access to a document, a user cannot see the documentin a view.

If a form has an access list, names from the Readers field are added to theform access list. Otherwise, the Readers field controls access to documentscreated from the form.

Entries in a Readers field cannot give a user more access than what isspecified in the database access control list (ACL); they can only furtherrestrict access. Users who have been assigned No Access to a database cannever read a document, even if you list them in a Readers field. On theother hand, users with Editor access or above in the ACL can be restrictedfrom reading documents if they aren’t included in a Readers field.


Any users who have Editor (or higher) access to the database can edit adocument if:

They are listed in the form’s read access list, Readers field, or Authorsfield.

The form has no read access list restrictions, no Readers field, and noAuthors field.

For information on updating Readers fields, see ”Updating Reader andAuthor fields“ in Managing Domino Databases.

Using an Authors field to restrict who can edit specific documentsAn Authors field works in conjunction with Author access in the databaseaccess control list (ACL). If you assign a user Author access in the ACL, theuser can read documents in the database but cannot edit even their owndocuments. Listing users in an Authors field expands access rights byallowing the listed users to edit documents they create.

Entries in an Authors field cannot override the database access control list;they can only refine it. Users who have been assigned No Access to adatabase can never edit a document, even if you list them in an Authorsfield. Users who already have Editor (or higher) access to the database arenot affected by an Authors field. Authors fields affect only users who haveAuthor access to the database.

Note that the name you enter in the Authors field must be the completehierarchical name — for example, John Smith/ACME/West — not theshortened common name form.

For information on updating Authors fields, see ”Updating Reader andAuthor fields“ in Managing Domino Databases.

Restricting who can read or edit specific documents

To restrict who can read documents, add a Readers field to a form. To allowusers with Author access to edit the documents they create, add an Authorsfield to a form.

Note This type of access control only takes effect when the database is on aserver. If you develop a database locally, you can’t test this feature untilyou copy the database to a server.


1. Open the form.

2. Create a field, or click an existing field. Then choose Design - FieldProperties.

3. At the Field Info tab, select Readers or Authors as the type.

Select Editable to allow authors and editors to modify the list (Besure to include yourself in the default value formulas which youcreate in the Script area of the Programmer’s pane — so there is atleast one value).

Select Computed to write a formula that computes the reader orauthor names.

4. To create editable or computed field values, click the Programmer’spane, select a formula type, and write the formula; click the green checkmark to save the formula.

Note Include server names in the formula if the database willreplicate.

5. On the Control tab, select a Choices option other than None to generatea list of readers or authors from which users can select.

6. (Optional) On the Field Info tab, select ”Allow multi-values“ to allowmore than one name to be stored in the field.

7. (Optional) On the Control tab, select ”Allow values not in list“ to letusers enter additional names. This property is applicable only toAddress and Access Control List choices.


To ensure that the database will replicate correctly, include the names ofreplicating servers in the reader names list.

Choices for generating a list of readers or authorsUnless ”None“ is selected as the lookup option for a Readers or Authorsfield, users either press CTRL+ENTER or, if specified for the field, the entryhelper button to see a list of possible entries. If the Readers field is locatedinside a layout region, leave ”None“ selected; other lookup options do notapply.

On the Control tab of the Field Properties box, choose one of these optionsfor generating a readers or authors list:

None

If you select None, you rely on a formula or on authors to create the listof names. Select ”Look up names as each character is entered“ to speedup typing in editable fields. Designer fills in the first name that matchesthe characters the user types.


Use Address dialog for choices

This option displays the Names dialog box so users can select namesfrom a Personal Address Book or from the Domino Directory. Select”Look up names as each character is entered“ to help users fill in aname quickly and Designer looks up a match.

Use access control list for choices

This option brings up a list of people, servers, groups, and roles in theaccess control list.

Use View dialog for choices

This option brings up a dialog box containing entries from a column ina Designer database view. Select the database to look up, select a view,and select a column number.

Writing formulas for Readers and Authors fieldsWhen you write a formula for a Readers or Authors field, enclose usernames and group names in quotation marks.

”Marketing"

Select “Allow multi-values” for a field that stores a text list with multiplenames. Concatenate the names in the formula with a colon.

"Mary Sen":"Marketing":"Joyce O'Connor"

Role names that qualify access levels are surrounded by quotation marksand square brackets.

"[Scheduling Committee]"

Examples: Restricting who can read or edit specific documentsAdding a Readers field to a formYou want to be sure that employees can read only their own EmployeeInformation documents. Create a computed-when-composed Readers fieldnamed AuthorizedReader that uses this formula:

@UserName

To add additional authorized readers, create a read access list in theDocument Properties box for individual documents.


Adding an Authors field to a formYou want to use an Authors field on a Slide Show form to let the Productiongroup edit documents, but you also want to save and display the originalauthor’s name for each document, so the creator’s name is easily foundeven after the document is edited. You create two fields.

To display the creator’s name, create a computed-when-composed fieldcalled CreatedBy with the formula:

@Name([CN];@UserName)

To allow the Production group to edit Slide Show documents, create acomputed Authors field and use the formula:

"Production"

Allowing authors to add other namesYou want to let authors and editors customize the Authors list. Create aneditable Authors field that uses “View access control list dialog” to presentchoices, and select “Allow multi-values” for the field.

Tracking who edits a document

If a document contains an Authors field, Designer automatically stores thenames of the users who have edited that document in an internal fieldcalled $UpdatedBy. Servers involved in replication are not considerededitors, so they’re not tracked in this list.

To display the contents of the $UpdatedBy field, users can click and holdthe Authors field in a document they’re reading. Designer displays apop-up showing the names of everyone who has modified the document,including people who did so through agents. Adding pop-up text to thefield label helps users understand the list.

Designer displays hierarchical user names in abbreviated form:

Betty Powers/R&D/WorkSavers/US

If “Anonymous form” was selected for the form, documents do not containan $UpdatedBy field, but have an $Anonymous field with a value of “1”instead.


Restricting authors from changing fields in existing documents

You can prevent users with Author access in the database ACL from editinga field in existing documents. This restriction doesn’t apply to newdocuments.

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” andclick the check mark.

Creating pages, forms, outlines, views, and agents for public accessA public access list, like Readers and Authors fields, works with thedatabase access control list to control users’ access to specific designelements. Users with No Access or Depositor access in the ACL cannotaccess the design elements of a database. To give them the ability to viewspecific pages, documents, forms, outlines, views, and folders make thedesign element available to pubic access users. Users who have at leastReader access in the database ACL will see in the element’s properties boxthat the element has been designated as available for public access.

To create public documents, you must create a public access form with a$PublicAccess field and create a public folder or view to display thedocuments. Public documents are useful for calendar applications whereone user might delegate to another user the ability to read or createappointments on his or her behalf.

Creating agents enabled for public access gives users with No Access orDepositor the ability to view and use any manually run agents.

For more information on the ACL, see “Controlling and monitoring accessto databases” in Managing Domino Databases.

To create a page or form for public access1. Open the page or form.

2. Choose Design - <design element> Properties.


4. Select “Available to Public Access Users.”

5. On a form, create a field.

6. In the Name field, enter $PublicAccess.

7. In the Type field, select Text and Computed when composed.


8. In the Programmer’s pane at the bottom of the form, enter 1 as thedefault value for the field. Click the green check mark to accept thevalue.

9. To hide this field from users, select the Hide When tab and specifyhide-when conditions.

To create a view for public access1. Open the view.

2. Choose Design - View Properties.


4. Check “Available to public access users” if you want documents in thisview or folder available to users with public access read or writeprivileges in the access control list for this database.

To create an outline for public access1. Open the outline

2. Choose Design - Outline Properties.

3. Check “Available to public access users.”

To create an agent for Public Access1. Open the agent in Designer.

2. Click Options.

3. Select “Available to Public Access Users.”

Encrypting documents in Notes applicationsEncrypted documents contain one or more encrypted fields that are linkedto keys that encrypt the field data. For example, documents created with theNotes mail template are encrypted. The encryption process occursautomatically (through the form design) or manually by authors andeditors. Associating multiple encryption keys with a documentautomatically encrypts all encryptable fields with the same keys. Youcannot link a particular key to a particular field.

Encryption keys can be secret — that is, keys that you must send to users inorder for them to decrypt a field — or public — that is, keys that are alreadyassociated with a user’s Person document in the Domino Directory. Publickeys are used for encrypting mail documents.

Caution Web users can see encrypted fields. Do not rely on encryptedfields as a way to restrict access for Web users.


Reading encrypted informationUsers can read encrypted information if they have the correct encryptionkey in their Notes User ID or in their Person document in the DominoDirectory. Users without the correct encryption key can read unencryptedparts of a document, but encrypted fields appear blank.

When multiple keys are associated with a form or document, users needonly one of the specified keys to read encrypted information.

Editing and saving encrypted informationUsers who don’t have the correct encryption key in their Notes User IDcan’t edit encrypted documents. They can create new documents but mustsave them unencrypted by removing the encryption key from theDocument Properties box.

When multiple secret keys are associated with a form or document, usersneed all of the specified keys to edit and save encrypted information withthe original keys. If they don’t have all the necessary keys, they can stillencrypt documents with the keys they have by changing the encryption keylist in the Document Properties box.

Removing or changing encryption keys for a documentAuthors can remove encryption or change the associated keys from theirown documents (if they are allowed to edit their documents and they haveall associated encryption keys). Editors can remove encryption from andchange the keys associated with any document.

Data security for encrypted informationIf a user copies the database, the data remains encrypted — even if thedatabase is copied at the operating system level. The encrypted data is alsosafe from access by API programs.

Caution Full text searches that include the option “Index encrypted fields”will show encrypted data to any users who have access to the database.Also, if a user who has the power to decrypt documents creates the index,that user can read the full text index as an ASCII text file at the server.


Encrypting documentsTo use encryption in a document, you create fields that are capable of beingencrypted and then you or users encrypt the fields with one or moreencryption keys. To encrypt a document, perform some or all of these steps:

1. (Optional) Create an encryption key to use secret encryption. To do this,see the topic “Creating a secret encryption key.”

2. Enable encryption for a field.

A document cannot be encrypted unless it contains at least one fieldthat has been designated as encryptable.

3. Choose a method for assigning encryption keys to documents:

Encrypt all documents automatically

Create a field that generates a list of encryption keys

Allow authors to encrypt documents with their own encryption keys

A document can be encrypted when it is first saved, or it can be encryptedwhen saved after a subsequent editing session.

For more information on encryption, see “Encrypting databases anddistributing encryption keys” in Managing Domino Databases.

Example: how decrypting a document worksMary encrypts a document using the encryption key in her User ID toencrypt field data.

David opens the encrypted document to read it. Designer compares thelist of encryption keys used to encrypt the document with theencryption keys in David’s User ID.

If David doesn’t have any of the same keys, the encrypted fields appearto be blank.

If David has some of the keys used to encrypt the document, thatencryption key is used to decrypt the document.

Examples: Making fields for encrypting documentsFor an Employee Information database, the Salary History form has a createaccess list that allows only members of the Financials group to create SalaryHistory documents. The database managers want to allow only four peoplein the Financials group to see salary information and to edit Salary Historydocuments.

The database manager can create an encryption key and distribute it to theselect group or identify the four people and encrypt the information usingtheir public encryption keys.


In the first instance, the database manager creates an encryption key calledSalary and sends it to the four people in the Financials group, and to thedatabase designer. The database designer enables encryption for theCurrentSalary field and associates the Salary encryption key with the form.This allows the four people in the Financials group who have the Salaryencryption key to create, read, and edit encrypted salary historydocuments, including the data in the CurrentSalary field.

In the second case, the manager provides the names of the four people tothe database designer, who chooses their names from the Public Encryptionkey list associated with the CurrentSalary field. Then the people fromnamed in the list can create, read, and edit encrypted salary historydocuments, including the data in the CurrentSalary field.

Users who don’t have the Salary encryption key and are not in the PublicKey list can read everything in the salary history documents, except thedata in the CurrentSalary field, but they can’t edit and save existingencrypted documents.

Creating a secret encryption keyDatabase managers create and distribute secret encryption keys to userswho need to decrypt documents that are encrypted with the secret keys.None of this is necessary if you use public keys for encryption.

1. Choose File - Tools - User ID.

2. Click the Encryption icon.

3. Click New.

4. Enter a name that describes the purpose of the new key.

5. Click ”North American only“ if the key is to be used in the U.S. andCanada; click International if the key is to be used in additionalcountries.

6. (Optional) Write a comment to explain the key’s use — for example, thedatabases to use it with, the people who have copies of it, and so on.

7. Click OK, then click Done.

For more information on encryption, see ”Encrypting databases anddistributing encryption keys” in Managing Domino Databases.

Encryption keys and private keys in Notes IDsEvery Notes User ID has a public key and private key that encrypt mail,fields, and documents and verify a writer’s identity. A User ID may alsocontain additional encryption keys that encrypt and decrypt documents.


When you design a form, you can use the public key for encryption orcreate a new encryption key. If you create a new encryption key, Designerautomatically stores it in your User ID. If someone sends you an encryptionkey, Designer stores the new key in your User ID, along with any otherkeys.

North American and International encryption keysDesigner uses two schemes for creating encryption keys. One scheme is forNorth American (United States and Canada) use only, and the other is foruse anywhere in the world. If you are designing a database for users in theUnited States and Canada and in other countries, create domestic andinternational versions of the encryption key.

If a document is encrypted with a North American encryption key, peopleusing Designer outside of the United States and Canada cannot decrypt thedocument because they can’t add a North American encryption key to theirinternational IDs. Because of legal restrictions, you cannot mail anencryption key with the North American encryption scheme outside theUnited States and Canada.

When American and Canadian users receive keys encrypted with theinternational scheme, they cannot change the key to the North Americanencryption scheme.

Enabling encryption for a fieldYou can enable encryption of a field whenever the document containing thefield is saved. Forms can contain more than one encryption-enabled field.

1. Open the form.

2. Create a field or click an existing field. Then choose Design - FieldProperties. The field can be any data type.


4. Select “Security options: Enable encryption for this field.”

Encrypting documents automaticallyYou can encrypt all encryptable fields automatically whenever someonesaves a new document composed with a form.

1. Open the form.



4. The “Default encryption keys” list shows all secret encryption keys inyour ID. Click the ones you want to add to the form as defaults.



To encrypt all documents created with a form, you enable encryption forone or more of the form’s fields (in the Field Properties box) and assign oneor more existing encryption keys to the form (in the Form Properties box). Ifyou use secret rather than public encryption keys, the database manager isin charge of distributing the encryption keys to all users who need them.

Whenever someone saves a new document composed with that form, all theencryptable fields in that document are encrypted using the key(s) youassigned, unless the author or editor changes the encryption keys associatedwith the document or disables encryption.

Documents created before you add the encryption keys remainunencrypted; however, you can manually encrypt them.

For more information on encryption, see “Encrypting databases anddistributing encryption keys” in Managing Domino Databases.

Creating a field that generates a list of secret encryption keysIf you are using secret encryption keys rather than public encryption keys toencrypt documents, maintain a list of the keys you create. To provide aconvenient list of frequently used encryption keys, create a specialSecretEncryptionKeys field. To create this special field, the form mustalready have fields enabled for encryption.

1. Open the form.

2. Create a field named SecretEncryptionKey. Define it as a text or listchoice field that is editable or computed.

3. For a list choice field, click the Control tab and select ”Enter choices(one per line).“ Write each entry, using a keyword and a synonym thatdescribes the encryption key — for example, Encrypt |ConfidentialKey. Use a null value for the ”Don’t encrypt“ option.

4. Click the Programmer’s pane and choose Formula in the Script area.

5. For a computed field, add a formula that returns the name of theencryption key to use; for an editable field, add a default value formula.

6. (Optional) Click the Advanced tab. Select ”Security options: Enableencryption for this field“ so unauthorized users cannot see the names ofencryption keys used in the formulas and keywords.


Users must have a copy of the encryption key so that they can savedocuments. The database manager is in charge of distributing secretencryption keys to all users who need them.


If the SecretEncryptionKeys field is empty (null), the document is notencrypted.

For more information on encryption, see ”Encrypting databases anddistributing encryption keys” in Managing Domino Databases.

Examples: Creating a field that generates a list of encryption keysEditable choice list field that lists one keyThis example gives users two choices. If the user selects “Encrypt,” thedocument is encrypted with the ConfidentialKey encryption key. If the userselects “Don’t encrypt” (represented by a null value “”), the document isnot encrypted.

Encrypt | ConfidentialKey

Don't encrypt | ""

Editable choice list field that lists multiple keysA choice list formula lets users choose the encryption key that isappropriate for the document.

Encrypt for Financials group | FinancialsKey

Encrypt for Managers group | ManagersKey

Encrypt for Human Resources group | HRKey

Don't encrypt | ""

Editable text fieldYou can create a SecretEncryptionKeys field that is an editable text fieldwith a default value formula that designates a commonly used key. Userscan remove the value to skip encryption or change the value to use anotherkey.

"ConfidentialKey"

Computed text fieldThis formula encrypts documents with the ConfidentialKey encryption keyif the Status field contains the word Confidential:

@If(Status="Confidential";"ConfidentialKey";"");

Allowing the author to choose the encryption keyIf you don’t have access to the encryption key or you want authors tochoose from the encryption keys they possess, enable encryption for thefields, but do not associate any encryption keys with the form.

Then when users save a document created with the form, they choosewhether to encrypt the document when saving it (in the DocumentProperties box) and choose which encryption key to use.


Restricting who can edit a section

In workflow applications, use sections to restrict who can edit or sign partsof 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 listThe edit access list for a section cannot override the database access controllist; it can only refine it. A user must already have at least Editor access tothe database in order to edit a document. Privilege names cannot be used inthe edit access list.

If you use custom roles to refine standard access levels, it is often helpful tocreate a section that corresponds to each access role. You can reveal the roleat the top of the section with the RoleName field that is tracking it. If youhave document buttons relevant to particular roles, place them next to eachrole’s section.

Using a computed field to define section editorsTo define a list of section editors, write a formula that populates the list ofallowed editors, either by including the current users name, by using@DbColumn to retrieve a list of names, using the value of an approver field,or using a group name or role from the access control list. Use acomputed-when-composed section to create a permanent list of editorswhen a document is created.

You can use only formulas that result in a text list containing one or morenames; these names are added to the section’s edit access list. Enclose thenames in quotation marks and concatenate them with a colon ( : ).

“Mary Sen”:“Marketing Group”

Access role names must include their square brackets and be enclosed inquotation marks:

“[Scheduling Committee]”

For information on using @DbColumn, see the Programming Guide.


Allowing the author to name section editorsTo let authors decide who can edit fields in a section, make the sectioneditable.

As a convenience to authors, write a default value formula to create aninitial list of editors for the section; anyone editing the section can thenupdate that list. If there are multiple authors, be sure to select “Allowmulti-values” for the field.

An editable section allows each document’s author to create a customizedlist of editors by double-clicking the section title when the document is inEdit mode or choosing Section - Define Editors. Any users alreadyauthorized to edit the fields within the section are displayed, and the authorcan add other editors to the list.

Using an access-controlled section on multiple forms.To use an access-controlled section on more than one form, place the sectionon a subform and include the subform in the forms.

An access-controlled section can be used in several forms by placing it on asubform.

Restricting who can access a section of a document

To create an access-controlled section1. Highlight the text, fields, and other design elements on a form that

make up the section.

2. Choose Create - Section - Controlled Access.

3. (Optional) In the Section Properties box, edit the section title.

4. (Optional) Enter a Section Field Name.

5. (Optional) Choose a border style and border color for the section.

You can insert fields and other design elements into the section aftercreating it. To append design elements to the bottom of the section, youmust recreate the section.

To name the editors for an access-controlled section1. 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 tospecify the section editors.


5. Select one of the Computed types to use a formula to define the sectioneditors.

6. (Optional for an editable field; Required for a computed field) In theProperties box, write a formula to define who can edit the field andclick the green check mark.

To collapse an access-controlled section1. Click the section marker and choose Section - Section Properties.

2. Click the Expand/Collapse tab and select options for showing thesection expanded or collapsed, depending on whether a document isbeing previewed, printed, or opened.

3. On the same tab, click the “For Editors” drop-down list and select “ForNon-editors.” A list of options appears for displaying the section tousers who can read but not edit the section.

4. Select “Hide title when expanded” if users don’t need to see the sectiontitle when the fields are displayed.


Examples: Restricting access to a sectionComputing an editors list from the access control listThe status section of a Business Card Request form has an access-controlledsection whose formula allows only administrators (an access role in theaccess control list) to change the status of a request. The formula for thecomputed field is:

"[Business Card Administrators]"

Allowing the author to name section editorsAn editable section of a Status Report form has an access-controlled sectionwhose default value formula always allows the author to edit the statusreport.

"@UserName"

The author can choose Section - Define Editors to name additional editorsfor a particular status report.


Attaching electronic signatures to documents and sections in Notes applications

For extra security, you can have Designer attach electronic signatures todocuments. Electronic signatures assure a reader that the writer’s identity isgenuine and that information has not changed since the writer mailed orsaved the document.

Note Signatures are valid only in Notes applications; they are notsupported on the Web.

To design a form whose documents can be signed, you create at least onefield 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 formsthat contain access-controlled sections.

You can enable signing of one or more fields on a form. If the field is in anaccess-controlled section, the signature applies only to the section and isgenerated when the document is saved. If the field is not in anaccess-controlled section, the signature is generated only when thedocument is mailed.

To generate multiple signatures on a form, create multiple sign-enabledfields, placed in separate access-controlled sections.

Attaching signatures to documentsTo attach a signature to a document during mailing:

The form must contain a SendTo field or, as an alternative, you cancreate a LotusScript program that uses the Send method of theNotesDocument class with a recipient’s argument.

The form must have at least one sign-enabled field. To sign-enable afield, assign the property “Sign if mailed or saved in section” in theControl tab of the Field Properties box.

The form enables mailing by using one of the following: a SendDocument form action, the form property “On Close: Present mail senddialog,” a MailOptions field with the value 1, an @MailSend formula, ora LotusScript program that uses the Send method of theNotesDocument or NotesUIDocument class.

The signing occurs during mailing in one of the following ways: thesender chooses “Sign” in the Mail Send dialog box, the form contains afield named Sign with the value 1, the form uses @MailSend with the[Sign] flag, or the form uses a LotusScript program with theSignOnSend property set to TRUE.


Attaching signatures to access-controlled sectionsTo attach a signature to a document when it is saved:

The form must contain an access-controlled section.

The access-controlled section must have at least one sign-enabled field.To sign-enable a form, assign the property “Sign if mailed or saved insection” is selected in the Control tab of the Field Properties box.

How Designer stores and verifies electronic signatures in Notes applications

Designer combines the data in a sign-enabled field with the private keyfrom the sender’s User ID to create a unique electronic signature. Designerstores the signature, along with the public key and the list of certificatesfrom the sender’s ID, in the document.

Note Signatures are valid only in Notes applications; they are notsupported on the Web.

Storing signatures in documentsDesigner stores signatures in mailed documents with the document.

If a user with Editor access in the database ACL changes a field in adocument, Notes replaces the existing signature with the signature of theeditor when the document is mailed. Notes cannot save more than onemail-time signature for a document.

If the document contains several sign-enabled fields, Designer uses datafrom each sign-enabled field to generate a signature. After mailing, achange in any field causes verification to fail when the recipient opens thedocument.

Storing signatures in sectionsFor documents with one sign-enabled, access-controlled section,Designer stores the signature with the section.

If a user with Editor access in the database ACL changes a sign-enabledsection, Designer replaces the existing signature with the editor’ssignature when the document is resaved.

If there are several sign-enabled fields in the section, Designer uses datafrom each sign-enabled field in the section to generate a signature. Aftersaving, a change to a field in the document causes verification to failwhen a reader opens the document.


For documents with several sign-enabled, access-controlled sections,Designer stores signatures within each section, so it is possible tomaintain 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 newersignature when resaving the document. Designer preserves the existingsignatures for sections for which the user has no access.

If there are several sign-enabled fields within a section, data from allthe sign-enabled fields in that section is used to generate a signature. Achange in any fields in the document after saving causes verification tofail when a reader opens the document.

Example: Verifying signatures1. 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 aunique signature. Designer also stores Mary’s public key andcertificates 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, Designerchecks the signature against the data to see if it matches.

4. Notes checks the certificates that came from Mary’s ID against David’sID to see if they share a common certifier or cross-certificate in the ID.

5. One of the following occurs:

If the signature and data are verified, Notes displays a messageindicating who signed it.

If the data has been modified, Notes displays a message indicatingthat the document has been changed or corrupted since Mary savedit. David should not assume that the content of the document is whatMary created.

If the signature can’t be verified or David and Mary don’t share acommon certificate, Notes displays a message that the signature can’tbe verified. David should not assume that Mary created thedocument.

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


Chapter 14Completing an Application and Managing Design Changes

This chapter describes how to document an application and how to test itbefore deployment. Because applications often require redesign, thischapter also describes how to make, control, and distribute design changesto applications that are already in use.

Completing an application

As you prepare to deploy an application, consider these finishing touches:

Creating an icon for the application.

Creating database help using the standard “About this Database” and“Using this Database” pages, or with a designated home page thatdescribes the application or site.

You may also want to:

Provide context-sensitive help for an application

Provide customized SmartIcons sets for a Notes application, to giveusers one-click buttons for frequent tasks

Then, before handing over the application to the database manager:

Test the design

Make a master design copy to manage future design changes

For more information on putting a database into production, see ManagingDomino Databases.

Creating a database icon for a Notes applicationA database icon helps users identify the database quickly on theirBookmark pane. An icon visually represents the purpose of the database.For example, a problem-reporting database for a software developmentgroup might display an insect icon to represent the “bugs” that usersreport. A discussion database where users ask questions about newproducts could include an icon with a question mark.

375

Creating a database iconYou can create a database icon by copying an icon from another databaseand pasting it in, by pasting a bitmap from a graphics application, or bycreating an icon in Designer.

To paste an icon into a database1. 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-inchsquare (32 x 32 pixels). You cannot resize it in Designer, and Designertruncates larger bitmaps.

2. Copy the bitmap to the Clipboard.

3. In Designer, open the database in which you want to paste the icon.

4. In the Design pane, click Resources - Other.

5. Double-click Icon to start the Icon editor.

6. Click Paste.

7. While still in the icon editor, you can make changes to the icon.

To create a new iconYou must have a mouse to create a new icon.



3. Double-click Icon.

4. Click a color and click a square to fill it with the chosen color.

5. Continue filling in blocks until the icon is complete.

6. Click OK to save the icon.

Note Icon changes do not replicate and are not affected by replace orrefresh design procedures. To distribute icon changes, copy the icon to eachdatabase. The icon design will refresh or replace if you disable “Prohibitdesign refresh or replace to modify” on the Design tab of the DesignDocument Properties box (To get this Properties box, select Icon in theWork pane and then select File - Document Properties).


Providing online help for an application

Including help with your application improves the chances that users willunderstand how to use it without asking for individual help from you or aco-worker. Database help can be integrated throughout the application sothat users have information as they need it.

Use these tools and techniques to document an application:

“About This Database” and “Using This Database” documents describethe database purpose. You can also create a page that provides this typeof information.

The document preview pane helps users scan through documentsquickly to get a sense of what’s in the database.

Database launch settings allow you to display the most useful startingpoint for users. This might be the “About This Database” page or itmight be the home page for the application.

Context-sensitive help in applications lets you write application-specifichelp that users access with a Help button or the F1 key in a Notesapplication or with a Help button in a Web application.

Field help describes the purpose and use of individual fields.

A help view organizes and displays help documents.

A separate Help database can be set to stay on top of other windows inyour application while users work.

Creating About and Using documents for a databaseEvery database should include an About This Database document and aUsing This Database document to explain the database to users.

The About This Database documentUse an About This Database document to describe the purpose of adatabase. You can specify that the About document opens automaticallywhen a user opens the database. To display this document, choose Help -About This Database.

The About document should include:

The purpose of the database.

The intended audience.

The name and telephone number of the database manager.

Chapter 14: Completing an Application and Managing Design Changes 377

The date the database was implemented.

Guidelines for its use.

Network requirements if users must be connected to the network toperform certain tasks — for example, if the application uses lookupsthat require a network connection.

The About document can contain rich text, so you can also use document, view, and database links, buttons, attachments, graphics, ormultimedia files.

The Using This Database documentCreate a Using This Database document to provide users with instructionson using various forms, views, and navigators in the database. To displaythis document, users choose Help - Using This Database.

The Using document, like the About document, can contain rich text, so youcan also add document or database links, buttons, attachments, graphics, ormultimedia files.

A Using This Database document should include:

A quick overview of the application.

The purpose of each view and its organizations.

The purpose of each form and how to fill it out.

The purpose of each agent, when to run it, and the anticipated results.

The overall work process being automated if the application automatesworkflow, including what happens at each stage. When users fill outdocuments, they should understand what happens after the documentsare saved, and what other users are expected to do.

To create an About or Using document1. In Designer, open the database you’re designing.


3. Double-click “About Database Document” or “Using DatabaseDocument.”

4. Write or edit the information.

You can also create links, buttons, hotspots, and attachments. You canapply text styles, as you would for any Notes form.

5. Save the document.


To automatically display the About This Database document1. Choose File - Database - Properties and click the Launch tab.

2. Do any of the following:

Select “On Database Open: Open ‘About database’ document” toalways open the About document first.

Select “Show About database document if modified” if you edit theAbout document and want to show it to users again.

Select “Show ‘About database’ document” when database is openedfor first time.

Select “On Web Open: Open About database document.”

You can use the About document as a springboard to a file in anotherdatabase or another product’s file. To do so, use the Database PropertiesLaunch options for “Launch first attachment in About database document”or “Launch first doclink in About database document.”

To view the About or Using documentsDo one of the following:

Choose File - Database - Open, highlight a database title, and selectAbout. This displays the About document.

Open a database on the Bookmark pane and choose Help - About ThisDatabase or Using This Database.

Creating context-sensitive help for an applicationIn addition to writing help documents or pages for an application, you canmake the documents or pages context-sensitive so that users can open themby pressing a help key — such as F1 — or by clicking a help button. You canassociate 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 whatevercontext-sensitive Help already exists for that element. This feature is notintended for context-sensitive help on dialog boxes or menu items.

To create context-sensitive help for a Notes application, you write a formulafor the onHelpRequest event for a page, form, subform, view, or folder. Inthe formula, you can use the formula language command@Command([OpenHelpDocument]) to specify a help document to openwhen the user request Help while that element is active. You can also use@Command([OpenPage]) to open a page instead of a document.

The onHelpRequest event is not available when serving an application overa Web server, but you can create a button for an element and program thebutton using a formula with @Command([OpenHelpDocument]) or


@Command([OpenPage]). A user clicks the Help button to see theassociated help document or page.

Because the onHelpRequest event accepts a formula, you can use theformula language in other ways to provide help. For example, you can usean @If formula with @IsDocBeingEdited to provide different help for a formdepending on whether a document is being read or edited, or depending onother conditions specific to your application. You can present a dialog boxto allow users to select among several help documents or pages. You canplace help text directly onto a form or page, set the text with a hide-whenformula, and use a formula on the onHelpRequest event to reveal the text(by changing the value of a document field) when a user requests help.

Tip To open documents in response to help requests, there must be a viewcontaining those documents sorted by a key field that you can use asparameters 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 Programming Guide.

Writing help for fieldsField help is optional, but it can help users fill out documents withoutassistance. A field label that appears next to the field describes the field’sgeneral purpose. Write field help to tell users what to enter in an editablefield or how to use the field. When a user selects a field that has help, theone-line help-text prompt appears at the bottom of the window.

If you cannot fit all the information into a help description or if the fieldisn’t editable, but you want to explain its use, use a pop-up annotation tothe field label to place help information directly on the form.

Tips for writing help for fieldsStart the help description with “Required:” if the user must fill in the field.

You can use 70 characters, including letters, numbers, spaces, andpunctuation. If your application will be translated to another language, useno more than 55 characters to allow the translators a few extra characters.

To write field help1. Open the form or subform in Designer.

2. Double-click the field.

3. In the Field Properties box, click the Advanced tab.

4. Write a help description.

5. Close and save the form or subform.


To write pop-up text for a field1. Open the form in Designer.

2. Highlight the field label — that is, static text that the user sees, not therectangular field definition.


4. In the Hotspot Properties box, write the pop-up text and click the greencheck mark.

5. Close and save the form or subform.

Examples For a text field named Supervisor:

Enter the name of the person to whom you report.

For a keywords field that presents check boxes:

Select as many options as apply.

For a required Subject field:

Required: You must add a brief description.

Creating and displaying more detailed application helpIn a complex application, an About This Database document and a UsingThis Database document might not provide enough documentation. Toprovide detailed documentation for an application, design a help form aspart of the database and display documents created with that form in a helpview. The following steps describe one way to achieve this.

To create a help form1. Create a new form called “help” and create fields for help content.

2. Click the Programmer’s pane and select “Define” and the name of theform you’re designing.

3. Select “Event: Window Title” and enter “Help” as the window title textin the formula window below.


5. Choose Create - Help to write, save, and close 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 documentsfrom your application using @Command(OpenHelpDocument). To open


documents from a Help database in a window that users can set to stay ontop of other windows as they work, choose File - Database - Properties -Design for your database. Then, turn on “List in Database Catalog” andenter the category “NotesHelp.”

Specifying the Web site home page in the Server document

To make a design element the site home page, edit the Home URL field inthe Server document or a Virtual Server document and specify a URL thatincludes the design element.

If you set an “About This Database document,” a navigator, a page, oranother 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 selectedin the “On Web Open” launch setting:

/ourhome.nsf

To open a navigator automatically, include the navigator name in the URL.The syntax is:

/databasename.nsf/navigatorname

This URL opens the Main Navigator in the Our Home database:

/ourhome.nsf/Main+Navigator

To open a view automatically, include the view name in the Home URL.The syntax is:

/databasename.nsf/viewname

This URL launches the Contents view of the Our Home database:

/ourhome.nsf/Contents


Restricting design changes

Once an application is complete and available, you decide how to protectthe design from changes. An application can have a totally open design,where users can update forms and views and pass along design changes.An application can have a totally closed design, where users use theapplication “as is” and have no access to design elements.

Designer lets you control the entire design of a database, as well asindividual design elements. You can restrict changes by not allowingchanges to overwrite one or all design elements, or you can hide one or alldesign elements from users.

In almost every case, you start by making a master design copy of theapplication.

For additional information, see the topic, Hiding the design of anapplication.

Checking the application design before rollout

After you complete the design, test the application and correct problemsbefore you release it.

Check the design of forms

Check the design of fields

Check the design of views

Distribute the application for a final review

Pilot-test the application

Make design changes before rollout

Request application sign-off

For more information on putting a database into production, see ManagingDomino Databases.


Checking form design

For each form, create two or three documents and enter a variety ofinformation into the fields. Then use this checklist to verify that the form isworking as intended.

Is there a default form for the database?

If not, double-click the form that should be the default and chooseDesign - Form Properties. Click the Form Info tab and select “Defaultdatabase form.”

Do all forms appear correctly on the Create menu? Are the appropriatekeyboard shortcuts used? Do the forms appear in the correct order?

If not, check the names and the “Include in Menu” properties for the forms.

Do the window titles for forms display appropriately under differentconditions?

If not, edit the window title formula. To display the window title whena form is printed, click the Printing tab in the Form Properties box andadd &W to the formula for the header or footer.

Check cross-platform compatibility: Are all fonts used in this formavailable (or approximated) on all platforms? Does all text displaylegibly? Did you use platform-specific terms where appropriate?

Make your application layout as generic as possible to suit all platforms.

Are related fields — for example, Name and Address fields — groupedtogether on the form?

If not, move the fields and their related static text to a more suitable position.

Do forms that are longer than one page have page numbers?

If not, click the Printing tab in the Form Properties box and add &P tothe formula for the header or footer.

Do the forms include Names fields where appropriate for trackingdocument authors and editors?

If not, add a Names field to the form.


Has a read-access list been defined for the form?

If one is needed, define a read access list by assigning names to a Readaccess control list on the Security tab of the Form Properties box.

Has a create access list been defined for the form?

If one is needed, define a create access list by assigning names to a Compose access control list on the Security tab in the Form Properties box.

Checking field design

Are fields (including keywords fields) showing the correct informationwhen first displayed?

If not, check the default value formula.

Does every editable field have a help description?

If not, add help descriptions for those fields. Ensure that fielddescriptions are consistently worded — for example, all are fullsentences or all express commands — and that ending punctuation —for example, periods — is consistent for each.

Can users enter information in editable fields?

If not, check the field definition. You may have selected the Computedoption when defining the field.

Are editable fields formatted correctly once the document is saved?

If not, check the input translation formula and the format for the field.

Are editable fields accepting invalid data or not accepting valid data?

If so, check the input validation formula.

Are computed fields computing correctly? Are they returning values ofthe appropriate data type?

If not, check the field formula. The formula may need to include somedata type conversion such as @TextToNumber.

Do inherited fields inherit their data correctly?

If not, check the field’s default value formula.

Do required fields have input validation formulas that display anappropriate message when the user tries to save the document withoutfilling in the fields?

If not, create the input validation formulas and include an explanatorymessage for the user.


In time-date fields, is the time displaying correctly?

If not, make sure you selected the appropriate time zone option in theField Properties box.

Are fields aligned properly with a variety of window sizes and ondifferent monitors?

If not, check the tab settings for the form.

Are encrypted fields accessible to users who have the encryption keyand inaccessible to all other users?

Make sure that only authorized users have the encryption key. Ifunauthorized users have the encryption key, change the encryption keyand redistribute it only to authorized users.

Checking view design

Once the database is complete, make sure the design is working. For testingpurposes create a view that uses @SELECTALL to select all documents.

Follow these guidelines to check view design.

Is there a default view for the database?

If not, double-click the view that should be the default and chooseDesign - View Properties. Click the Options tab and select “Defaultview when database is first opened.”

Is there a view that is displayed by date?

If not, add a view that sorts documents by date, so users can viewdocuments in chronological order.

Do all views appear correctly on the View menu? Are the appropriatekeyboard shortcuts used? Do the views appear in the correct order?

If not, check the names and the “Show in View Menu” selection in theView Properties box.

Is the information in the view easy to read?

If the view appears cluttered or the columns are too close together, resetthe column width and justification.

Are all the documents that should be in the view displayed, or are toomany documents displayed?

If the view is not displaying the correct documents, check the viewselection formula.


Are response documents indented?

If not and you want to indent responses, select “Show responsedocuments in a hierarchy” on the Options tab of the View Propertiesbox and create a column for responses.

Do response documents correspond to the correct main documents?

If not, check the view selection formula; also be sure that theresponses-only column is placed directly to the left of the column thatdisplays the main document information.

If the view uses categories, do the categories appear correctly?

If not, create a sorted, categorized column and use the name of theappropriate keywords field as its formula.

If the form uses a formula, do selected documents use the correct form?

If not, check the form formula.

Check cross-platform compatibility. Are all fonts used in this viewavailable (or approximated) on all platforms? Are column widthssufficient for all platforms? Did you use platform-specific terms where appropriate?

Make the application layout as generic as possible to suit all platforms.

If needed, does the view have a read access list?

To create a read access list, select the Security tab in the View Properties box.

Checking columnsIs the information in each column correct?

If not, check the formulas in the column definitions.

Is the column returning values of the appropriate data type?

If not, check the field formula. Columns display only simple text;therefore, you may need to use @TEXT in the formula to display valuesfrom numbers or time fields.

Is each column displaying all the information that is contained in it?

If not, you may need to adjust the column width and/or the font usedto display the column.

If you are using a date format in a column, have you accommodated4-digit years so that you avoid problems with the year 2000 and beyond.


Are the contents of columns aligned properly?

For example, numbers should be right-justified; text should beleft-justified or centered. Check the justification for each column.

Are documents in the right order?

If not, make sure that you sort on the correct columns, and that youchose the correct sort order (ascending or descending).

Are documents supposed to be numbered?

If so, create a new view that has a column in the left-most position thatsorts in ascending order and uses @DocNumber for its formula.

Making a design copy of a completed application

Before delivering the database to the database manager for general release,make a local template copy as the design. You can make future designchanges 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 extensionreserved for templates.

5. Select “Database design only” in the Copy section of the dialog box.

6. Deselect Access Control List.

7. (Optional) Click Encryption to encrypt the database and protect itscontents from being accessed at the operating system level. Then click OK.

8. Choose File - Database - Access Control to define an appropriateaccess control list for the template.

DetailsIf you specify a directory in addition to a file name, the new database isplaced in the directory you name as a subdirectory of the Notes Datadirectory. You specify a location for the Data directory during installation.If the directory doesn’t exist, Notes creates it for you.


The following access levels are recommended for the access control list of atemplate 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 databaseshould have

[Default] No Access — or whatever the actual databaseshould have

[LocalDomainServers] Manager — or whatever the actual databaseshould have

[OtherDomainServers] No Access — or whatever the actual databaseshould have

The items within the square brackets are needed only if the template isgoing to be used for creating new databases. The brackets are required forthese entries.

For more information about rolling out an application, see ManagingDomino Databases.

Pilot testing an applicationOnce your application has been reviewed, pilot test it with a few users.Make sure that the application works correctly and that all instructions areclear. Because the application users have a different point of view, theyoften uncover problems missed during the review cycle.

Only the people specifically assigned to pilot test the application shouldhave access to it. The default access should be - No Access. Then you canassign specific access levels and privileges to make sure that certain userscan access only what they should. Make sure you retain Manager access, soyou can make changes to the access control list during the test period andsolicit comments from the testers.


To pilot test an application1. Choose File - Database - New Copy to make a local backup copy of

your application. Use this backup copy if you need to backtrack fromchanges made during the pilot test.

2. Write an About This Database document to explain that the applicationis in the testing phase. Give users your name, e-mail address, andphone number, so they can contact you with questions, comments, and suggestions.

3. Add a Comment form to make it easy for testers to give you feedback.Include the comment form in at least one view. (Make sure that thecomment form is marked in the form design to be included on theCreate menu, or that a button or action is available to the user tocompose the form.)

4. Choose File - Database - Access Control to add testers to the accesscontrol list. Be sure to retain Manager access for yourself.

5. Ask your Notes administrator for write access to a server for the pilottest. Tell the administrator which users need access to that serverduring the pilot test.

6. Choose File - Database - New Copy to copy the application to theserver. Test the application on a single server. Do not create replicas yet.

7. If the database will involve replication later on, either to mobile laptopsor between servers, confirm that the replication formulas are workingand that servers can handle the volume of replication. For example, anannual review system places a demand on the server during the reviewwriting time, but not at other times.

If users will be replicating, then the pilot needs to confirm thatreplication instructions are appropriate for the levels of user expertise.While the initial part of the pilot test may be limited to a single server, ifthe intended implementation involves multiple servers, then the pilotneeds to address some of these issues as well. See Managing DominoDatabases for additional help on replication.

8. Keep track of questions that people ask about the function or use of thedatabase. Their questions may include the Using This Databasedocument or to the design of the database.

For more information on copying a new database to a server, see ManagingDomino Databases.


Renaming a database

If you want to change the title of a database as it appears in the Bookmarkbar, you can edit the title.


2. Choose File - Database - Properties.

3. Enter a new database title.

A database name or title is not the same as the database file name. The filename associated with a database is permanent. The only way to change thefile name is to make a copy or a replica of the database and give the newdatabase a different file name.

Renaming design elements1. Open a database in Designer.

2. In the Design pane, click the type of design element you’re working on.

3. Double-click the name of the design element in the Work pane.

4. Choose Design - <design element name> Properties to open the Propertiesbox for the design element.

5. Edit the name of the design element.

6. Close and save the design element.

Design synopsis

The Design Synopsis dialog box lets you generate a detailed report on aparticular database. Design Synopsis lets you:

Gather information on a database

Select the design elements you want in your report

Filter the contents of the report so that you do not automatically get alengthy report

Choose to have the report appear on the screen or have it written to aspecified database


To create a design synopsis1. Open the database for which you want a report.

2. Choose File - Database - Design Synopsis or select Synopsis in theDesign pane. The Design Synopsis dialog box appears with thefollowing tabs:

Design Elements

Database Information

Content

Output

3. Click the Design Elements tab:

Select design elements one at a time from the list box. If you wantevery element of every design to appear, select All from the list box.

Choose the specific elements that appear for each of the designelements. For example, if you selected Forms in the list box, all the forms in the database are listed. Select the ones you want in your report.

The Add button lets you add specific elements one at a time to yourreport. The Add All button adds all the elements of a particulardesign element (for example, all the forms). Your selections appearon the right. If you want to add every element of every designelement, choose All from the design list box and then click the AddAll button.

4. Click the Database Information tab. Then, check the appropriate boxesto include information in your report on the following topics:

General information — gives information such as the database title,location, and categories.

Space usage — calculates information such as the file size, number ofdocuments, and space used by the database.

Replication — gives information on the replication settings for thedatabase.

Access list — generates a list of users, groups, and servers in theACL and specifies assigned access levels and access roles for each.


5. Click the Content tab. Then do the following:

Check the details you want on each design element. For example, forForms, you can check Form Alias and Last Modification. Thosedetails appear for each selected form in the database.

Check the appropriate boxes so that your report will includeinformation on subcomponents (such as formulas), LotusScript code,Java code, HTML code, or JavaScript code.

6. Click the Output tab. Then do the following:

Choose to have blank lines or page breaks as report separators.

Check the Write Output to Database box if you want to write thereport to a database. If you check this box, a new dialog box appearsletting 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 generatedreport 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 displaywhen users open an existing document. Other changes, such as adding anew field, do not display in existing documents until you update thedocuments by manually editing and resaving them or by running an agent.If the database replicates, redesign the form on only one database and letthe changes replicate to other replicas.

Form changes that don’t require updates to existing documentsAs long as the form doesn’t have the “Store form in documents” propertyset, the following changes display automatically in existing documents.When users open a document, they see the changed format.

Changing a computed field formula

Changing static text on the form

Changing pop-ups

Changing text properties and formats

Changing form actions and buttons

Changing graphics

Changing the form name (if you leave the original name as a synonymto the right of the | symbol)


Form changes that require updates to existing documentsAdding a new field

Changing the field data type

Changing a field name

Deleting a field

Changing the form name (if you don’t leave the original name as asynonym)

Changing the form type — for example, from Main to Response

Changing a form that has the property “Store form in document”

Checking field values in a documentOpen the Document Properties box to see if a document contains aparticular field or field value, or to troubleshoot a field that is notcalculating its value correctly. A null value (“”) indicates that the field isempty.

A document always contains fields you design as well as fields Dominoautomatically generates. Most fields generated by Domino start with $. Thefollowing Domino-generated fields are useful fields to know about:

$File — shows an entry for each attachment in the document.

$Links — shows an entry for each link in the document.

$Readers — lists authorized readers if the document contains a readaccess list.

$Revisions — lists the date and time of each editing session since thefirst time the document was saved.

$Title, $Info, $WindowTitle, $Body, and $Actions — are associated witha form that is stored in the document.

$UpdatedBy — lists the document authors and editors. Anonymousforms don’t have this field.

Form — indicates the name of the form used to create the document orthe name of the form most recently used to save the document. Use theform in views to select documents created with the form.

PostedDate — indicates that a document has been mailed and showsthe 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 changesTo update multiple documents affected by form changes, use an agent. Todo so, it is best to create unshared agents and run them manually.

Editing and resaving documentsTo save the step of editing and resaving documents manually, create anagent that uses the formula:

@Command([ToolsRefreshAllDocs])

Adding a fieldIf you create a new field, create an agent that inserts the new field intoexisting documents using the formula:

FIELD New field name := value ;

where New field name is the name of the field and value is the value youwant the field in these documents to have. The value can be the field defaultvalue; a formula that calculates the value; or a null value (“”) that insertsthe field into the documents, but doesn’t give them any initial value.

Removing field data from all documentsIf you delete a field, existing documents continue to store the obsolete fieldand its values. This unnecessary storage can affect disk space. To removethe 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 sizeof the database.


Renaming a fieldIf you rename a field, existing documents continue to refer to the old fieldname. To update documents to refer to the new name, create an agent thatuses 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 theoriginal name for the field.

Reassigning documents to another formIf users attempt to open documents created with a deleted form, they see amessage indicating that the form cannot be found. To prevent users fromseeing this message, use these agent options to reassign existing documentsto another form. These options appear when you click on Agents in theDesign pane and then double-click an agent listed in the Work pane:

1. Under “Which document(s) should it act on,” select “All documents indatabase” and click Add Search.

2. Select “By Form Used,” select the name of the obsolete form, and click OK.

3. 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 documentsshould use.

Removing the stored form from documentsIn designing mail-enabled applications in which users need to see adocument and don’t have the original form stored in their mail databases,select the form property “Store form in documents.” This form property ispermanently attached to all documents created with the form. To removethe stored form, remove all internal fields connected with the form bycreating an agent that uses the formula:

SELECT $TITLE= "Old form name" ;

FIELD $TITLE:=@DeleteField;

FIELD $INFO:=@DeleteField;

FIELD $WINDOWTITLE:=@DeleteField;

FIELD $BODY:=@DeleteField;


FIELD $ACTIONS:=@DeleteField;

FIELD FORM:= "New form name" ;

This formula removes all internal fields attached to the documents whereOld form name is the name of the form used to create the documents. Thelast line creates a FORM field where New form name is the form that willdisplay the documents in the future.

After you run the agent, compact the database to reduce the actual file sizeof the database.

Templates

A template is a skeleton that contains design elements, but no documents.When you use a template to create a database, the database receives thedesign elements from the template. You can use the Designer templates asis or customize them. Or, you can create a template by creating a databasewith the .NTF file extension and the “Database is a template” property. Thisproperty enables the master template to distribute design changesautomatically to databases created from it. Databases that inherit theirdesigns from master templates receive the latest changes through a nightlyserver task.

If, for some reason, you do not want to automatically inherit designs via thenightly server task, you have two options: (1) do not put the template on aserver that runs the nightly update task or (2) do not set the “Database is atemplate” property. You can then distribute changes to the database designby using the Replace Design command, specifying the server where thetemplate is located and selecting the template. Make sure to set the databaseproperties so that the database does not automatically inherit the design viathe nightly server task.

Converting a database to a templateOpen the database you want to be a template and choose File - Database -Properties.


2. Select “Database is a template.”

3. Enter a template name (with no spaces in the name) and click the greencheck mark to confirm it.

4. (Optional) Select “List as advanced template in ‘New Database’ dialog”to hide the template unless users select “Show all templates” in theNew Database dialog box.


You can use letters, numbers, and underscores in the name. Choose aconcise, descriptive name that is easy to remember and type. Choose aname that indicates the application type or design elements represented inthe template. For example, StdR5Disc represents a standard Notes templatecontaining the design for a Discussion (R5) database.

The master template name, the title, and the categories assigned to thedatabase cannot add up to more than 99 characters.

Creating templates

Using a template, you can establish design standards for use throughoutyour company. In large companies, a central development group usuallydesigns and manages templates to provide consistent designs and speed updistribution of new databases. Use a template to standardize similar typesof applications — for example, all discussion databases — or to storeindividual design elements, such as fields, forms, views, folders, navigators,and agents that you can use in a variety of applications.

To customize a Designer template, use File - Database - New Copy to copythe original template and inherit the original design. Give it a different filename in the Copy Database dialog box to prevent future releases fromwriting over your customized template.

Here’s a list of changes you might make when you customize a Designer template:

Leave the original Designer template properties alone so that existingdatabases that inherit their design will continue to be synchronized tothe template.

Change the newly copied template file name in the Copy Databasedialog box (File - Database - New Copy) to a name that indicates itsintended use.

Change the newly copied template name (File - Database -Properties) toa new name, indicative of the new template purpose.

If existing databases that inherited the original Designer templatedesign need to inherit the design from the newly created template, editthe database properties of those databases to reflect the name of thenewly copied template.


Advantages of standardizing with templatesAnyone can quickly and easily create a new database

Users need to know only one command: File - Database - New. Theynever have to modify the design and don’t need to know anythingabout database design.

Developers and experienced users can save design time

Forms, views, and agents copied from a template require no additionaldesign work or updates. Using a predesigned form or view thatcontains complex formulas or a large keywords list reduces the chanceof design errors and requires less testing time before database rollout.

Databases appear consistent to users

View, forms, and fields associated with a template use the same namesin all databases. This allows users to apply their knowledge of onedatabase to many databases.

Note The template does not usually control the database icon, the AboutThis Database document, and the Using This Database document. If youwant an icon, About document, or Using document to inherit all designchanges, go into Designer, choose Resources- Other, select the icon ordocument, and make change in the Properties box so that changes areinherited from the template. The default is not inherited. You can alsochange these design elements by manually copying and pasting theredesigned elements into databases linked to the template.

In addition, do not create private agents or folders in templates; theirchanges can’t be distributed automatically. If a private agent or folder existsin a template, you receive error messages when the design isrefreshed/replaced. In the case of a shared/private-on-first-use folder: ifthe folder in the template has been opened or tested, a private folder existsand that folder generates errors when you try to refresh a design.

Examples: Creating templates

A customized discussion templateSuppose you need to add a Confidentiality field to all discussion databases,so that authors can mark specific documents as “Confidential — Forinternal use only.” All databases that base their design on the Discussiontemplate will inherit this field.

Add the field directly to the Designer Discussion template. Every databaseassociated with the template inherits the new Confidential field.

DISCSW50.NTF (StdR5Disc)

|—————- SALES.NSF Sales discussion inherits from StdR5Disc

|—————-TRAVEL.NSF Travel discussion inherits from StdR5Disc


A spinoff templateMost users’ mail databases inherit their design from the standard Notesmail template, but the Eastern region employees need a Reply to Customerform in their mail databases. Make a copy of the Notes mail template to useas a base for the Eastern mail template. You inherit the design from theNotes mail template, but after creating the Reply to Customer form, youclick “Prohibit design refresh or replace to modify” in the Design DocumentProperties box so the form won’t be deleted when the server resynchronizesthe design of mail databases.

The Eastern region’s template inherits its design from the Domino mailtemplate and also serves as a template itself.

MAIL50.NTF (StdR5Mail)

|——-SLEE.NSF Sam Lee’s mail inherits from StdR5Mail

|——-EASTMAIL.NTF (StdEastMail) Eastern mail template inheritsfrom StdR5Mail

|—————- SBRAUN.NSF Sandy Braun’s mail inherits fromStdEastMail

A designer’s notebookYou create a new template called DesignNotebook to store centralizedinformation, such as employee names and product numbers, as well asgeneric design elements, such as Main Document forms and All byCategory views. Developers and experienced users browse through theDesign Notebook when they create a new database and copy and inheritelements to speed up their design work.

DESIGN.NTF (DesignNotebook)

|————- Suggestion Box: Inherit the All by Category view fromDesignNotebook

|————- Employees Directory: Inherit the Employee Informationform and EmployeeID field

from DesignNotebook

|————- Product Catalog: Inherit the Product ID Update agent fromDesignNotebook


Creating a design library templateIf you have several design elements that you want to copy to differentdatabases, you can create a library of design elements. You do this bycreating a template that contains all of these design elements. That way, ifyou want to copy a design element to a new database, you maintain aconnection to a source template. This allows you to have a design librarytemplate that is maintained and updated centrally and have the changesautomatically propagate to all databases that you choose to inherit fromthat template. This is especially useful if you have forms or images that willbe common to a number of different databases that need occasionalupdating, such as company logos or order forms.

To create a design library template1. Create a new blank database with the file extension .NSF.

2. Copy the individual design elements into the template.

3. On the Design tab of the Database Properties box, select “Database is atemplate” and enter a template name.

4. On the Design tab of the Database Properties boxes of the databasesthat will inherit these design items, select “Inherit design fromtemplate” and enter the template name.


Linking a database to a templateYou can link a new or existing database to a template.

To link a new database to a master templateWhen you create a database from a template, select “Inherit future designchanges” in the New Database dialog box to create the link.

When you create a replica (File - Replication - New Replica) or a copy (File -Database - New Copy), the new database automatically links to the sametemplate that the original database uses.

To link an existing database to a templateIf you link an existing database to a template, the database design isreplaced when the server’s Design task runs, or when you manually refreshthe design. Thereafter, the design remains synchronized with the template.

1. Select the template and choose File - Database - Properties.


3. Highlight the name in the “Database is a template” box, and pressCTRL+C to copy it.

4. Select the database you want to link.

5. Select “Inherit design from template” on the Design tab in theProperties box.

6. Click the Template Name box, and press CTRL+V to paste the name.

Linking individual design elements to a templateTo link individual forms, views, navigators, pages, and other designelements to a template, copy the design element from a template or from adatabase that inherits its design from a template. Then paste the elementinto another database. You can also set up the link for existing designelements in a database to a template.

To link a copied design element to a templateWhen you copy a design element from a template or from a database linkedto a template, the copied element automatically links to the template if youanswer Yes when prompted about inheriting future design changes.


To link an existing design element to a templateIf you link an existing design element to a template, the design is replacedwhen the server’s Design task runs or when you manually refresh thedesign. Thereafter, the design element remains synchronized with the template.

1. Select the master template and choose File - Database - Properties.


3. Highlight the name in the “Database is a template” box and pressCTRL+C to copy it.

4. In Designer, open the database containing a design element you want to link.

5. In the Design pane, select the type of design element you’re designing.

6. Select the name of the design element in the Work pane.


For an agent, choose Agent - Agent Properties.

For other design elements, choose Design - Design Properties.

8. Click the Design tab of the Design or Agent Properties box.

9. Click “Inherit from the design template” and press CTRL+V to paste the name.

Making and distributing design changesWhen you need to redesign an application, make and distribute the changesin one of these ways:

Make design changes directly in an independent database on the server.

This technique combines making and distributing design changes inone step. Use this technique only if a small group of people uses thedatabase and it exists on only one server.

Make design changes in a template and then use Replace Design todistribute the template design to the database.

Make design changes in a master template (sometimes called a “designtemplate”). Use the Design server task or Refresh Design to distributethe master template design to databases that inherit their design fromthe master template.

Using a master template to manage design changes is best in largerorganizations where you need to control, track, maintain, andsynchronize design changes in a structured way. For small


organizations, using a template or a master template is a matter ofpreference.

This figure below summarizes the steps you take to make and distributedesign changes:

Replication is the process by which database replicas on multiple serverssynchronize their data and their designs automatically. It’s important tounderstand which design changes replicate and which don’t and how thedatabase access control list and other replication settings affect thedistribution of design changes.

Refreshing a design

Refreshing a design updates a database whose design is linked to atemplate. Design elements that prohibit design replace or refresh are notincluded in the updates.

Automatically refreshing a designThe Design server task automatically synchronizes all server databases thatare linked to a template. This server task runs by default at 1:00 A.M. Forthe update to work, a template must reside on the same server as thedatabases linked to it. Replicas synchronize with the templates stored ontheir servers.


Manually refreshing a designUse the Refresh Design command to distribute design changes manuallyfrom a template to any databases linked to it. Manually refresh the designof a database when:

The database is stored locally; therefore, the nightly Design server taskdoesn’t update the design.

You want to receive design updates before the scheduled update.

You don’t have Designer access to the template.

Components that are not refreshedThe following are not changed during an automatic or manual refresh procedure:

The database icon (unless you have disabled the “Prohibit designrefresh or replace to modify” box in the Design Properties box)

The database title and category

The property “List as advanced template in New Database”

The database ACL and encrypt database settings

Using This Database and About This Database documents (unless youhave disabled the “Prohibit design refresh or replace to modify” box inthe Design Properties box)

Individual elements whose design is protected from updates (that is, if“Prohibit design refresh or replace to modify” is selected on the Designtab of the Design Properties box for the element)

Components that are refreshedThe following components are changed during an automatic or manualrefresh procedure if the design element changes in the template:

Forms, fields, form actions, and event scripts

Views, folders, and view actions

Agents

Pages

Framesets

Navigators

Shared fields

File - Database Properties selections, except the “advanced template” option


Refreshing a design manually1. 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 thetemplates are on your workstation, and then click OK.

3. Click Yes to confirm.

4. Repeat Steps 2 and 3 if other templates associated with the database arestored on other servers.

Replacing a designThe Replace Design command makes a database identical to a template andis the only way to distribute design changes if the database doesn’t inheritits changes from a template. If you have at least Designer access in thedatabase ACL, you can replace the design of a database with the designfrom a template.

Components that are not replaced during Replace DesignThe following components are not changed during a Replace Designprocedure:

The database icon (unless you have disabled the “Prohibit designrefresh or replace to modify” box in the Design Properties box)

The database title and category

The property “List as advanced template in New Database”

The database ACL and encrypt database settings

Using This Database and About This Database documents (unless youhave disabled the “Prohibit design refresh or replace to modify” box inthe Design Properties box)

Individual elements whose design is protected from updates (that is, if“Prohibit design refresh or replace to modify” is selected on the Designtab of the Design Properties box for the element)


Components that are replaced during Replace DesignThe following components are replaced during a Replace Design procedure:

Forms, fields, form actions, and event scripts

Pages

Views, folders, and view actions

Agents

Navigators

Framesets

Shared fields

File - Database Properties selections, except the “advanced template”option

To replace the design of a databaseIf a database replicates to other servers, replace the design of only onedatabase and let the changes replicate to other replica databases.

1. Select the database on the server and choose File - Database - ReplaceDesign.

2. Select the template.

3. Click Replace and Yes to confirm.

Design changes and replicationUnless you distribute design changes through templates, design changesand any document updates made in one database replicate directly toreplicas, as long as servers have Designer access or greater in the databaseACL. To avoid replication conflicts and unexpected changes, only oneperson — the database designer or manager — should make designchanges to only one database and maintain its design. Then let replicationdistribute the design changes to other replicas.

Replication occurs at the times specified by the server’s replicationschedule. Replicating design changes can take several hours or even a fullday if replicas are in different locations and aren’t replicated frequently.


Templates and replicationWhen you use a template to distribute design changes, you must place areplica of the template on each server that has databases that inherit theirdesign from the template. Give servers Designer access or greater in thedatabase ACL of each replica. To avoid replication conflicts, make changesto one template on a “source” server. Then let replication distribute thedesign changes to template replicas. The updated template replicas thenrefresh the design of linked databases on the server. To distribute designchanges efficiently, the source server should replicate the template replicasbefore the Design task runs on each server at 1:00 A.M. Any updates you’vemade to documents replicate directly with other database replicas.

For more information about replication, see Managing Domino Databases.

Preventing design changesUse these methods to protect a customized design from accidental changes.

Note None of these choices prevents someone with Designer or higheraccess in the database ACL from changing the design. To prevent all designchanges, hide the design of the database.

Protect an individual design element from being replaced or refreshed This is useful to protect customized design elements from being overwrittenin a Replace Design procedure and to protect a customized design elementin a database that is linked to a template.


2. In the Design pane, click a design element. The names of all the designelements of that type appear in the Work pane.

3. In the Work pane, select the name of the design element you want to protect.

4. Choose Design - Design Properties (or for agents choose Agent - Agent Properties).


6. Select “Prohibit design refresh or replace to modify.”


Unlink individual design elements from a templateThis breaks the link between a design element and a template and is usefulwhen you want to customize a design element that you copied from atemplate. Future changes to the design element in the template won’t affectthe design element in your database.


2. In the Design pane, select a design element. The names of all the design elements of that type appear in the Work pane.

3. In the Work pane, select the name of the design element you want to unlink.

4. Choose Design - Design Properties (or for agents choose Agent - Agent Properties).


6. Remove the name of the template in the “Inherit from the designtemplate” box.

Unlink a database from a template This breaks the link between a database and a template and is useful whenyou want to customize the design of an entire database. Future changes tothe template won’t affect the database.

1. Open the database and choose File - Database - Properties.


3. Deselect “Inherit design from template”.

Hiding the design of a databaseTo prevent users from making any design change to a database, hide thedatabase design. Hiding the design permanently disables all designoperations and hides all formulas and scripts. Even users who haveDesigner or Manager access to the database can’t make design changes.

This feature is useful for hiding the design of ready-to-use databases thatare based on a template you own. When design changes are required, youredesign the template, whose design is not hidden, and then refresh thedesign of the linked databases. To maintain maximum design security, donot give the template to anyone except authorized designers, and do notdistribute documentation for the formulas and LotusScript programs.


When you hide a database design, users cannot:

View the settings for design elements (View - Design disappears fromthe View menu)

Modify, add, or delete fields, forms, navigators, pages, or subforms

Modify or delete existing views

View, delete, or modify existing agents or add shared agents

View or change formulas, LotusScript programs, or formulas associatedwith simple actions

Change the Database Open properties

Display a synopsis of the design

Reveal the design of the database by making a copy or replica of it

To hide the design of a databaseThis procedure assumes you’re hiding the design of a database that inheritsfrom a template. Thoroughly review, debug, and pilot test the templatebefore proceeding.

1. Create a new database based on the template.

2. After the database is created, select the new database and choose File -Database - Replace Design.

3. Select the template and select “Hide formulas and LotusScript” and“Inherit future design changes”.

4. Click Replace and Yes to confirm.

Building in access to agents before hiding the designIf an agent in the application requires user input, such as specifying a database on which to run or changing schedule options, you must select the schedule option “Choose when agent is enabled”. Create a button or form or view action that includes a formula using@Command[AgentEnableDisable] to enable the agent automatically.


Hiding design elements

You can hide most design elements so that users can’t see them on menus orlists. You do this in the Design tab of the Properties box for the designelement or agent.

Choose from these options at the Design tab:

“Hide design element from”Choose “Web browsers” to hide a Notes-only design element from Web users.

Choose “Notes R4.6 or later” to hide a Web-only design element from Notes users.

Choose both options to hide the design element from all users. This is usefulwhen a design element launches only from a button or a formula, or if youdesigned the element for purposes that users don’t need to know about.

“Do not show this design element in menus of Notes R4 or laterclients”Use this to hide older design elements from Notes Release 4 users.

Hidden design elements are hidden from the server too; you can’t useDomino 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 forbackground processes, such as lookup formulas, enclose the design elementname in parentheses — for example, (Lookup View) — instead of usingHide tab options.

To hide design elements1. 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.


For an agent, choose Agent - Agent Properties.

For other design elements, choose Design - Design Properties.


6. Choose the appropriate Hide options.


Chapter 15Creating a Workflow Application

Workflow Overview

Workflow applications let you automate tasks. These tasks most ofteninvolve automatically sending mail messages or automatically routingdocuments, such as tracking orders and reviewing project plans. Anyproject requires that one person or a number of people complete a series oftasks; workflow applications guide the project through these tasksautomatically. Workflow applications reduce overhead and errors, speedprocesses, and track the status of a project. For example, a workflowapplication might automatically send a document in a publishing companyfrom writer to editor to proofreader to production. At each stage, anindividual is responsible for specific tasks related to that document. Oncethe task is complete, the workflow application ensures that the individualsresponsible for the next task are notified and receive the data they need toexecute their stage of the process.

Examples of Workflow ApplicationsThe Document Library R5 template (doclbw50.ntf) and the Teamroom R5template (teamrm50.ntf) are examples of applications that includeworkflow. For both templates, the document you want reviewed is kept in acentral database and is not mailed to reviewers. Reviewers receive mailnotifying them of the need to review. Included in the mail may be a doclinkto the document.

The Document Library template uses a review cycle so that you can route adocument link to a series of recipients. It allows serial and parallel reviews.With parallel reviews, every reviewer receives e-mail notification at thesame time. With serial reviews, you do not want all reviewers commentingon the document at the same time. Reviewers receive e-mail notification atdifferent times.

The Teamroom template features parallel review processing. It also allowsthe automatic mailing and archiving of newsletters and memos.

See the Domino Designer Templates Guide for additional information on thesetemplates.

413

Planning workflow

Before you select the type of mailing features that suit a workflowapplication, you should carefully plan the actual workflow. One way toimplement a workflow application is to collect information from thedatabases of an application into a central, shared database and thendistribute the information through e-mail to the appropriate individualusers. Another way to implement a workflow application is to senddocuments automatically from one user to another for their review.

Users working in a shared database can create and edit documents directlyin the database. Remote users must dial into the server database regularlyto contribute. Designers can implement automatic e-mail notifications toalert users to documents in the database that need their attention. Toautomate the process, you can build e-mail notifications into forms oragents. To make it easier for users, the notifications often include document links. For the convenience of remote users, you might include acopy of the document within the e-mail notification instead of a link to thedocument.

If users work in individual mail databases, they can create and respond todocuments and then route them to each other or to a central mail-indatabase. Automated, easy-to-use forms that are stored in documents aretypical of such applications. Of course, if you are sending individual mailmessages, you are increasing disk space because the form is stored with thedocument.

The following table summarizes the advantages and disadvantages of thesetwo approaches.

Method Advantages Disadvantages

Central SharedDatabase

Central shareddatabase; e-mailnotices that link todocuments

Alerts users to work thatneeds their attention or itemsof interest in a centraldatabase; places least burdenon network resources andconserves server disk space;users get to see each other’sreview comments.

Requires network access orremote access through a modem

continued


Method Advantages Disadvantages

Individual MailDatabases

Sending multipledocuments

Easier for remote usersbecause they only need toaccess mail instead ofaccessing a remote database.

Workflow process may takelonger since work is donesequentially; requires moreserver disk space than a centraldatabase because forms must be stored with documents;replication times may be longerbecause of document size.

Features that support automatic mailing

You can add automatic mailing to a database either at the form level orthrough automation features such as form and view actions, agents, and events.

Sending links to documentsIn a workflow application, you may want to mail notices of new ormodified documents or reminders of work that needs to be done. Sendinglinks instead of documents saves time and space. To do so, create an agent,event, form or view action, hotspot, or button that uses one of the following:

The simple action “Send Mail Message” with “Include link todocument” selected.

The simple action “Send Newsletter Summary.”

The formula function @MailSend with the [IncludeDocLink] flag.

A LotusScript program that uses the Send method in either theNotesDocument class or the NotesUIDocument class and theFormatMsgWithDoclinks method in the NotesNewsletter class.

A Java program that uses the Send method in the lotus.notes.Documentclass and FormatMsgWithDoclinks method in thelotus.notes.Newsletter class.

Chapter 15: Creating a Workflow Application 415

Sending documentsIt makes sense to build in features for mailing documents in the following situations:

Users work on documents sequentially from their individual mail databases

You want to send documents to a mail-in database

The form must have a SendTo field that specifies the recipients, unless youuse a formula or program that includes the SendTo information.

Use any of these methods:

Add a MailOptions field with a value of 1 to force the document to bemailed when it is saved.

Select the form property “On Close: Present mail send dialog” to letusers decide if they want to mail the document.

Create an agent, event, form or view action, hotspot, or button thatuses:

The simple action “Send Document”

The formula functions @Command([@MailSend]) for optionalmailing or @MailSend for automatic mailing

A LotusScript program that uses the Send method of theNotesDocument class or the NotesUIDocument class

A Java program that uses the Send method of thelotus.notes.Document class

In addition, all forms and views contain the default action “SendDocument” that you can display in the Actions menu or the action bar.

Enabling users to view documentsTo allow users to view mail-enabled documents, do one of the following:

Copy the form into the master mail template on the server and refreshthe design of mail databases.

Select the “Store form in document” option for the form.


Forwarding documents in a mail memoUse 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 oneof the following:

The simple action “Send Mail Message” with the option “Include copyof document” selected

The formula function @Command([MailForward])

A LotusScript program that uses the Forward method in theNotesUIDocument class

In addition, all forms and views contain the default action “Forward” thatyou can display in the Actions menu or the action bar.

Sending replies to a mail memoTo activate a message to a mailed document, create an agent, event, form orview action, hotspot, or button that uses the simple action “Reply toSender.”

Mailing features and Web applicationsWeb users whose mail databases reside on a Domino server can participatein mailing processes. When you are designing forms or views, include formor view actions as alternatives to menus for tasks Web users need to do. Forexample, you can create a “Send Document” action so that it appears on theaction bar of a form both in Notes and on the Web.

Fields that control mailing optionsTo build mailing options into a form, create fields that have reserved namesin 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 orchoice list fields that use predefined values.

For information on text fields, see the topic Text and rich text fields. Forinformation on choice list fields, see the topic Displaying lists of choices.

For information on editable and computed fields, see the topic Editable andcomputed fields.


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.

Encrypt 1, 0 Use 1 to encrypt maileddocuments.

MailFormat B, E, M, T Enables cc:Mail users to viewNotes documents in a variety ofpredefined formats:

B = both text and encapsulated.

E = encapsulated in a Notesdatabase, which is attached tothe cc:Mail memo.

M = mail. Body field ofdocument is text and pastedinto cc:Mail memo.

T = text. Contents of thedocument are rendered as textand pasted into the body of thecc:Mail memo.

MailOptions 1, 0 Use 1 for automatic mailing.

ReturnReceipt 1, 0 Use 1 to send a receipt whendocument is opened by therecipient.

SaveOptions 1, 0 Use 1 to save mailed documents.

SendTo The name(s) of a person,group, or mail-in database.

Required for all forms that maildocuments.

Sign 1, 0 Use 1 to an add electronicsignature to fields. (Onlyapplicable if a form also containssign-enabled fields.)

If you write a LotusScript program that uses the Send method of theNotesDocument class or a formula that uses @MailSend, you can includemany of the above mailing options in the script or formula.

For more information on using LotusScript, see the Programming Guide.


Interactions with the Mail Send dialog boxThe MailOptions field with a value of 1 overrides the user’s choices in theMail Send dialog box if the form is set to enable optional mailing. With aMailOptions field set to 1, users can click Yes to save the document, No toclose without saving, or Cancel to return to the document.

The Sign, Encrypt, and SaveOptions fields with values of 1 override theproperty “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 Senddialog box.

Interactions with the Document Save dialog boxThe values in SaveOptions, Sign, and Encrypt fields override the user’ssettings in the Document Save dialog box.

MailFormatA computed MailFormat field can have one of the following values:

Encapsulated (E)

The document is encapsulated in a database, which is attached to thecc:Mail memo. The cc:Mail recipient must have the Notes clientinstalled on the workstation. This preserves the document exactly as itlooks in Notes. To read the document, the cc:Mail user double-clicksthe icon representing the attached database; this launches Notes andopens the database. Use this format only if information will be lost ifthe document were to be converted to Text or Memo format. TheEncapsulated format creates larger documents, so it uses more serverdisk space. To ensure that the document is displayed correctly when acc:Mail recipient starts Notes, assign the form property “Store form indocument” in the Form Properties box.

Text (Text)

The contents of the document are rendered as text and pasted into thebody of the cc:Mail memo. The cc:Mail recipient can read the documentwithout using Notes. Since the document is rendered as text, you do notneed 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 theydo not use Notes.

Mail (M)

The Body field of the document is rendered as text and pasted into thecc:Mail memo. Use this format only with documents that were createdusing a form that contains a field named Body.


Since the document is rendered as text, you do not need to store theform in the document.

MailOptionsThe MailOptions field with a value of 1 overrides the property “On Close:Present mail send dialog” in the Form Properties box. With a MailOptionsfield set to 1, users can click Yes to save the document, No to close withoutsaving, or Cancel to return to the document. To add the mail signing andencryption options, create editable keywords fields named Sign andEncrypt.

SendToThe “Allow multi-values” and “Allow values not in list” are useful forSendTo fields.

Examples: Fields that control mailing optionsAn editable SendTo field with a default valueYou want to give users the name of the mail-in Employee Survey database, and the option of mailing surveys to other people. Create aneditable SendTo field, select “Allow multi-values,” and write a defaultvalue formula that includes the mail-in database name, enclosed inquotation marks.

A hidden SendTo field with a single recipientSandy Brown needs to receive all documents saved in the MarketingStatistics database. Add a hidden Names field called SendTo to theStatistics form. The field formula contains the recipient’s name and domainenclosed in quotation marks. The recipient’s domain is required if therecipient isn’t in the same Notes domain from which the document is sent.

"Sandy Brown @ Marketing"

A formula that calculates recipients and sends a documentApprovers want to receive new travel requests from employees by e-mail.On the Travel Request form of the Employee Expenses database, createhidden text fields called SendTo, Subject, and Remark. The field formulabelow calculates the names of approvers and sends the original documentas a link when the document is saved for the first time.

REM "Send mail to approvers the first time the doc is saved";REM;SendTo :=@Unique(@Trim(ApproverName_1 : ApproverName_2 : ApproverName_3));Subject := "Travel Request for " + TravelerName + "requiresyour approval";Remark := "A Travel Request has been entered for " +TravelerName + ". Your approval is required. Pleasedouble-click the following link and approve or reject therequest.";


REM;@If(@IsNewDoc & @IsDocBeingSaved; @MailSend(SendTo; ""; "";Subject; Remark; "";[IncludeDoclink]); "")

Displaying the MailSend dialog box

If you want the Mail Send dialog box to appear so that users have theoption of mailing, saving, signing, or encrypting a document, do one of thefollowing:

Select “On Close: Present mail send dialog” in the Form Properties boxon the Defaults tab.

Write a formula that includes @Command([MailSend]).

Make sure that you include a SendTo field on the form.

Creating a database that receives mailings

A mail-in database document in the Domino Directory allows a database toreceive mailed documents. The server administrator creates the mail-indatabase document:

1. Open the Domino Directory and choose Create - Server - Mail-InDatabase.

2. Next to Mail-in name, give the database a name that identifies it inSendTo fields or in formulas on the form.

3. Next to Domain, enter the domain name if your organization usesmultiple mailing domains.

4. Next to Server, enter the hierarchical name of the server on which thisdatabase resides.

5. Next to Filename, enter the database directory name (if the database isin a subdirectory of the Notes Data directory) and the file name.

6. (Optional) Click Administration, and next to Administrators enteradditional names of people who can change this document.

7. Close and save the document.


Using an agent to send automatic repliesFor a mail-in Survey database, for example, that collects employees’responses about the company’s benefits package, create an automaticresponse agent so employees receive a confirmation that the survey arrived.

1. Select the Survey database and choose Create - Agent.

2. Give the agent the name “Send Thank-You” and select “Shared Agent.”

3. Select the run option “If New Mail Has Arrived.”

4. Select Simple action(s) and click Add Action.

5. Select “Reply to Sender” and click “Reply to sender only.”

6. In the box for the body of the text, type:Thank you for taking the time to respond to our survey. Wewill distribute the results as soon as they are ready.

7. Click OK.

8. Close and save the agent.

Using an agent to mail noticesConsider that every week, you want action items mailed from the MeetingTracking database to the people who are assigned to each task.

1. Select the Meeting Tracking database, and choose Create - Agent.

2. Give the agent the name “Mail Action Items” and select Shared Agent.

3. Select the run option “On Schedule Weekly” and click Schedule.

4. Select On Wednesday, type:5 PM

Then click OK.

5. Select “All new and modified documents since last run” and click AddSearch.

6. Select “Condition: By Form Used,” select “Action Item,” and click OK.

7. Click Add Search and select “Condition By Field” and select Status,contains, Open. Click OK.

8. Click Simple action(s) and Add Action.

9. Select “Send Mail Message” and click More.

10. In the To box, click Formula and enter the formula:AssignedTo

11. In the Subject box, click Formula, type this formula and click OK:ActionItem + ", due " + @Text(DueDate)


12. In the Body box, type:This action item has been assigned to you.

13. Select “Include copy of document” and click OK.


Using an agent to send announcementsConsider that you are designing a Corporate Announcements database towhich managers want to send notices for important announcements. Tocirculate particular announcements, managers select them from the viewand then select the agent that sends notices.

Tip To prevent non-managers from running this agent, deselect “Createpersonal agents” in the database access control list for all users except thosewith Manager access.

1. Select the Corporate Announcements database and choose Create -Agent.

2. Give the agent the name “Mail announcements” and select “SharedAgent.”

3. Select the run option “Manually From Agents List.”

4. Select “Selected documents.”

5. Select Simple action(s) and click Add Action.

6. Select “Send Newsletter Summary.”

7. In the To box, type:All Personnel

“All Personnel” is a group in the Domino Directory.

8. In the Subject box, type:Important Announcements

9. In the Body box, type:Please note the following new announcements:

10. Select “Include summary for each document in view,” select the All ByDate view, and click OK.



Chapter 16Connecting to Enterprise Data

Accessing data in enterprise applications

Incorporating back-end data into everyday business processes maximizesthe value of a Designer application. Designer includes a range oftechnologies for the security and control of business processes, formsrouting, and approvals management. With enterprise integrationtechnologies, you can incorporate traditionally difficult-to-reach data intoyour business applications.

Using data integration tools and services, you can create applications thatcontain connectors to relational databases (such as Oracle and DB/2),Enterprise Resource Planning systems (such as SAP, PeopleSoft, and J.D.Edwards), and transaction systems (such as CICS, IBM MQSeries, and IMS).You can accomplish this either programmatically or with visual tools thatwork with native database drivers.

The following connection solutions are available either as part of DominoDesigner or as an add-on tool.

@DB commandsAs in previous releases, you can use @DB commands and the LotusScriptData Object (LS:DO) to exchange data with relational databases usingODBC.

For more information on @DB commands and LS:DO, see the ProgrammingGuide.

Domino Enterprise Connection Services (DECS)Domino Enterprise Connection Services (DECS) is a visual tool and highperformance server environment you can use to create Web applicationsthat provide live, native access to enterprise data and applications. Thevisual tool includes an application wizard and online Help to assist you todefine external data source connections — for example, DB2, Oracle,Sybase, File directory, EDA/SQL, or ODBC — and fields within yourapplication that automatically update with external connector data.

For more information on connecting to legacy databases, see the DominoEnterprise Connection Services User’s Guide.

425

LotusScript and Java classesLotusScript and Java include classes for enterprise data access. Use theseclasses to customize applications to incorporate information from relationaldatabases, transaction systems, and ERP applications according to yourbusiness needs. The Domino Server includes the Lotus Domino ConnectorLotusScript extension, permitting programmatic access to DominoConnectors from LotusScript.

For more information about the Domino Connector LSX, see the LotusScriptExtension for Domino Connectors Reference Guide.

The Domino driver for JDBC, providing standard JDBC access to data inDomino databases, is also available from the Lotus Web site athttp://www.lotus.com. Using this driver, you can write Java applets andapplications that use JDBC to access information in Domino databases.JDBC classes now ship with Domino in the java.sql classes. These classesmay be used when writing Java agents to access relational data via standardJDBC drivers.

For more information on LotusScript and Java classes, see the ProgrammingGuide.

Domino ConnectorsDomino Connectors are modules which provide native connectivity toexternal sources such as relational databases, ERP, or transaction systems.You can access these connectors through the forms-based development toolin DECS, or through the Domino object classes using LotusScript or Javalanguages.

For more information on Domino Connectors, see the Domino ConnectorsSetup Guide.

Lotus Enterprise IntegratorLotus Enterprise Integrator, previously called Lotus NotesPump, which isavailable separately, extends DECS functionality beyond real-time datasources to include support for high volume data transfer andsynchronization. Lotus Enterprise Integrator provides visual tools tomanage integration between data sources without programming, includingthe capability to initiate event-driven or scheduled high volume datatransfers between Domino applications and relational databases and otherenterprise applications. Lotus Enterprise Integrator also supportsprogrammatic data transfers via LotusScript and Java Classes.

For more information on Lotus Enterprise Integrator, see the Lotus Web siteat http://www.eicentral.lotus.com.


Connectivity Solutions Description Domino Version

DECS - Domino Enterprise ConnectionServices

Forms-based development tool. Provideslive access to enterprise data andapplications, including relational databases,transaction systems, and EnterpriseResource Planning (ERP) systems.

R4.6.2 or higher

LS:DO - LotusScript Data Object

LotusScript access to any ODBC-compliantdata sources.

R4.0 or higher

JDBC - Java DatabaseConnectivity

Access from Java agents to relational data via Standard JDBC classes. AJDBC to ODBC bridge also shipped as a part of Domino.

R4.6 or higher

Lotus Domino Connector LotusScript Classes

Unified object model with a consistentinterface to programmatically accessenterprise data and applications. Theseclasses can be used with LotusScript or Java.

R4.6.2 or higher

Lotus Domino Connectors

Modules which provide native connectivityto enterprise data sources. These connectorscan be accessed through Domino EnterpriseConnection Services or programmaticallythrough Domino classes.

Connectors to DB2, Oracle, Sybase, Text &File based systems, EDA/SQL, and ODBCare provided with the Domino server.Premium connectors to ERP applications,Transaction Monitors, and Directorysystems will be available separately.

Note that the NotesSQL driver for ODBCaccess to Domino data is available for freefrom the Lotus Web site athttp://www.lotus.com.

R4.6.2 or higher

LSX - LotusScript extensions

Create custom objects that work nativelywith Domino applications as well as Javaand OLE. Some examples of LSX’s areMQSeries, SAP, DB2, and Rich text.

The DB2 LSX will ship for Domino Release5. These are classes for programmingdirectly to the DB2 client access library.

R4.0 or higher

Lotus Enterprise Integrator

(Lotus Notes Pump)

Data distribution server that providessupport for event-driven or scheduledhigh-volume transfer and data sourcesynchronization.

R4.0 or higher

continued

Chapter 16: Connecting to Enterprise Data 427

Connectivity Solutions Description Domino Version

Domino Connector Toolkit

Provide developers with tools andinformation to build additional DominoConnectors and classes available in Java orLotusScript.

R4.6.2 or higher

Using ODBC to access relational databases

You can use the ODBC (Open Database Connectivity) Version 2.0 standardto access relational databases such as DB2 or Oracle. Using formulas orscripts embedded in Domino objects, you can integrate the data from manyexternal databases into Domino applications. For example, a customercall-tracking application accessed via the Notes client or Web browser canaccess customer financial data from an ODBC-compliant relational databasemanagement 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 ODBCWhen you install Designer, ODBC modules that support external dataaccess 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 andinstall the library and driver separately. For Windows 95, for example, youneed these modules on your workstation:

The ODBC 2.0 interface, available from Microsoft.

This defines the library of ODBC functions that perform the connection,query, and data-retrieval processes.

The Driver Manager, available from Microsoft and other vendors.

This loads the necessary drivers used to access the data and acts as aninterface between Domino and the drivers.

The ODBC drivers, available from third-party vendors or available atno charge to Notes and Domino users on the Lotus Web site.

These handle communication between the Driver Manager and thedatabases. Domino supports a variety of drivers. Each driver affects thespecific capabilities of your application and comes with its owninstallation, configuration, and Help documentation.


Note On 32-bit platforms, such as Windows 95, avoid having the32-bit and 16-bit versions of drivers and driver managers installed witha 32-bit or 16-bit version of Domino installed. The two different types ofsoftware do not mix. When using 32-bit Notes clients or servers, use a32-bit driver manager and 32-bit drivers. When using a 16-bit Notesclient or Domino server, use a 16-bit driver manager and 16-bit driversto use ODBC to make successful connections.

Some Lotus applications include ODBC drivers that are licensedspecifically for use with that application. Domino cannot use thesedrivers. If you try to use these drivers, a message appears stating thatyou must have a license. You may be given a phone number or otherinformation.

For more information about ODBC, see the Microsoft ODBC 2.0Programmer’s Reference and SDK Guide published by Microsoft Press.

Registering data sources for ODBCBefore your Designer application can access data in a relational database,you must register a data source that tells the ODBC driver manager how tolocate the data. Registering a data source ties a specific ODBC driver withthe data to be accessed. The registration information includes the data youwant to access, its associated server or directory, the back-end DBMS, andthe network platform. To register this information in a registration file(ODBC.INI in Windows 95), you use the Windows Control Panel, a utility,such as the Windows ODBC Administrator Utility, or a script or formula.

Note Users of existing DataLens® programs that use Windows 3.1 mustensure that the data sources named in those programs are registered inODBC.INI (not DATALENS.INI).

To register a data source for ODBCYou can use the operating system to register a data source for ODBC. Usingthe operating system allows you to register the data source hardware,software, and database type. The following procedure applies to Windows:

1. Open the Windows Control Panel.

2. Click the ODBC icon.

3. Click Add.

4. Select the driver you want, and click OK.

5. Enter the data source name, description, and requested information.

6. Some drivers require additional information; enter any otherinformation necessary and click OK.

7. Click Close.

Chapter 16: Connecting to Enterprise Data 429

Writing formulas and scripts to access relational databasesThe following @functions access an external database through ODBC andreturn a value or list of values:

@DbColumn returns all the values in one column of a table, or all thedistinct values.

@DbLookup returns selected values in one column of a table bymatching keys.

@DbCommand passes a command to an external DBMS and returns theresult.

@DbColumn and @DbLookup can only retrieve data. They can’t add,delete, or modify data, or perform other operations. @DbCommand canretrieve data or send other SQL statements that can change data.LotusScript provides a wider range of capabilities including the ability toupdate the external database.

For more information about accessing external databases through ODBCand 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 writeapplications that incorporate data from external non-Notes data sources.Your script may perform the following steps:

Establish a connection with the data source.

Each connection requires the data source name. If the data source nameis not already registered, you must also provide additional information.

Use SQL statements to send queries or other actions to the data source.

Retrieve and use result sets.

Read, modify, or add information into relational databases.

Disconnect from the data source.

For more information on writing scripts to access external databases, see theProgramming Guide.


Chapter 17Including Java Servlets in Web Applications

This chapter describes creating and running Java servlets on a Domino Webserver. Servlets are invoked by URLs and are capable of performing a widevariety of custom operations for a Web application.

Overview of Java servlets

A servlet is a Java program that is run by the Domino Web server inresponse to a browser request. Servlets provide a convenient way to addpowerful functionality to your Web application. In some ways, servlets actlike CGI programs, but they are more tightly integrated with the server andcan take advantage of special Java classes. For example, a servlet mayconnect to a relational database or enterprise system and get data inresponse 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 howthey are run. Servlets are “server-side” programs; a servlet’s Java class isloaded and run entirely within the Domino server and the result from theservlet, usually a page of HTML, is returned to the browser. In contrast,applets are “client-side” programs; an applet’s Java class is downloaded tothe browser and is run by the browser. Therefore, applets require Javasupport in the browser, but servlets do not.

Servlets for Domino must conform to the Java Servlet API Specification, anopen standard published by Sun Microsystems, Inc.

Running a servlet in Domino involves writing the servlet, enabling servletsupport in Domino, and, if necessary, setting servlet properties.

431

Comparing agents, servlets, and CGI programs

Agents, servlets, and CGI programs all allow you to extend thefunctionality of your Domino Web application. Agents can be tightlyintegrated with a Web application through the form WebQueryOpen andWebQuerySave events. Servlets have special features available through theServlet API classes, such as session and cookie management. Due to thegrowing popularity of Java, the trend today is to use servlets rather thanCGI programs for new development. However, there is a large selection ofoff-the-shelf CGI programs already available.

If you are writing your own application and need to program somefunctionality on the server, you may have a choice of which type ofprogram to use. Each type of program has its advantages and will be thebest choice in particular situations. Here are some suggested uses for eachtype of program:

Program type Best uses

Agent Programs that perform Domino actions when documentsare read or posted.

Programs that need to be run on a schedule or whendatabase 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 anon-Java API.

Here are some useful comparisons of the properties of these programs.

What language can the program be written in?Agent: Java, LotusScript, or Notes formula language. All are inherentlycross-platform.

Servlet: Java. Inherently cross-platform.

CGI program: Platform scripting languages; that is, any languagecompiled into an executable file, or cross-platform languages such asJava or Perl.


Where is the program stored?Agent: Stored in a Domino database, which means that agents takeadvantage of database replication and server clustering.

Servlet: Stored in the file system, usually in the domino\servletdirectory.

CGI program: Stored in the file system, usually in the domino\cgi-bindirectory.

How is the program invoked by a Web user?Agent: Invoked automatically by a WebQueryOpen or WebQuerySaveevent, or invoked directly by an OpenAgent URL, for example,“http://acme.com/sales.nsf/results?OpenAgent”. Agents can also betriggered by server events, such as the arrival of new mail, or on ascheduled basis.

Servlet: Invoked directly by a URL. Domino recognizes two types ofservlet URLs. The first type specifies the servlet by its name, forexample:“http://acme.com/servlet/SQLDatabaseQuery?month=june”. Thesecond type specifies a file extension that the Domino administrator hasmapped to a servlet, for example,“http://acme.com/sqlquery.esp?month=june”.

CGI program: Invoked directly by a URL, for example,“http://acme.com/cgi-bin/filesearch?string=widget”.

When is the program loaded and unloaded by the server?Agent: Loaded every time it is invoked and unloaded when it hasfinished.

Servlet: Loaded once; stays loaded until the HTTP server task is shutdown or restarted. This gives servlets a significant performanceadvantage over agents or CGI programs. However, this also means thatthe servlet classes can be accessed from many requests simultaneously,so you must make sure that the servlet code is thread-safe.

CGI program: Loaded every time it is invoked and unloaded when it hasfinished.

Chapter 17: Including Java Servlets in Web Applications 433

How can the program interact with Domino?Agent: LotusScript and Java agents can use the Domino object classes.Formula agents can use most @functions.

Servlet: Can access Domino through the Common Object Request Broker(CORBA) interface.

CGI program: Can access Domino through the CORBA interface, orthrough the Domino C or C++ APIs.

What security is available for the program?Agent: To invoke an agent, a Web user must have at least Depositoraccess to the database containing the agent. An agent can run with theidentity of its creator or the user. The full range of Domino securityfeatures applies to operations performed by the agent.

Servlet: Access to the servlet can be controlled by file-protectiondocuments in the Domino Directory. If the servlet accesses Dominothrough the CORBA interface, it can specify a Domino user name andInternet password. Domino security applies to all COBRA operations.

CGI program: Access to the program can be controlled by file-protectiondocuments in the Domino Directory. If the program accesses Dominothrough a C API, it takes the identity of the server ID; if it uses theCORBA interface, it can specify a user name and Internet password. Inboth cases, Domino security applies.

Running servlets in Domino

Writing the servletTo write a servlet, you need a Java compiler and the servlet API. You canobtain both from Sun Microsystem’s web site at http://java.sun.com.Download the Java Development Kit (JDK), which includes the compilerand other basic tools, and the Java Servlet Development Kit (JSDK), whichincludes the servlet API specification, the servlet .JAR file (jsdk.jar), andexample servlets. The Sun site also provides links to other servlet resourceson the Web.

You can also write servlets using any popular Java developmentenvironment. As a convenience, a copy of jsdk.jar is included in the Dominoserver and Designer installation kits. It is identical to the file supplied inSun’s JSDK.

Sun periodically updates the JDK and JSDK. Domino 5.0 supports JDK 1.1.6and JSDK 2.0. Domino quarterly maintenance releases (QMRs) often


incorporate Sun’s upgrades, so you should check the QMR Release Notes toverify the supported JDK and JSDK versions.

Enabling servlet support in DominoServlets are loaded and called by the Domino Java Servlet Manager, a partof the HTTP server task. The runtime Java support for servlets is providedby the Domino Java Virtual Machine (JVM). When the HTTP task is started,it can automatically start the servlet manager and load the JVM. The HTTPtask will write status messages for these operations to the server consoleand log file.

The servlet manager is controlled by settings in the Domino DirectoryServer document. The settings are located on the Internet Protocols -Domino Web Engine tab of the Server document. The settings are asfollows:

Setting Options

Java servlet support None: (default) The HTTP task does not load the servletmanager or the JVM.

Domino Servlet Manager: The HTTP task loads both theJVM and the servlet manager.

Third Party Servlet Support: The HTTP task loads the JVM,but not the Domino servlet manager. This allows the use ofthird-party servlet managers such as IBM’s WebSphereApplication Server.

Servlet URL path The path in a URL that signals Domino that the URL refersto a servlet. The default is /servlet.

Class path A list of one or more paths which the Servlet Manager classloader will search to find servlets and their dependentclasses. This setting allows you to add additional paths.You may specify directories, JAR files, and ZIP files. Pathsmay 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 URLrefers to a servlet. Each extension in the list must bemapped to a single servlet by a directive in theservlets.properties file. The default is no extensions.


The following settings control the Domino Servlet Manager’s runtimesupport of the Java Servlet API HttpSession interface. A servlet that doesnot 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 periodicallychecks the user activity of all HttpSession instances.Sessions that have been idle for a given period of time areautomatically terminated. The servlet manager calls theinstance’s HttpSession.invalidate() method to inform theservlet 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 beforeterminating a session. The default is 30 minutes.

Maximum activesessions

The number of simultaneous active sessions allowed. Thedefault is 1,000 sessions. When this limit is reached, thesessions that have been idle the longest are terminated.

Session persistence Enabled: When the HTTP task exits, the servlet managersaves session data to a disk file called sessdata.ser in theDomino data directory. The session data will be reloadedwhen the HTTP task is restarted. Objects that the servlethas bound to sessions will also be saved if the objectsimplement the java.io.Serializable interface.

Disabled: (default) All session data is discarded when theHTTP task exits.

Loading servlet classes with the JVM loaderThe Servlet Manager class loader will not load classes that use native code,create custom class loaders, or perform certain other restricted operations. Ifyour 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 isnormally responsible for loading classes from the standard Java archivesinstalled with Domino, in particular the java.* and lotus.* packages. You canforce a servlet to be loaded by the JVM loader rather than by the ServletManager loader by moving the servlet from the Servlet Manager classpathto the JVM classpath. The JVM classpath is specified by the NOTES.INIvariable JavaUserClasses.


Setting properties for servletsSpecial properties for individual servlets can be specified in a text file calledservlets.properties located in the Domino data directory. The followingproperties can be specified:

Alias

Initialization arguments

URL extension mapping

Load at Servlet Manager startup

These properties are specified by directives in the servlets.properties file.The general syntax of a directive is:

servlet(s).<name>.<property>=<value(s)>

Directives are case-sensitive. The servlets.properties file can also containblank lines and comment lines starting with the “#” character. Theservlets.properties file is optional. The default properties for servlets are: noalias, no initialization arguments, no extension mapping, and load servletson demand.

Servlet aliasesThe alias directive has this syntax:

servlet.<alias-name>.code=<class-name>

For example:

servlet.SQLQuery.code=sql.database.query.Servlet

A servlet alias is a convenient name by which to reference the servlet in aURL, instead of using its class name. An alias is especially useful if theservlet is in a package. The above example allows the servlet to be invokedby a URL like “http://acme.com/servlet/SQLQuery?month=june” ratherthan “http://acme.com/servlet/sql.database.query.Servlet?month=june.”

You can assign more than one alias to a servlet. The servlet manager willcreate a new instance of the servlet on receiving the first URL that refers toeach alias. The servlet manager will call the servlet’s init() method when anew instance is created. Since the alias name can be used in other directivesin the properties file, the instances can be given different properties. Forexample, you could specify a separate initialization argument directive foreach alias. Also, because the servlet classes are only loaded once even ifmultiple instances are created, the instances of the servlet can share data byusing static class variables.


As a security feature, if you give a servlet an alias, the servlet cannot bedirectly referenced in a URL by its class name. This allows you to hide theactual name of a servlet.

Initialization argumentsYou can specify initial data for a servlet in the properties file. The servletcan access the data by using the method ServletConfig.getInitParameter.The initialization directive has this syntax:

servlet.<alias or classname>.initArgs=<name1=value1>,<name2=value2>,...

Multiple arguments can be specified, separated by commas. For example:

servlet.SQLQuery.initArgs=target=db2,user=Domino,cacheSize=30

URL extension mappingThe 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 fromthe next by a space. All extensions must also be included in the “Servlet fileextensions” setting in the Server record. For example, to cause Domino tocall the SQLQuery servlet whenever a URL specifies the extension “sql” or“sq,” add “sql,sq” to the server setting and add this directive to theproperties 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 startupBy default, the servlet manager loads a servlet’s class files into memory thefirst time a URL is received that refers to the servlet. However, you canspecify that one or more servlets should be loaded immediately when theservlet manager is started. This prevents users from experiencing delayswhen 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 separatedby spaces.


If you have given a servlet one or more aliases, you can include the aliasesin the startup directive. This will cause the servlet manager to load theservlet classes and then create an instance for each alias.

After the servlet manager loads a servlet’s classes, they stay in memoryuntil the Domino HTTP task is stopped by the console command “tell httpquit” or restarted by the console command “tell http restart.” Beforeunloading a servlet, the servlet manager calls the destroy() method for eachinstance 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 untilthe HTTP task is stopped. The “tell http restart” command will not unloadthe class.

Example properties fileHere is an example of a servlets.properties file:

# Properties for the sql servletservlet.SQLQuery.code=sql.database.query.Servletservlet.SQLQuery.initArgs=cache=30servlet.SQLQuery.extension=sql# Properties for the mail servletservlet.MailServlet.initArgs=mime=enabled,smime=disabled

# Both servlets should be loaded at startupservlets.startup=SQLQuery MailServlet# end of fileExample: Java servlet

This example servlet returns an HTML page that displays all the HTTPheaders that the browser sent with the servlet request.

import java.util.*;import java.io.*;import javax.servlet.*;import javax.servlet.http.*;

public class ExampleServlet extends HttpServlet {

public void doGet (HttpServletRequest request,HttpServletResponse 3response) throws IOException{ response.setContentType("text/html"); ServletOutputStream out = response.getOutputStream(); out.println("<HTML><B>Headers sent with therequest:</B><BR>");

for (Enumeration headers = request.getHeaderNames();


headers.hasMoreElements();) { String headerName = (String) headers.nextElement(); out.println("<BR>" + headerName + ": " + request.getHeader(headerName)); } } // end of method

} // end of class

After you compile this code, copy the ExampleServlet.class file to yourserver domino\servlet directory. It does not need any special properties, soyou do not need to create a servlets.properties file. Run the servlet from abrowser by entering this URL, using the name of your server:

http://www.yourserver.com/servlet/ExampleServlet

The information in the page returned by the servlet depends on thebrowser. Here is the HTML page returned for a Netscape browser:

<HTML><B>Headers received with the request:</B><BR><BR>ACCEPT-LANGUAGE: en<BR>CONNECTION: Keep-Alive<BR>ACCEPT: image/gif, image/x-xbitmap, image/jpeg,image/pjpeg, image/png, */*<BR>USER-AGENT: Mozilla/4.05 [en] (Win95; U ;Nav)<BR>ACCEPT-CHARSET: iso-8859-1,*,utf-8<BR>HOST: test1


Appendix ADomino Designer Templates

This appendix lists templates available with Domino Designer that arespecifically intended for use by application developers.

For information on system administration templates, see “Application and System Templates” in Administering the Domino System or DominoAdministration Help.

Table of Domino Designer templates

If you install the templates with Domino Designer, you’ll find them in theNotes program directory.

Database title File name and designtemplate name

Audience Description

Discussion -Notes & Web(R5.0)

discsw50.ntf

StdR50Disc

GeneralNotes usersand Webbrowserusers

Electronic conference room.

Features: Threadeddiscussion with built-in userprofiles that allow automaticmailing of links to items ofinterest. Anonymousresponses, archiving, andpublic/private threads.Multiple navigators,alternate view templates,and hotspot actions for Webbrowser users.

DocumentLibrary - Notes& Web(R5.0)

doclbw50.ntf

StdR50WebDocLib


Document storage.

Features: Review workflow(serial and parallel) andarchiving.

continued

441

Database title File name and designtemplate name

Audience Description

Microsoft OfficeLibrary (R5.0)

doclbm50.ntf

StdR50DocLibMS

GeneralNotes users

Special version of theDocument Library templatededicated to this applicationsuite.

Automatically loads andsizes the OLE object to thewindow; and stores andsupports review cycles ofdocuments created withsuite products.

PersonalJournal (R4)

journal4.ntf

StdR4Journal

GeneralNotes users

Electronic diary where userscan write and organizeprivate ideas anddocuments. Includesinstructions for customizingthe design.

Site Registration5.0

siregw50.ntf

StdSite50Reg

Webbrowserusers

A sample showing how toregister Web users forDomino-based applications.Users can create accounts forthemselves with no manualintervention.

TeamRoom(R5.0)

teamrm50.ntf

StdR50TeamRoom


Model of team collaborativeoperations.

Maintains several documentcommunication types torepresent meetings,discussions, and actionitems. Features parallelreview processing,archiving, and newsletters.

For an in-depth look at features of several of these templates, see Domino Designer Templates Guide, available on the Notes.Net Web site(http://www.notes.net).


Appendix BImporting to and Exporting from Views

Importing data allows you to move data from an old system into a view.Exporting data allows you to create a table of the data in a view for use in apresentation 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 toimport a small test file first. You can quickly determine whether the importis working correctly and make any necessary corrections before you importthe entire file. The following table lists the types of files you can import andexport.

File type File extensions File description

Lotus 1-2-3 andSymphony®

Microsoft Excel*

.wks, .wk1, .wrk**,

.wr1**, .wk3, .wk4Entire worksheet or named range

Tabular text .tab, .txt, .prn, .rpt ASCII text arranged in rows andcolumns; limit of 1536 charactersper record, total

Structured text .ltr, .cgn, .str ASCII text that retains its structurein fields and values; shown as onerecord per page and one field perline; limit of 256 bytes per simpletext field

*To import a Microsoft Excel file, use Excel to save the file as a 1-2-3worksheet and then import it.

**You cannot import a .wrk or .wr1 file to a view, but you may export toeither format. If you import a multiple-worksheet file, only the worksheetthat was most recently viewed will be imported. If you import a specificrange from a multiple-worksheet file, only the information from the mostrecently viewed worksheet will be imported.

443

Importing options

Formatting optionsYou have three choices for generating the column titles and widths whenyou import a file.

Choose “View Defined” if the column names and column widths in thesource worksheet are identical to the names and widths of the columnsin the view.

Choose “WKS Title Defined” if you’ve set up the worksheet so that thecells in the first row of the worksheet match the column headers andfields in the view. The cells in the first row must be labels.

Choose “Format File Defined” if you are using a column descriptor file(.col) that contains column style instructions.

Including additional fields for imported documentsYou can use the import option “Calculate fields on form during documentimport” if you want the newly created document to contain all of the fieldsof the form you’re using for the import. Notes imports information fasterwhen you do not select this option. If you first import without selecting thisoption and the results are not what you expect — for example, fields thatrely on other fields are empty or incorrect — import the worksheet againand choose this option.

GuidelinesNotes uses a character translation file (.cls) to translate foreign symbols andcharacters. 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 holdthe imported data. When you import a worksheet into the view, eachworksheet row becomes an individual document, and each worksheetcolumn becomes a field. The original cell contents become the fieldcontents. You can import data into either main documents or responsedocuments.

Notes doesn’t wrap lines of an imported worksheet. If a worksheet hasmore columns than a window can display, use the horizontal scroll bars tosee the full width of the worksheet. Notes can handle a worksheet whosemaximum text width is 22.75 inches; additional text is not displayed in the columns.


Importing worksheet data into a viewThe source file containing the worksheet must be on your local hard driveor on a file server to which you are connected.

1. Select the database and open the view that will receive the source data.


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 arecreating response documents.

8. Select a “Column format.”

9. If you select Format File Defined, enter the name of the .col file,including the complete operating system path.

10. To import part of a worksheet, type a range name or range address inthe WKS Range Name box. You cannot import a 3-D range.

Note If you import a multiple-sheet worksheet file, Domino importsonly the sheet that was open when the file was last closed, or, ifimporting a specified range, imports the range from that sheet.

11. (Optional) Select “Calculate fields on form during document import.”

12. Click OK.

After importing, you can change the column font to a proportional spacefont, such as Courier, in the view design pane to improve the display ofworksheet data.

Importing tabular textTabular text is ASCII text arranged in rows and columns, separated bycharacters. When you import a tabular text file into a view, each text rowbecomes an individual document, and each text column becomes a field.The original cell contents become field contents.

There is a limit of 1536 total characters per record when importing tabulartext into a view.

If the ASCII file and the view have different formats, create a columndescriptor file (.col) to parse the ASCII file so its individual componentscorrespond to columns in the view or document fields. Then when you

Appendix B: Importing to and Exporting from Views 445

import the ASCII file, select the “Use format file” option in the Tabular TextImport dialog box.

Viewing imported textASCII text files are monospaced. If columns in the view use a proportionalfont, text from the imported file may be truncated. To avoid problems whenimporting text into a view, select Typewriter Fonts (monospaced text) forthe columns. You may want to resize columns to be sure the data is nottruncated on import. Truncation occurs only in the displayed text; no data islost.

Importing tabular text into a viewThe source file containing the tabular text file must be on your local harddrive or on a file server to which you are connected.



3. Select Tabular Text.


5. Click Import.

6. Select a form to use for the imported source data from the Use Formlist.

7. (Optional) Enter a Header Line Count or a Footer Line Count.

8. Enter the number of Lines Per Page in the source file.

9. Leave Main Document(s) selected in the “Import as” list, unless you arecreating response documents.

10. (Optional) Select “Calculate fields on form during document import.”

11. (Optional) Select “Use format file,” click “Choose format file,” andselect a column descriptor (.col) file.

12. Click OK.

Header Line Count; Footer Line CountTo import only the data, specify the number of header and/or footer linesthat you want Notes to ignore in the source file.

Lines per PageThe “Lines per Page” setting establishes how many lines of data each Notesdocument receives. The total number of lines in the imported documentsare calculated as:

Lines Per Page - (Header Line Count + Footer Line Count)


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 thetext file must correspond to the field names in a Notes document in theview. To do this, create a form that contains the names of the fields you’reimporting.

Importing structured text into a viewThe source file containing the structured text file must be on your local harddrive or on a file server to which you are connected.



3. Select Structured Text.


5. Click Import.

6. Select a form to use for the imported source data from the Use Formlist.

7. Select an Inter-Document Delimiter to determine how to separate therecords.

Select Form-feed if the records in the source file are separated by aform feed (ASCII 12).

Select Character Code if the records in the file are separated by adelimiter other than the default, ASCII (form-feed).

8. Leave Main Document(s) selected in the “Import as” list unless you arecreating response documents.


Select Justify in the “For body text” list to wrap text to fit the Noteswindow

Select Preserve Line Breaks in the “For body text” list to maintain theexisting line breaks in the source file and add a return character atthe 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 instructionsfor mapping each column in a source file into the fields and columns of aNotes view. .col files are for use only with tabular ASCII files andworksheet 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 toimport each column from the source file.

3. Write formulas in a section that is delimited by the keywordsFORMULASTART and FORMULAEND.

4. Close and save the file.

Using a column descriptor file (.col) to map a source file to a Notes viewTo import many files that have an identical structure into a view, create acolumn format descriptor (.col) file. A .col file is like a map that defineswhich data from the source file goes into which Notes field. A .col file is foruse only with tabular text files and worksheet files.

A .col file is an ASCII text file that contains a series of column definitionstatements, followed by a section containing formulas that control thecontents of fields in the Notes view. You write one statement for eachcolumn in the source file. This statement describes how to format and mapthe 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 viewEnter the name of the column in the source file. The name should beidentical to the name of the corresponding field in a form. After you enterthe column name, you can provide an optional statement that specifies thedata type of the data. You must, however, provide statements that definethe 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, Notesimports the data for those fields, but the data won’t appear in the form orview until you create Notes field names that exactly match those in the .colfile. For example, if the .col file uses the field name “Phone” and the Notesview uses “PhoneNumber,” data for the “Phone” field is present in theview but is not displayed. To correct this problem, change the name of theexisting 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 viewyou’re using.

Specifying the data type of a columnWhen you import a file, Notes automatically determines the datatype ofeach column, based on the appearance of the data. For example, if thecolumn in the source file contains data in the form 7/19/97, Notes importsthe data as dates.

As part of a field definition, you can provide an optional TYPE expression,followed by the appropriate data type: Text, Number, or Datetime. Forexample, to import the contents of a field called DateOfBirth as a date, enterthe following field definition into the .col file:

DateOfBirth: TYPE DATETIME

The data in the source column must fit the datatype you specify. If Notesencounters data that doesn’t match the datatype you specify, Notes importsthe data as the type it most resembles.

GuidelinesThe formulas that you write in a .col file describe how to modify theincoming values for display in the view. These formulas, which follow thesame rules as view selection formulas, may perform such operations as:

Use @If formulas to test incoming values and display a specific value inthe view, depending on the result of the formula

Use text manipulation functions to modify the appearance of theincoming value; for example, to concatenate values or trim excess space characters from incoming values

Enter default values in fields

Writing a .col file for a worksheetTo import worksheets using .col files, use these keywords:

WKSCOLThis keyword allows you to associate a field name with a specific worksheetcolumn. The syntax for a statement using this keyword is:

fieldname: WKSCOL columnletter


Where:

fieldname is the name of the field in the view.

columnletter is the letter of the source column in the worksheet thatmaps to that field name.

Only columns specified by the WKSCOL keyword will be imported.

RANGEThis keyword specifies the worksheet range to be imported. The syntax fora statement using this keyword is:

RANGE rangename

Where:

rangename is the name of the range in the worksheet.

The range must be a valid range name in the imported file.

If you use a RANGE statement, the first WKSCOL statement in the .col filemust refer to the first column in the range. For example, if the range startsat 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 nameentered in the Worksheet Import Settings box.

Writing a .col file for a tabular text fileTabular text is ASCII text arranged in rows and columns, separated byspace characters.

Specifying the delimiter of a columnIf 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 eachfield 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 ofthe last field as a null (“”).

Specifying the start, end, and width of a fixed-width columnIf the tabular text file contains fixed-width columns of data, you use theSTART keyword along with either the END or WIDTH keyword to defineeach field.

For example, if the source data contains a LastName field that is twelvecharacters 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 andallows 12 characters for it. The second line specifies that the data type of theFirstName field is text, begins the contents of the field at position 13, andallows 8 characters for it.

Specifying the header, footer, and lines per pageThe HEADER, FOOTER, and LINESPERPAGE keywords tell Notes toignore headers and footers during importing. The number of lines in theimported document are calculated as:

LinesPerPage - (HeaderLines + FooterLines)

For example, the following line of a .col file tells Notes to ignore fourheading lines and one footer line and sets the maximum number of lines per page to 66:

HEADERLINE 4 FOOTERLINE 1 LINESPERPAGE 66

The keywords may appear together or alone on a line in the file. Thesesettings 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 definitionstatements. A .col file can have only one FORMULASTART andFORMULAEND sequence. FORMULASTART must appear alone on a linebefore the first formula. FORMULAEND must appear alone on a line afterthe last formula. Each line of formulas between these keywords must endwith a semicolon.

ExampleThe following .col file is used to import a 1-2-3 .WK3 file that records acheckbook balance.

;COL file for checkbook worksheet;Discovers checkbook errorsDefine five columns of inputdate: WKSCOL Achknum: WKSCOL Bamount: WKSCOL Cdeposits: WKSCOL Fwithdrawals: WKSCOL Gbalance: WKSCOL K;Define one column to mark bounced checksFORMULASTARTFIELD bounced:=@IF(balance<0,"Yes"; "No");FORMULAEND

In this example, columns D, E, H, I, and J in the worksheet are not importedinto the view.

Exporting views

You can export a view to a worksheet, a tabular text file, or a structured text file.

Exporting to a worksheetWhen you export a view to a worksheet, each document becomes a row inthe worksheet. Each field becomes a column in the worksheet. The originalfield contents become cell contents. Column titles become labels in theworksheet.


When you export a view to a new worksheet file, Notes exports the file in1-2-3 .wk1 format. Although you can specify any extension with the filename, it’s best to keep the extension .wl1. When you open the exported filein a newer release of 1-2-3, 1-2-3 automatically converts the file to its newformat and adds the appropriate extension.

If you change the exported file to .wk2, .wk3, or .wk4 before opening it in arelease of 1-2-3 that uses that extension, then open the file in 1-2-3 andattempt to add and save attributes, the new copy of the file will be inconflict 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 fileWhen you export a view to a tabular text file, each document becomes a text row (line). Each field becomes a text “column,” separated by spacecharacters. The original field contents become the “cell” contents. To see theseparation between columns in the exported view, use a monospaced fontfor the columns in the original view.

The result of a tabular export may not look exactly like the view. Views usea proportionally spaced font, but exports use a monospaced font. Export afew documents as a test. Then, if necessary, adjust the column widthsettings in the view before you perform the whole export.

To display or edit the contents of a view in a Notes document, export theview to a tabular text file. Then import the tabular text file into a Notesdocument.

Exporting to a structured text fileStructured 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 allthe documents in the view, minus any rich text attributes.

To export a view1. 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.



To replace an existing file, select a directory and file name from the list.

To create a new file, enter a new file name.

To append to an existing tabular text file, select a directory and filename from the list.

6. Click Export.

7. If you selected an existing file, do one of the following:

To replace the file, click Replace.

To append to an existing file, click Append.

8. Click “All documents” unless you selected specific documents in Step 2.

9. (Optional, for 1-2-3 worksheet or tabular text formats) Select “IncludeView titles” to export the view’s column headings to a worksheet ortabular text file.

10. (Optional, for structured text format) Change the inter-documentdelimiter and word-wrap settings if you are exporting to a structuredtext file.

11. Click OK.

Note In step 10, choose Form Feed to use a form-feed to separate recordsin the file, or choose Character Code to separate the records in the file withthe ASCII code for a delimiter other than the default, ASCII 12 (form-feed),such as:

32 Space

44 ,

45 -

58 :

59 ;

124 |

The word wrap option represents the number of characters at which eachline wraps. The default is 75 characters.


Appendix CDeveloping Applications Using MAPI

This appendix describes the support available in Domino to access yourDomino mail file and the Domino Directory.

Developing applications using MAPI

Domino Release 5.0 supports the messaging application program interface (MAPI), which allows mail integration between Domino and aMAPI-compliant messaging application, such as Microsoft Mail orMicrosoft Exchange. The Domino MAPI service providers may be used byany extended or simple MAPI client.

To support MAPI, Domino includes these service providers, which provideaccess from the Domino message, directory, and transport services tosimple or extended MAPI clients:

Address Book provider

Message Store provider

Message Transport provider

Using the MAPI classes and methods supported by the Domino MAPIservice providers, you can write C++ programs to integrate Domino with aMAPI-compliant mail system.

A list of supported MAPI classes and methods appear at the end of thisappendix.

The Address Book providerThe Address Book provider provides read-only access to the DominoDirectories. Therefore, you cannot create individual or group entries in aDomino Directory.

To specify that the provider search multiple Domino Directories whendoing address lookups, set the NAMES= setting in the NOTES.INI file toinclude the file names of all of the Domino Directories to search. Also, addthe names of the Domino Directories for Options - Addressing duringMicrosoft Exchange profile setup.

455

The Address Book provider searches the Domino Directory for recipients’names according to the order specified in the profile.

Any Simple or Extended MAPI client can use the Address Book provider toaccess a Domino mail file and Domino Directory.

The Message Store provider

The Message Store provider, which you can use as the default MAPIMessage Store, is a tightly-coupled message store. That is, the MessageStore provider, rather than the Message Transport provider, handles thedelivery of messages when a recipient is a Notes user. Also, messages aresent using calls to the Message Store Message Interface rather than theMAPI Spooler.

MAPI creates an Outbox folder the first time the Domino Message Store isaccessed. The Outbox folder captures outgoing messages you send fromany extended or simple MAPI client (for example, Microsoft Exchange orOffice) when you are not connected to the LAN. Messages addressed toNotes recipients are stored in the Outbox folder and placed in the localmail.box database in Domino. Once a connection to the server isre-established, the messages are transferred. Messages addressed tonon-Domino recipients are placed in the outgoing mail queue, theexchange.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 fileattachments in messages you compose while using the client application.Attachment data is set or obtained using the IStream or IStorage interfaces.RTF, message encryption, and message signing is supported.

Complex restrictions, MAPI associated messages and folders, viewdefinition, and arbitrary message sorting are not currently supported.


The Message Transport provider

The Domino Mailer and Router transfers messages between Notes users.When the MAPI spooler receives messages composed in a non-Notesmessage store, the Domino MAPI Message Transport provider registersAddress and Message Types and sends messages to Notes recipients. If oneor more recipients are not of ADDRTYPE Notes, the Mail Router passes themessages to the MAPI spooler.

MAPI recipient types

Domino MAPI service providers handle delivery of messages to thefollowing recipient types:

Users who access their Domino mail files through a simple or extendedMAPI client, such as Microsoft Exchange

Non-Notes users who access their non-Domino mail files through asimple or extended MAPI client, such as Microsoft Exchange

Notes users who access their Domino mail files from the Notes desktop

Users of foreign mail systems that use a gateway as a backend

Platforms and requirements for MAPI

Windows 95When you install the Notes client, the Domino MAPI service providers areautomatically installed. The required DLLs for the Windows messagingsubsystem are already present in Windows 95.

Windows NT 3.51The Domino MAPI service providers are available for Windows NT 3.51.Since Windows NT 3.51 does not provide the Windows messagingsubsystem, you must install the subsystem separately.

Windows NT 4.0The Domino MAPI service providers are available for Windows NT 4.0. Therequired DLLs for the Windows messaging subsystem are already presentin Windows NT 4.0.

Note The Domino MAPI service providers can be installed and used fornode installations on all of these platforms.

Appendix C: Developing Applications Using MAPI 457

MailThe Domino MAPI service providers may only be used to access mail filesthat use the Domino Release 5.0 mail template (mail50.ntf). If you areupgrading from Release 4.x to Release 5.0, you must upgrade your mail fileto use the mail template provided in Release 5.0. To use the serviceproviders, both the client and the server must be running Release 5.0.

The Profile Setup Wizard automatically installs all three service providers.When you create a Microsoft Exchange Profile, the wizard uses informationstored in the current Location document in Domino. You makemodifications to the Office (Network) Location document to configure thelocation for server-based mail. To use workstation-based mail, you modifythe Travel or Island (Disconnected) Location document appropriately. Notethat the Location type in the document must be either Local Area Networkor No Connection. The Mail section of the location document must specifyinformation about the mail file location, the name of the mail file, and thedomain.

Note During logon to the service providers, the settings forMDB_NO_DIALOG and AB_NO_DIALOG flags are ignored. As a result,the user is always prompted for a password.

Address Book templateTo access Domino Directories through the Address Book Provider, youmust apply the Domino Release 5.0 Domino Directory template(pubnames.ntf) to the design. If you are using workstation-based mail,apply the Personal Address Book template (pernames.ntf) to the design ofthe Personal Address Books.


MAPI classes and methods

MAPI classes Supported methods

CLASSIMAPIContainer

GetContentsTableGetHierarchyTableOpenEntryGetSearchCriteria

CLASS IABLogon AdviseCompareEntryIDsGetLastErrorLogoffOpenEntryUnadvise

CLASS IABProvider LogonShutdown

CLASS IMAPIControl ActivateGetLastErrorGetState

CLASS IMAPIFolder CopyMessagesCreateFolderCreateMessageDeleteFolderDeleteMessagesEmptyFolderGetMessageStatusSaveContentsSortSetMessageStatus

CLASS IMAPIProp CopyToGetIDsFromNamesGetLastErrorGetPropListGetPropsOpenPropertySaveChangesSetPropsDeleteProps

continued



CLASS IMAPITable AbortAdviseCreateBookmarkFindRowFreeBookmarkGetLastErrorGetRowCountGetStatusQueryColumnsQueryPositionQuerySortOrderRestrict (supported for Address Book Provider, but notfor Message Store Provider)SeekRowSeekRowApproxSetColumnsUnadvise

CLASS IMessage CreateAttachDeleteAttachGetAttachmentTableGetRecipientTableModifyRecipientsOpenAttachSetReadFlagSubmitMessageNote Message object based on Notes note, notMAPI-supplied IMSG.DLL OLE Docfile representation.

CLASS IMsgStore AbortSubmitAdviseCompareEntryIDsFinishedMsgGetOutgoingQueueGetReceiveFolderNotifyNewMailOpenEntrySetLockStateSetReceiveFolderStoreLogoffUnadvise

continued



CLASS IMSLogon AdviseCompareEntryIDsGetLastErrorLogoffOpenEntryUnadvise

CLASS IMSProvider CompareStoreIDsLogonShutdownSpoolerLogon

CLASS IXPLogon AddressTypesEndMessageFlushQueuesIdle (supported, but not used for tightly-coupledmessage store)OpenStatusEntryPoll (supported, but not used for tightly-coupledmessage store)RegisterOptionsStartMessage (supported, but not used fortightly-coupled message store)SubmitMessageTransportNotify

CLASS IXPProvider ShutdownTransportLogon

CLASS IMailUser All methods supported for this class

CLASS IAttach All methods supported for this class

CLASSIMAPIAdviseSink

All methods supported for this class

CLASS IMAPIProfile All methods supported for this class

CLASSIMAPIContainer

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


Appendix DFeatures to Avoid Using in Web Applications

The majority of design features are available for both Domino and Webusers. This appendix describes the features that aren’t applicable to Webbrowsers or aren’t yet supported for them.

Domino @functions that are not supported on the Web

The following groups of @functions are not supported in Web applicationsor 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 aview. Not available in other contexts.

@DDEExecute@DDEInitiate@DDEPoke@DDETerminate

@DocMark@DeleteDocument

@DocChildren@DocDescendants@DocLevel@DocNumber@DocParentNumber@DocSiblings

Not available except in column formulas.

@IsCategory@IsExpandable@Responses

continued

463

@Function Comments

@DialogBox@PickList@Prompt@IsModalHelp

@GetPortsList

@Environment@SetEnvironmentENVIRONMENT keyword

Use predefined field names to gather informationabout the Web user’s environment by requestingCommon Gateway Interface (CGI) environmentvariables.

@MailSend

@Domain@MailDbName@MailEncryptSavedPreference@MailEncryptSendPreference@MailSavePreference@MailSignPreference

@IsAgentEnabled

@IsDocBeingMailed

@URLGetHeader@URLHistory

@UserPrivileges

@Platform for user’s platform. Returns server’s platform only. Use @ClientTypeto distinguish between Web and Domino users.

Domino actions and agent properties that are not supported on the Web

Avoid using the following actions and agent features in a Web application.

Feature Comments

Agents

Manually From Actions Menu Web users do not have an Actions menu. Runagents with actions or buttons that use@Command([ToolsRunMacro]) or throughthe WebQuerySave and WebQueryOpen formevents.

“If Documents Have Been Pasted”and the document selection option“Selected documents”

The concepts of “pasted documents” and“selected documents” don’t apply to Webapplications.

continued


Feature Comments

Form and view actions

Include action in Action menu Web users do not have an Actions menu. Usethe option “Include action in button bar”instead.

Default form and view actions thatuse system commands (such as*Edit Document, *Categorize)

Use supported @commands to create theequivalent actions.

Programs for actions and agents

Simple actions

LotusScript for forms, actions, andbuttons

Supported for agents only.

“Alias a folder” simple action Dragging and dropping to folders is notavailable on the Web.

Domino calendar features that are not supported on the Web

Avoid using these calendar features in a Web application.

Feature Comments

Embedded Group Scheduler

Calendar pop-up controls

Date Picker

Time control

Duration control

Domino field properties that are not supported on the WebAvoid using the following field features in a Web application.

Feature Comments

Notes/FX fields

Field Info properties

Compute after Validation

Give this field default focus

Control properties

Options Display entry helper button is not supported.

continued

Appendix D: Features to Avoid Using in Web Applications 465

Feature Comments

Advanced properties

Help description

Enable encryption for this field Web users cannot read data in encryptedfields.

Sign if mailed or saved in section

Names fields

Control properties

Choices (for Names fields) “Use Address dialog for choices,” “UseAccess Control List for choices,” and “UseView dialog for choices” are not supported.Web user access to databases is based on theauthenticated name.

Checkbox fields

Checkbox selection order For some browsers, the order of the datareturned from multiple selections in acheckbox may be different from the selectionorder. The data itself remains the same, butthe order returned is different.

Domino form properties that are not supported on the Web

Avoid using the following form features in a Web application.

Feature Comments

Form Info properties

Versioning

Anonymous forms

Merge replication conflicts

Store form in document - edit mode Read mode is supported, but do not use fordocuments that need to be created or editedon the Web.

Disable field exchange

Automatically refresh fields

continued


Feature Comments

Default properties

On Create: Inherit entire selecteddocument into rich text field — “asLink” and “as Collapsible rich text”

This applies to rich text fields only.On Create may be used for textfields on the Web.

Inheritance from selected documents issupported on the Web, but only if the field isof type text, the document resides in the samedatabase, and the database property, “WebAccess: Use JavaScript when generatingpages” is selected.

Inherit entire selected document into rich textfield “as rich text” is supported.

On Open: Show context pane

Security properties

Default encryption keys Not applicable to Web.

Disable printing/forwarding/copying to clipboard

Form elements

Layout regions Use tables to align form components instead.

Pop-up hotspots

ActiveX components, OLE, andOCX objects

Not supported on Macintosh, UNIX, andOS/2 platforms. Supported for display onWindows NT and Windows 95 platforms, butusers can’t save changes made to objects.

Border controls for tables If the top left cell of a table has a border, theentire table is displayed with a border;otherwise, there is no border because oflimitations with HTML.

Domino formatting features that are not supported on the WebAvoid using the following formatting features in Web applications.

Feature Comments

Bullet character in an ordered list(sizing and color)

The color and size of a bullet in an ordered listcannot be manipulated on the Web.

International characters The international characters that aresupported on the Web vary depending on thebrowser version and the fonts installed on theplatform used to view and edit text on theWeb.

continued


Feature Comments

First-line indent or outdent in aparagraph

Full justification paragraphalignment

Images Avoid this feature if editing a document withboth the Notes client and the editor applet.

Ordered lists Avoid this feature if the list will be edited inthe Notes client and the editor applet.Ordered lists are supported if they are editedwith the editor applet only.

Pasting text There are limitations for pasting text in theeditor applet. See Designing Fields forinformation about using the editor applet forediting rich text fields on the Web.

Tabs

Tables Avoid this feature if editing a document withboth the Notes client and the editor applet.

Unordered lists Avoid this feature if the list will be edited inthe Notes client. Unordered lists aresupported if they are edited with the editorapplet only.

Domino frame properties that are not supported on the WebAvoid using this frame feature in a Web application.

Feature Comments

Basics properties

Default target for links in frame Targets may be set in both the Frameproperties box and the design elementcontained by that frame. The design elementin this case may be a form, page, or view. If atarget is set in the Frame properties box of aWeb application, but not in the designelement, and the design element is laterreplaced, the links in the frame will not go tothe target specified in the Frame properties.This can be avoided by specifying the sametarget frame in both the Frame properties andthe design element.


Domino horizontal rule properties that are not supported on the Web

Avoid using the following horizontal rule feature in a Web application.

Feature Comments

Horizontal Rule Info properties

Color Gradient is not supported on the Web.

Domino hotspot properties that are not supported on the Web

Avoid using the following hotspot feature in a Web application.

Feature Comments

Hotspot Info properties

Show border around hotspot

Domino navigator properties that are not supported on the Web

Avoid using the following navigator features in a Web application.

Feature Comments

Navigators

Info properties

Auto adjust panes at runtime

Objects

Polyline objects Polyline objects display on the Web, butclicking them has no effect.

HiLite properties

Highlight when... options fornavigator objects


Domino table properties that are not supported on the Web

Avoid using the following table features in a Web application.

Feature Comments

Table Layout properties

Column spacing This property is not supported in Webapplications, but may affect the Widthproperty of a cell, which is supported on theWeb.

Minimum height

Row spacing

Table Width Same as window is ignored in a Webapplication.

Cell Borders properties

Color Cells are the same color as the table.

Cell Border Style The style options, Ridge and Groove, are notsupported on the Web.

Cell Border Thickness Border thickness settings greater than 1 arenot supported.

Table/Cell Background properties

Style Solid is the only color option supported on theWeb. Gradients will appear as the first color.

Cell image

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

Right

Table wrap

Compatibility

Table Rows properties

Show only one row at a time Switch rows every n milliseconds andtransitions are not supported.


Domino text styles that are not supported on the Web

Avoid using the following text features in a Web application.

Feature Comments

Font properties

Default fonts (Helvetica and TimesRoman in Windows).

Alignment and Tab properties

Full Justification and No Wrapalignment styles

Interline spacing A line spacing which is not a whole numberwill be rounded up to the nearest wholenumber. For example, a line spacing of 1.5will be rounded up to 2.

Formatting aids, such as tabs,indents, outdents, and extra spaces

HTML doesn’t support these formattingstyles. Use tables to align form components.Use the text style Pass-Thru HTML to useHTML formatting styles.

Text effects properties

Shadow, Emboss, and Extrude text styles

Domino view properties that are not supported on the Web

Avoid using the following view and folder features in a Web application.

Feature Comments

Views and folders

Folders Private folders are not supported in outlineson 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 tohide the view from Web users, or include theview name in parentheses — for example,(HiddenView).

continued


Feature Comments

On Open: Go To... options

On Refresh options

Style properties

Unread rows

Alternate rows

Show selection margin

Beveled headings

Advanced properties

Refresh index options

Discard index options

Views can be re-indexed at a Domino server.

Columns

Basics properties

Show twistie when row isexpandable

Triangles are always shown.

View properties that are not supported by the Domino view appletAvoid using the following Domino view applet features in a Webapplication.

Feature Comments

Pass-Thru HTML

Horizontal scrollbars

View

View Info properties

Calendar views Calendar views are not supported. The HTML Calendarview will be generated even if view applet is selected.

Options properties

On open: Go to lastopened document

On Refresh None of these options are supported.

Style properties

Unread rows color

Alternate rows color

continued


Feature Comments

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 indexbuild to designer ormanager

Column

Font properties The available fonts are limited to a subset of fontssupported by Java.

Title properties

Font The available fonts are limited to a subset of fontssupported by Java.

Advanced properties

Show values in thiscolumn as links


Appendix EProgramming a Web Site

This appendix contains information about programming related to Webapplications, such as Domino URL commands, formulas, Java, JavaScript,Perl and CGI scripting, and Visual Basic script.

Domino URL Commands

A URL command combines a specific URL with a command thatmanipulates an item such as a document or view. Adding Domino URLcommands as HTML in forms gives users shortcuts for navigatingdatabases and performing other tasks quickly.

The Domino URL command syntaxDomino URL commands have the syntax:

http://Host/DominoObject?Action&Arguments

Where

Host = a DNS entry or an IP address

DominoObject = a Domino construct (For example, a database, view,document, form, navigator, agent, and so on.) URL commands foraccessing DominoObjects use the following syntax:http://Host/Database/DominoObject?Action&Arguments where Database =the database in which the DominoObject resides.

Action = the desired operation on the specified DominoObject (For example, ?OpenDatabase, ?OpenView, ?OpenDocument,?EditDocument, ?OpenForm, and so on.)

Arguments = a qualifier of the action. (For example, Count = 10combined with the ?OpenView action limits the number of rowsdisplayed in a view to 10.)

Syntax GuidelinesDomino URLs do not use the server name. Host identifies the server.

The maximum size of a URL command is 1024 bytes.

475

Special identifiers used in Domino URL commands include:$defaultView, $defaultForm, $defaultNav, $searchForm, $file, $icon,$help, $about, and $first.

DominoObject can be any of the following: for a database, the databasename or replica ID; for other objects, the DominoObject’s name,universal ID, NoteID, or special identifier. For example, to specify aview in a URL, you can use any of the following: the view name, viewuniversal ID, view NoteID, or $defaultView.

A Notes database should be specified by placing a double underscorebefore the replica ID and adding an .nsf suffix to the end. For example:__852562F3007ABFD6.nsf

A DominoObject’s name and universal ID are identical in all replicas ofa database, but the DominoObject’s NoteID will probably change indatabase replicas. Therefore, it is best to use the DominoObject name oruniversal ID in URLs. One name or alias can refer to two objects — forexample, two forms with the same name when one is hidden fromNotes users and one is hidden from Web users.

Action can be explicit or implicit. Examples of explicit actions include?OpenServer, ?OpenDatabase, ?OpenView, ?OpenDocument,?OpenForm, and ?EditDocument. Examples of implicit actions include?Open, ?Edit, and ?Delete. If you do not specify an action, Dominodefaults to the ?Open action. An action may also be preceded by anexclamation point (!). For example, ?OpenDocument could also bewritten as !OpenDocument.

When Domino is running as an extension to Microsoft InternetInformation Server, a database is required in the URL syntax for servercommands such as ?OpenServer, ?Login, ?Logout, and ?Redirect. Youmay use the name of a database that does not exist in order to supplythe correct sytnax without opening a database. For example:http://www.mercury.com/dummy.nsf?Login

To require user authentication, append the Login argument to anyDomino URL.

Because URLs cannot contain spaces, use the + (plus sign) as aseparator. For example:http://www.mercury.com/discussion.nsf/By+Author

Where a name or argument contains a symbol that is not part of the URL syntax and would conflict with URL syntax, such asplus signs (+), slashes (\ or /), or ampersands (&), use %xx (where xx is the hex ascii value) as a separator. For example:http://www.mer%+maid.com/leads.nsf/By+Salesperson?OpenView&ExpandView


Separate arguments with & (ampersand). For example:http://www.mercury.com/leads.nsf/By+Salesperson?OpenView&ExpandView

Separate hierarchical names with / (slash). For example, to open a viewnamed Docs\By Author in a database named Discussion, enter:

http://www.mercury.com/discussion.nsf/Docs/By+Author

If you are generating your own URLs for any part of an application, usesimple aliases whenever possible to avoid URLs with unsupportedcharacters. Domino will convert URLs containing unsupportednon-ascii characters to base32 encoding.

URL commands may also refer to databases with .nsf4 or .box suffixes.They may also refer to template files (.ntf), but they may only beopened in preview mode.

Selecting “Web access: Use JavaScript when generating pages” inDatabase properties will enable you to compute URLs attached tobuttons and hotspots on the Click event. If this option is not selected,URLs attached to buttons and hotspots will be computed when thepage is generated. This 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 ThisDatabase documents, Help documents, and database icons. Databases mustbe in the notes\data directory or a subdirectory of the notes\data directoryin order to be accessed by a URL command, except in the case of servercommands such as ?OpenServer, ?Login, ?Logout, and ?Redirect. You mayuse the name of a database that does not exist in the server commandsyntax if a database is required, as it is with Microsoft Internet InformationServer. If the database referenced in a server command does not exist, itwill be ignored. Use ?Redirect to redirect doclinks across servers. Hiddendesign elements are hidden from the server too; you can’t use Domino URLcommands to access documents in hidden views.

OpenServerSyntaxhttp://Host/?OpenServer

http://Host/Dummy.nsf?OpenServer

Appendix E: Programming a Web Site 477

Examplehttp://www.mercury.com/?OpenServer

http://www.mercury.com?dummy.nsf?OpenServer

RedirectSyntaxhttp://Server/Dummy.nsf?Redirect&Name=notesserver&Id=To=encodedurl

Where:

http://Server refers to the Web server which is generating the URL.

Name=notesserver specifies a Domino server name in its common orabbreviated form. This is optional when the “By Database” setting onthe server is on.

ID=repid indicates the replica ID of the database to be located. This isan optional argument.

To=encodedurl specifies the rest of the URL.

Examplehttp://mercury.com/dummy.nsf?Redirect&Name=Mister%2FHankey&Id=0525666D0060ABBF&To=%FAView%3FOpenView

OpenDatabaseSyntaxhttp://Host/DatabaseFileName?OpenDatabase

http://Host/__DatabaseReplicaID.nsf?OpenDatabase

Exampleshttp://www.mercury.com/leads.nsf?OpenDatabase

http://www.mercury.com/sales/discussion.nsf?OpenDatabase

http://www.mercury.com/__852562F3007ABFD6.nsf/OpenDatabase

OpenViewSyntaxhttp://Host/Database/ViewName?OpenView

http://Host/Database/ViewUniversalID?OpenView

http://Host/Database/ViewNoteID?OpenView

http://Host/Database/$defaultview?OpenView


Exampleshttp://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 OpenViewAppend optional arguments to refine the URL. Combine any of thefollowing arguments for the desired result.

Collapse = n Where:

n is the row number to display in collapsed format in a hierarchicalview. Do not combine this argument with the ExpandView orCollapseView 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 hierarchicalview. Do not combine this argument with the ExpandView orCollapseView arguments.

ExpandView Displays the view in expanded format

Start = n Where:

n is the row number to start with when displaying the view. The rownumber 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 thatdocument.

Exampleshttp://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&CollapseView

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&ExpandView

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&Start=3&Count=15

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&StartKey=F

OpenAboutUse the OpenAbout command to access the About This Databasedocument.

Syntaxhttp://Host/Database/$about?OpenAbout

Examplehttp://www.mercury.com/leads.nsf/$about?OpenAbout

OpenHelpUse the OpenHelp command to access the Using This Database document.

Syntaxhttp://Host/Database/$help?OpenHelp

Examplehttp://www.mercury.com/leads.nsf/$help?OpenHelp


OpenIconUse the OpenIcon command to access the database icon.

Syntaxhttp://Host/Database/$icon?OpenIcon

Examplehttp://www.mercury.com/leads.nsf/$icon?OpenIcon

URL commands for opening framesets

OpenFramesetSyntaxhttp://Host/Database/FramesetName?OpenFrameset

http://Host/Database/FramesetUNID?OpenFrameset

http://Host/Database/FramesetNoteID?OpenFrameset

Exampleshttp://www.mercury.com/discussion.nsf/main?OpenFrameset

http://www.mercury.com/discussion.nsf/35AE8FBFA573336A852563D100741784?OpenFrameset

URL commands for opening agents, forms, and navigatorsThe following commands open agents, forms, and navigators in a database.Hidden design elements are hidden from the server too; you can’t useDomino URL commands to access documents in hidden forms.

OpenAgentSyntaxhttp://Host/Database/AgentName?OpenAgent

Exampleshttp://www.mercury.com/sales/leads.nsf/Process+New+Leads?OpenAgent

Note Agents may only be referred to by name. The use of UNID andNoteID are not supported when referring to an agent.


OpenFormSyntaxhttp://Host/Database/FormName?OpenForm

http://Host/Database/FormUniversalID?OpenForm

http://Host/Database/FormNoteID?OpenForm

http://Host/Database/$defaultform?OpenForm

Exampleshttp://www.mercury.com/products.nsf/Product?OpenForm

http://www.mercury.com/products.nsf/625E6111C597A11B852563DD00724CC2?OpenForm

http://www.mercury.com/products.nsf/$defaultform?OpenForm

Optional argument for OpenFormParentUNID = UniqueIDNumber

Where:

UniqueIDNumber is document ID of the parent document, which is usedin response forms or when the form property “Formulas inherit valuesfrom selected document” is selected.

Syntaxhttp://Host/Database/FormUniversalID?OpenForm&ParentUNID

Examplehttp://www.mercury.com/products.nsf/40aa91d55cle4c8285256363004dc9e0?OpenForm&ParentUNID=6bc72a92613fd6bf852563de001f1a25

OpenNavigatorSyntaxhttp://Host/Database/NavigatorName?OpenNavigator

http://Host/Database/NavigatorUniversalID?OpenNavigator

http://Host/Database/NavigatorNoteID?OpenNavigator

http://Host/Database/$defaultNav?OpenNavigator

$defaultNav opens the folders pane in a database.


Exampleshttp://www.mercury.com/products.nsf/Main+Navigator?OpenNavigator

http://www.mercury.com/products.nsf/7B5BC17C7DC9EB7E85256207004F8862?OpenNavigator

http://www.mercury.com/products.nsf/$defaultNav?OpenNavigator

ReadFormUse the ReadForm command to display a form without showing its editablefields. ReadForm is useful for displaying a form as a simple Web page.

Syntaxhttp://Host/Database/FormName?ReadForm

http://Host/Database/FormUniversalID?ReadForm

http://Host/Database/FormNoteID?ReadForm

http://Host/Database/$defaultform?ReadForm

Exampleshttp://www.mercury.com/home.nsf/Welcome?ReadForm

http://www.mercury.com/products.nsf/625E6111C597A11B852563DD00724CC2?ReadForm

http://www.mercury.com/products.nsf/$defaultform?ReadForm

URL commands for creating, deleting, editing, opening, and savingdocuments

The following commands manipulate documents in a database. Hiddendesign elements are hidden from the server, too; you can’t use Domino URLcommands to access documents in hidden views.

CreateDocumentThe CreateDocument command is used as the POST action of an HTMLform. When the user submits a form, Domino obtains the data entered inthe form and creates a document.

Syntaxhttp://Host/Database/Form?CreateDocument

http://Host/Database/NoteID?CreateDocument

http://Host/Database/FormName?CreateDocument


Where:

FormName is the name of the form being accessed.

Exampleshttp://www.mercury.com/products.nsf/b9815a87b36a85d9852563df004a9533?CreateDocument

http://www.mercury.com/products.nsf/basketballs?CreateDocument

DeleteDocumentSyntaxhttp://Host/Database/View/Document?DeleteDocument

Examplehttp://www.mercury.com/products.nsf/By+Part+Number/PC156?DeleteDocument

EditDocumentSyntaxhttp://Host/Database/View/Document?EditDocument

Examplehttp://www.mercury.com/products.nsf/By+Part+Number/PC156?EditDocument

OpenDocumentSyntaxhttp://Host/Database/View/Document?OpenDocument

Where:

Document is any of the following:

DocumentKey — the contents of the first sorted column in the specifiedview.

DocumentUniversalID

DocumentNoteID

$first — the first document in the view

Exampleshttp://www.mercury.com/products.nsf/By+Part+Number/PC156?OpenDocument

http://www.mercury.com/leads.nsf/By+Rep/35AE8FBFA573336A852563D100741784?OpenDocument


SaveDocumentThe SaveDocument command is used as the POST action of a documentbeing edited. Domino updates the document with the new data entered inthe form.

Syntaxhttp://Host/Database/View/Document?SaveDocument

Examplehttp://www.mercury.com/products.nsf/a0cefa69d38ad9ed8525631b006582d0/4c95c7c6700160e2852563df0078cfeb?SaveDocument

URL commands for opening documents by keyThe following commands allow you to open a document by using the keyvalue of the first sorted column of a view, such as a document name, or togenerate a URL to link to a document by key. Hidden design elements arehidden from the server too; you can’t use Domino URL commands to accessdocuments in hidden views, unless you’ve hidden the view by surroundingits name in parentheses, rather than using the Hide tab in the Propertiesbox.

Using Domino URLs to access a documentTo open a document by key, create a sorted view with the sort on the firstkey column. Then use a URL to open the document.

Syntaxhttp://Host/Database/View/DocumentName?OpenDocument

Where:

View is the name of the view. To access a document regardless of theview, specify the document by its universal ID and substitute a zero (0)for the view name.

DocumentName is the string, or key, that appears in the first sorted orcategorized column of the view.

Use this syntax to open, edit, or delete documents and to open attachedfiles. Domino returns the first document in the view whose column keyexactly matches the DocumentName.

There may be more than one matching document; Domino always returnsthe first match. The key must match completely for Domino to return thedocument. However, the match is not case-sensitive or accent-sensitive.


Note that View can be a view Note ID, UNID, or view name. In addition, theimplicit form of any of these commands will work when appropriate. Forexample, you can omit the OpenDocument argument in a URL commandand the document will still open because the command is automaticallyinterpreted as OpenDocument. (EditDocument and DeleteDocument mustbe explicit commands.)

Exampleshttp://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 documentFor information about using @commands in Web applications, seeAppendix D.

Using Domino URLs to access attachmentsWhen Domino saves a file attachment with a document, it generates a URLso it can retrieve the file later. An attachment generates a URL whose lastcomponent 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 aNote ID or a DocumentKey. This allows you to create URL links toattachments 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 pagesThe following command will open a Web page using its name, UNID, orNote ID.

OpenPageSyntaxhttp://Host/Database/PageName?OpenPage

http://Host/Database/PageUNID?OpenPage

http://Host/Database/PageNoteID?OpenPage


Exampleshttp://www.mercury.com/discussion.nsf/products?OpenPage

http://www.mercury.com/discussion.nsf/35AE8FBFA573336A852563D100741784?OpenPage

Optional arguments for OpenPage and OpenDocumentThe following arguments will manipulate outline controls on pages anddocuments. The arguments for OpenPage and OpenDocument commandsuse the same syntax regardless of the command.

CollapseOutline=nWhere

n = the triangle at the top level of the outline. It is possible to expandtriangles in hierarchical order. For example, &CollapseOutline=2.1.3will collapse the second triangle at the top level of the outline, the firsttriangle at the second level, and the third triangle at the third level.

Syntaxhttp://Host/Database/PageName?OpenPage&CollapseOutline=n

http://Host/Database/PageUNID?OpenPage&CollapseOutline=n

http://Host/Database/PageNoteID?OpenPage&CollapseOutline=n

Exampleshttp://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=nWhere

n = the triangle at the first level of the outline. It is possible to expand atriangle in hierarchical order. For example, &ExpandOutline=2.1.3 willexpand the second triangle at the top level of the outline, the firsttriangle at the second level, and the third triangle at the third level.

Syntaxhttp://Host/Database/PageName?OpenPage&ExpandOutline=n

http://Host/Database/PageUNID?OpenPage&ExpandOutline=n

http://Host/Database/PageNoteID?OpenPage&ExpandOutline=n


Exampleshttp://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

StartOutline=nWhere

n = the triangle at the top level of the outline. It is possible to expand atriangle in hierarchical order. For example, &StartOutline=2.1.3 willstart the display with the third triangle at the third level of the outline.

Syntaxhttp://Host/Database/PageName?OpenPage&StartOutline=n

http://Host/Database/PageUNID?OpenPage&StartOutline=n

http://Host/Database/PageNoteID?OpenPage&StartOutline=n

Exampleshttp://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.

OpenElementUse the ?OpenElement command to access attachments, image files, andOLE objects.

Using OpenElement with attachmentsSyntaxhttp://Host/Database/View/Document/$File/Filename?OpenElement

Examplehttp://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 includesboth the “internal” file name as well as the external name. Since the internalfile name is not easily determined, make sure all attached files have uniquenames.

Because some browsers require that the URL end with the attached filename, Domino treats all file attachment OpenElement commands asimplicit commands. For example:

http://Host/Database/View/Document/$File/InternalFileName/Filename?OpenElement

Using OpenElement with image filesSyntaxhttp://Host/Database/View/Document/FieldName/FieldOffset?OpenElement

http://Host/Database/View/Document/FieldName/FieldOffset?OpenElement&FieldElemFormat=ImageFormat

Optional argument for OpenElementFieldElemFormat = ImageFormat

Where:

ImageFormat is either gif or jpeg. If you do not specify FieldElemFormat,Domino assumes the image file format is gif.


Using OpenElement with OLE ObjectsSyntaxhttp://Host/Database/View/Document/FieldName/FieldOffset/$OLEOBJINFO/FieldOffset/obj.ods?OpenElement

Note The current URL syntax for referencing images and objects in Notesdocuments — specifically the FieldOffset — makes it impractical to createthese URLs manually. As an alternative, you may paste the actual bitmap orobject in place of the reference, create URL references to files stored in thefile 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 inputform — either a customized search form or the default search form — to letusers define their own searches, but you may also define a URL thatperforms text searches without user input. Both input and results formsmay be customized.

SearchDomainUse SearchDomain URLs for text searches across a domain. The searchinput form is opened with the OpenForm command by name or universalID. For search results, the results template is specified as part of the URL. If no template is found, then the default template form,$$SearchDomainTemplate, is substituted. If $$SearchDomainTemplate is not found, an error will be returned. If no results are returned, the value of the $$ViewBody field remains the same.

Syntaxhttp://Host/Database/[templateForm]?SearchDomain[ArgumentList]

Where:

templateForm is an optional argument that calls the search results form.

ArgumentList is a list of optional arguments.

Examplehttp://www.mercury.com/mersrch.nsf/MercuryResults?SearchDomain


RedirectThe server will provide a direct or redirect URL command as needed forlinks displayed on the results form if the capability has been enabled. Thedomain URL locates information on the server where the links aregenerated. The redirect command locates the correct server and redirects alink to that server by constructing the appropriate URL. The redirectcommand can improve performance by resolving individual links whenthey are selected instead of resolving all of the links returned at once.

See Domino 5 Administration Help for information about enabling a redirectURL command on a server.

SearchSiteUse SearchSite URLs for text searches in multiple databases. Because theURL requires the name of a search site database, be sure to create onebefore using a SearchSite URL.

Syntaxhttp://Host/Database/[$SearchForm]?SearchSite[ArgumentList]

Where:

$SearchForm and ArgumentList are optional arguments.

Examplehttp://www.mercury.com/mercsrch.nsf/$SearchForm?SearchSite

SearchViewUse SearchView URLs to limit a search to documents displayed in onedatabase view.

This URL is useful for views that display all documents (so you can have afull-database search) or for views in which you can predict what users needto see, such as all documents whose status is “Completed.”

Syntaxhttp://Host/Database/View/[$SearchForm]?SearchView[ArgumentList]

Where:

$SearchForm and ArgumentList are optional arguments. The specialidentifier $SearchForm indicates that Domino will present a search viewform for search input. If this identifier is provided, the ArgumentList isignored. If this identifier is absent, a default form will be generated onthe fly based on the contents of the search.htm file located on the server.The default form generated by the server does not support pagedresults.


Examplehttp://www.mercury.com/products.nsf/By+Product+Number/$SearchForm?SearchView

Optional arguments for SearchSite and SearchView$SearchForm

The special identifier $SearchForm indicates that Domino will present asearch site form for search input. If this identifier is provided, ArgumentListis ignored.

The ArgumentList must contain the Query argument; in addition, it maycontain any or all of the other arguments in any order.

Query = the search string

Count=[n]

Where n is the number of results to display on each page until theSearchMax has been reached. For example Count=10 will display 10 resultsper page.

SearchEntry = the name of the form to use for the results of a domainsearch. The default argument is “ResultEntry,” which supports all of thepre-defined results fields specified in the ArgumentList. This argument isvalid for SearchDomain only and should not be used for SearchSite orSearchView.

SearchFuzzy=[TRUE,FALSE]

Where True = use fuzzy search. The default is FALSE.

SearchOrder=[1,2,3]

Where 1 = “Sort by relevance”, 2 = “Sort by date ascending”, 3 =“Sort bydate descending.” The default is 1.

SearchMax=[n]

Where n is the maximum number of entries returned. The default value isdetermined by the server.

SearchWV=[TRUE, FALSE]

Where TRUE = include word variants in the search. The default value isTRUE.

Start=[n]

Where n is the number corresponding to the document that appears first inyour list of results. For example, Start=10 begins your list of results with the10th document found in the search. Start=0 means that paged results willnot be returned.


Exampleshttp://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 resultsThe following parameters for SearchView and SearchSite URL commandswill allow you to display search results page-by-page and to providebuttons or hotspots to navigate between pages.

Start and Count parametersStart and Count parameters allow you to display search resultspage-by-page and may be included as arguments in the SearchView orSearchSite URL commands or as items in the search results form. The Startparameter is the entry that appears first when your results are displayed.The Count parameter is the number of results that will display on eachscreen. For example, if Start=5 and Count=10, the search results woulddisplay beginning with the 5th entry and would display up to 10 entries perscreen until the maximum number of entries has been displayed. Theseparameters work with customized forms only.

Syntaxhttp://Host/Database/ViewName/[$SearchForm]?SearchView[ArgumentList]

http://Host/Database/ViewUNID/[$SearchForm]?SearchView[ArgumentList]

http://Host/Database/ViewNoteID/[$SearchForm]?SearchView[ArgumentList]

Where:ArgumentList includes the Query argument and any or all of the otherarguments 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.

Exampleshttp://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 Countparameters

If you are using Start and Count parameters you can include Next andPrevious buttons or hotspots to enable users to navigate between pages ofresults. Both parameters must be used if you are using navigational buttons.

1. Open your customized results form and place buttons or hotspotslabeled Next and Previous where you want them to appear on the form.

2. For the button or hotpsot labeled Next, write a formula that willadvance the user forward one page.

3. For the button or hotspot labeled Previous, write a formula that willtake 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; “” ‘ “+”) toreplace all of the spaces in your query with plus signs (+).

URL commands for requiring authentication

Login argumentTo force user authentication regardless of the database access control list,append the Login argument to any Domino URL. This ensures thatanonymous Web users who weren’t initially prompted for a name andpassword when they entered the site are required to supply a name andpassword to complete tasks that require user identity.


Syntaxhttp://Host?OpenServer&login

http://Host/DatabaseDirectory/DatabaseFileName?OpenDatabase&login

Exampleshttp://www.mercury.com?OpenServer&login

http://www.mercury.com/sales/leads.nsf?OpenDatabase&login

URL commands for processing SSL certificatesThe following commands automate the request and receipt of SecureSockets Layer (SSL) certificates stored in a database.

OpenForm with SpecialAction argumentSyntaxhttp://Host/Database/FormName?OpenForm&SpecialAction=specialActionField

Where:

specialActionField is the name of an editable text field on the form whosevalue contains a predefined command. To use the field with SSLcertificates, use one of the following certificate request commands:

“SubmitCert”

“ServerRequest”

“ServerPickup”

For more information about the OpenForm command, see “URL commandsfor opening agents, forms, and navigators” earlier in this chapter.

Exampleshttp://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 CertificateThe SubmitCert command creates a User Certificate document in thespecified database, using the form specified in the TranslateForm argument.

Syntaxhttp://Host/Database/ResultForm?RequestCert&Command=SubmitCert&TranslateForm=TranslationFormName

Where:

ResultForm is a form in the specified database that displays informationabout the processed request.

TranslationFormName represents a form in the database that containsfields to hold certificate information.

Examplehttp://www.mercury.com/certs.nsf/CertificateProcessed?RequestCert&Command=SubmitCert&TranslateForm=Certificate

Optional and required fieldsThe SubmitCert command requires a translation form with a field namedCertificate. Domino saves information about the certificate subject andissuer in the document if the form contains fields with these names:

CommonName

Org

OrgUnit

Locality

State

Country

IssuerCommonName

IssuerOrg

IssuerOrgUnit

IssuerLocality

IssuerState

IssuerCountry

Creating an SSL Server Certificate RequestThe ServerRequest command creates a Server Certificate Request documentin the specified database, using the form specified in the TranslateFormargument.


Syntaxhttp://Host/Database/MessageForm?RequestCert&Command=ServerRequest&TranslateForm=TranslationFormName

Where:

ResultForm is a form in the specified database that displays informationabout the processed request in the user’s browser after a successfulsubmission.

TranslationFormName represents a form in the database that containsfields to hold certificate information.

Examplehttp://www.mercury.com/certs.nsf/CertificateProcessed?RequestCert&Command=ServerRequest&TranslateForm=Certificate

Optional and required fieldsThe ServerRequest command requires a translation form with a field namedCertificate. Domino saves information about the server request in thedocument if the form contains fields with these names:

CommonName

Org

OrgUnit

Locality

State

Country

@functions and @commandsMost @functions are supported in Web applications. If you are familiar withthe formula language, use @functions as a quick way to addprogrammability to a form.

Since browsers don’t provide menus for Web applications, Dominosupports @commands that allow users to work at a Web site, including theability to open and edit documents, delete documents, open a view, orchange to another view.

See Formulas for information about using @commands and @functions.


Java, JavaScript and Visual Basic Script

The following programming languages may be used in Web applications byentering them into HTML or $$HTMLHead fields, or marking them aspassthru HTML.

Java

JavaScript

Visual Basic script

For more information on Java programming, see the Domino DesignerProgramming Guide, Volume 3: Java Classes.

JavaScriptJavaScript allows you to create interactive applications that can runinterchangeably on your company’s intranet or on the Internet. InJavaScript, most of the information processing is done on the client side.This increases the efficiency of your applications by reducing the amount oftraffic between the client and the server. JavaScript may be entered into theJS Header object on the Objects tab in the Programmer’s pane, as passthruHTML, or into a $$HTMLHead field.

See “Adding Automation to Applications” for information about usingJavaScript in Domino.

Perl Scripts

Domino supports programs written in Perl. Perl programs have file namesthat end with .pl. Place Perl programs in the cgi-bin directory. By default,Domino looks in directories that are included in the server’s PATHstatement for a Perl interpreter named perl.exe. To override this default,define an environment variable (PERLBIN) that gives the name or absolutepath of the Perl interpreter. For example, c:\perl5\bin\perl.exe.

Common Gateway Interface (CGI) programs

CGI is a standard for connecting external applications with HTTP servers.CGI programs allow you to do some background processingon a Web page.To run CGI programs, place them in the default cgi-bin directory or in adirectory that has execute access. Because Domino does not maintain accesscontrol at the file system level, scripts must include access control measuresto prevent unauthorized use.


Running a CGI programTo run a CGI program, include the URL to the CGI program file andenclose it in brackets. Note that you can pass arguments — for example,values from fields in the form — to the CGI program. For example:

[http://www.lotus.com/cgi-bin/register.exe?“ + Email + ”&&&“ +LastName + ”&&&]

A CGI program can run immediately after the user submits a document.You might do this when you want to use the Notes API to further processthe data. To run a CGI program this way, add a field named $$Return, anduse HTML instructions as the field value.

CGI variablesWhen a Web user saves a document or opens an existing document, theDomino Web server uses CGI variables to collect information about theuser, including the user’s name, the browser, and the user’s InternetProtocol (IP) address.

To capture this information in a Web application:

Create a field with the name of a CGI variable.

Create an agent whose script contains a CGI variable as aDocumentContext property.

Creating a field with the name of the CGI variableWhen a field is named after a CGI variable, Domino copies the field valuefrom the CGI environment and places it in the field. This feature is useful incomputed-for-display fields and for determining “hide when” conditions.

1. Create a field and give it the name of a CGI variable.

For example, to obtain the IP address of the user submitting the form,add a field named Remote_Addr to the form.

2. Select the hide-when field properties “Previewed for Editing” and“Opened for editing” so users cannot enter information in it.


Using the DocumentContext property in Web agent scripts

The DocumentContext property of the NotesSession class is useful inWeb-run LotusScript agents. When an agent is executed using the?OpenAgent command, the DocumentContext property returns a Notesdocument that contains all CGI variables that are applicable to the session.When an agent associated with a document (through the form’s query openagent or query save agent) is executed, the values of that document can beaccessed via the DocumentContext property. You can use these values tocollect or process information for the current session. Agents used this waymust be shared agents and be set up to run manually.

To use the DocumentContext property, precede an agent script with theselines:

Dim session As New NotesSessionDim doc As NotesDocumentSet doc = session.DocumentContext

Note If the agent runs with the WebQueryOpen or WebQuerySave formevents, the document returned by DocumentContext does not automaticallycontain CGI variables. You must add fields with CGI variable namesdirectly to the form to capture session information.

Example: Using the DocumentContext property in Web agent scriptsThis script uses the Print statement and the CGI variable remote_user todisplay “User =” and the Web user’s name. The script sets theDocumentContext before executing the rest of the script. The variableassumes a text list.

Dim session As New NotesSession Dim doc As NotesDocumentSet doc = session.DocumentContextPrint "User = " + doc.remote_user(0)

Table of CGI variablesDomino captures the following CGI variables through a field or aLotusScript agent. You can also capture any CGI variable preceded byHTTP or HTTPS. For example, cookies are sent to the server by the browseras 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 isprotected, this is the protocol-specific authenticationmethod 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 HTTPPOST and PUT, this is the content type of the data.

Gateway_Interface The version of the CGI spec with which the servercomplies.

HTTP_Accept The MIME types that the client accepts, as specified byHTTP headers.

HTTP_Referer The URL of the page the user used to get here.

HTTPS Indicates if SSL mode is enabled for the server.

HTTP_User_Agent The browser that the client is using to send the request.

Path_Info The extra path information (from the server’s root HMTLdirectory), as given by the client. In other words, scriptscan be accessed by their virtual path name, followed byextra 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 thatcontains characters that are not allowed a URL, the nameis encoded. This CGI variable decodes the string.Path_Info_Decoded is available to Domino applicationsonly.

Path_Translated The server provides a translated version of PATH_INFO,which takes the path and does any virtual-to-physicalmapping to it.

Query_String The information that follows the ?, or in some cases the !*in the URL that referenced this script.

Query_String_Decoded Returns the same as Query_String, but decodes thestring. For example, if a URL references a view name thatcontains characters that are not allowed in a URL, thename is encoded. This CGI variable decodes that string.Path_Info_Decoded is available to Domino applicationsonly.

continued


Field name Returns

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 nameretrieved from the server. Use this variable only forlogging.

Remote_User Authentication method that returns the authenticateduser name.

Request_Content Supported only for agents. Contains the data sent with anHTTP POST request. The data is usually “URLencoded,”consisting of name=value pairs concatenated byampersands. 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 forself-referencing URLs.

Server_Name The server’s host name, DNS alias, or IP address as itwould appear in self-referencing URLs.

Server_Protocol The name and revision of the information protocolaccompanying this request.

Server_Port The port to which the request was sent.

Server_Software The name and version of the information server softwarerunning the CGI program.

Server_URL_Gateway_Interface

The version of the CGI spec with which the servercomplies.

*If your Domino server is configured to allow search engines to search yourWeb site, Domino will generate URLs with an ! (exclamation point) insteadof a ? (question mark). If this is the case the Query_String CGI variableincludes the information that follows the exclamation point. Domino alwaysrecognizes both the question mark and the exclamation point, but onlygenerates URLs with the exclamation point if your site is accessible to Websearch engines. Generating URLs with an exclamation point makes themmore searchable.


Symbols$$fields

$$Return, 112$$ViewBody, 490listed, 161, 394

@commandsfor application automation, 294Programmer‘s pane and, 5referencing, 146Web use of, 23, 497

@Db commands@DbColumn, 140, 430@DbCommand, 430@DbLookup, 140, 430described, 425

$fields$Anonymous, 359$HLFormula field, 144$PublicAccess, 360$title, 83$UpdatedBy, 359$VersionOpt, 162listed, 161

@functions@DialogBox, 108@PickList, 110@Prompt, 109for date and time

calculations, 133for external data access, 140Programmer's pane and, 5referencing, 146using, 211Web, 463, 497

Numbers1-2-3 files

importing into views, 445

AAbout This Database document

creating, 377inheriting from template, 399launching, 26OpenAbout command, 480

Accessdatabase, 48, 349defined, 347documents, 351folders, 351forms, 353, 354outlines, 46restricting through outline

settings, 48sections, 369views, 351

Access Control List. See ACLAccess levels

list of recommended, 389Access list, 355Accessibility

for users with disabilities, 35Accessing data. See Data accessACL

access levels, 389agent security and, 275CGI and, 498copying from template, 19database, 349URL commands and, 494using to enter names, 137, 139Web previewing and, 38

Action bardescribed, 257

Action bar applet, 22, 257Action buttons

and screen readers, 36creating, 253

Action hotspotscreating, 265defined, 248deleting, 265editing, 265hiding, 265

Actionsadding, 220built-in, 247changing automation for, 254copying, 254creating, 253creating hotspots for, 265deleting, 254described, 13, 246displaying as buttons, 253editing, 259examples, 247inserting, 258menu, 254naming, 300navigator, 230OLE and, 340publishing, 326shared, 31, 258simple, 246URL commands and, 476using to simulate Notes

menus, 254Web, 464

Actions field, 394Actions menu

described, 254ActiveX

defined, 326Address Book provider

Domino Directory and, 455Address lookups

in multiple Domino Directories, 455

Agent Logdescribed, 279size limit, 284

Agent Managerdescribed, 249recording less information, 283setting up debugging, 278

AgentRunnerdescribed, 284

Agents, types ofbuilt-in, 249embedded, 277

Index 503

Index

CT6E2NA

Please note that the page numbers listed in the Table of Contents refer to the page numbers that appear in the footers of the printed documentation. To navigate to a specific page, select the chapter and use the scroll buttons in the tool bar to go to the page.

foreground or background, 276local or server, 276LotusScript and Java, 274public access, 360

Agents, uses foradding fields with, 395editing documents with, 395hiding design with, 409mail responses, creating, 422mailing with, 422removing field data with, 395removing stored forms with, 396renaming fields, 396resaving documents with, 395

Agents, working withAgent Manager debugging, 282automated components of, 268calling, 254, 262, 277chaining together, 289compared to servlets and CGI

programs, 432copying, 268creating, 267debugger settings, 280debugging, 277deleting, 268described, 13, 248disabling, 268enabling, 272examples, 272finding creator of, 276invoking, 433naming, 300properties of, 432renaming, 391replication conflicts and, 271run-time statistics, 281run options, 269running, 254running on the Web, 500scheduling, 267security, 273, 434simulating a run, 277specifying servers for, 267uses for, 432viewing, 249viewing the log, 279Web and, 464

Aliasesaction names, 300agent names, 300choice list, 140

converting to full names, 141form names, 87servlet names, 437view names, 181

All by Category view, 186Alternate HTML, 309Alternate text tag

for images and Java applets, 35Annotating

applications, 381documents, 95fields, 380

Anonymous forms, 90Anonymous field, 359AppletBase

extending, 315Applets

action bar, 257adding to a page or form, 70BeanMachine and, 304described, 431editor, 126Java, 303listed, 22outline, 51servlets and, 431view, 216

Applicationsannotating, 381automating, 245, 340completing, 375deploying, 383documenting, 377mail-enabled, 414master design copies, 383overview of Domino, 1previewing, 37security for, 347setting launch properties

for, 25testing, 389

Asterisksas passwords, 142

Attachingsignatures, 368

Attachment fieldsWeb and, 25

Attachmentscreating, 71, 102displaying information

about, 197on pages and forms, 71

opening with URL commands, 487

AttributesHTML, 156

Authenticationcertificates and, 350URL commands and, 494

Authorsanonymous, 90displaying names, 197

Authors fieldcreating, 351described, 356restricting read-access with, 356

Autolaunchingdefined, 331examples, 334objects, 74, 325

Automatingapplications, 340described, 13, 245formulas for, 294hiding components, 302JavaScript and, 295navigators, 234replies, 422security features and, 294using LotusScript, 291

Averagescalculating, 206

BBackground processing

on Web pages, 498Backgrounds

for pages and forms, 68Base class property

for Java applets, 310Billing

forms for, 111reserved fields for, 160

Bitmap graphics. See GraphicsBlank databases, 20BMP files. See GraphicsBody field, 160, 394Borders

for frames, 170Browsers

proxy settings for, 39setting up for previewing, 39using Print statement to

instruct, 291


Button bar, 257Buttons

creating, 261customizing, 258defined, 248deleting, 261editing, 261examples of, 262

CCAB files, 306Calculating

cell values, 206field values, 128, 196values for computed fields, 146

Calendar controlsadding to a page or form, 72creating, 134Web use of, 465

Calendar viewscreating, 177, 465defined, 173using with the group

scheduler, 102Cascading

action names, 301agent names, 301form names, 87view names, 183

Cascading Style Sheet. See CSSCatalog database, 349Categories

adding to views, 185, 187columns, 187field for creating, 161, 187formulas for, 187naming, 187subcategories, 188

Categorized viewaliases and, 141

Categorizingby users, 185, 188documents, 186

Category fields, 187cc:ing. See Forwarding, Routingcc:Mail

mailing to, 419Certificates, SSL, 494CGI

defined, 498

CGI programscompared to servlets and

agents, 432invoking, 433properties of, 432security for, 434uses for, 432

CGI variablesagents and, 500fields and, 499table of, 500user profiles and, 499

Character translation file, 444Checkbox fields

aliases in, 140creating, 137in Web applications, 465

Choice list fieldsaliases in, 140creating, 137refreshing, 151views and, 110

Choicesdisplaying in lists, 110, 137refreshing, 152

Class name, 305Classes

CSS, 28Notes, 314

CLS files, 444CodeBase property

for Java applets, 310COL files

creating, 448defined, 448for importing a tabular text

file, 450formulas and, 449, 452guidelines, 449keywords, 449

Collapsingcolumns, 197sections, 369views, 207

Color paletteschanging, 21for choosing colors, 64using to blend colors, 31

Colorsblending with user's system, 33for columns, 207

for frame borders, 171for navigators, 233for outline entries, 50for rows, 207for unread marks, 222for views, 207for Web applications, 21palettes for, 64

Column descriptor file. See COL filesColumn width, 450Columns

adding to views, 180calculating values in, 206categorized, 185collapsing, 197copying, 179date, 223deleting, 179entering names from, 139expanding, 197formatting, 223hiding, 207HTML and, 205icons in, 200linking to documents, Web, 205mapping to fields in views, 448numbers, 224programming, 194referred to in formulas, 211response, 214specifying data type in views, 449styling, 207switching to a view, 205testing, 387time, 223titles for, 184views and, 10, 173width, 207, 451

Combobox fieldsaliases in, 140creating, 137

Common Gateway Interface. See CGI

Common namedisplaying, 136

Compatibility with previousreleases, 304

See also Release 4; UpgradingComponents

sizing, 330using, 326

Index 505

ComposedDate field, 160Compression. See Zip filesComputed fields

CGI programs and, 499defined, 146examples, 150order of evaluation, 85

Computed for display fields, 147Computed text, 58Computed when composed

fields, 147Conflict documents, 90

See also Replication conflictsConsole commands, 280Controls

calendar, 72, 102, 139date/time, 133embedded, 102

Cookies, 75Copy Java applet, 313CORBA properties

for Java applets, 310CORBA SSL security

for Java applets, 311Count parameter

Domino URL commands and, 490

search results and, 494Create menu

documents and, 87CreateDocument command, 483CSS

class and objects, 28described, 28passing information, 162styles applied to objects, 28

Currencyfields for, 128formatting in columns, 224formatting in Number fields, 128

Custom controlsadding to forms, 328described, 326read-mode and, 331running, 331sizing, 330updating, 331

Customizingdatabases, 17sorting order for columns, 204templates, 398window titles, 95

DData access

with @DbColumn and@DbLookup, 140

with Domino Connectors, 426with Lotus Enterprise Integrator,

426with ODBC, 428, 429with servlets, 431

Data entryfields for, 146

Data types. See Field typesDatabase icons

creating, 376replacing, 406

Database managementshared resources and, 30stored forms and, 82

Database synopsis, 391Databases

See also Applicationsaccess control lists, 349access to, 349agent access, 275blank, 20connecting to, 425copying, 18creating, 16, 402creating a test copy, 278default views, 210defined, 2documenting, 377external, 428hiding, 411icons, 481launch properties, 25launching into framesets, 172linking, 402mail features and, 417naming, 18ODBC and, 428previewing, 27properties, changing, 23renaming, 391replacing design of, 406response forms, 92restricting creation of new, 275SSL protected, 350summary, 391titles for, 17unlinking, 409URL commands and, 477

DatalensODBC and, 429

Date/Time controls, 133Date/Time fields

described, 129examples, 135

Date pickeradding to a page or form, 72in Web applications, 465

Date separator, 130Dates

calculating by formula, 133columns for, 223displaying, 223entering, 129, 133formatting, 130, 132, 223stored as seconds, 136

Debug_AMgr statement, 282DEBUG_OUTFILE statement, 283Debugging

agents, 277Java applets, 320NotesLog class, 283

Decimal placesin Number fields, 129

Decimal symbol, 129Decrypting documents, 363DECS

described, 425Default

active field, 153encryption, 365field values for editable

fields, 148headers and footers, 92views, 210

DeleteDocument command, 483Deploying

applications, 383Design action buttons, 4Design bookmarks icons, 4Design changes

making, 403preventing in image resources, 32templates and, 17

Design elementsautomating, 266copying, 18hiding, 411linking, 402listed, 2named, 260previewing, 37


protecting, 408templates and, 402updating, 404

Design list, 4Design pane, 4Design synopsis

creating, 391described, 14

Designerstarting, 3work area overview, 4

Designschanging, 407default, 181hiding, 18, 409linking, 402maintaining, 388preventing changes, 383refreshing, 404replacing, 406replication and, 407synopsis of, 391templates and, 397, 409testing, 385unlinking, 409updating, 404

Details. See ExpandingDialog boxes

creating, 108designing, 109displaying, 337

Dialog forms, 108Dialog list fields, 137Discussion template, 16, 441DocBase property

for Java applets, 310Doclinks. See LinksDocument Library template, 442Document Object Model, 5Document Save dialog box

overriding options, 419Document selection formula, 189DocumentContext property

in Web agent scripts, 500Documenting

applications, 377fields, 380

DocumentsAbout This Database, 377accessing, 351, 356agent access, 275agents and, 395annotating context of, 95anonymous, 90

calculating age of, 135categorizing in views, 186conflict, 90copying, 287copying from templates, 19creating, 87, 483decrypting, 363deleting, 287, 483displaying in views, 189, 194,

196, 197editing, 395footers, 92form redesign and, 393forms and, 81headers, 92help, 381hiding, 337launching, 378launching as dialog boxes, 337launching into framesets, 172linking in workflow

applications, 415mailing, 290, 417marking read or unread, 287modifying, 156, 380, 395, 483moving, 289opening by key, 485previewing, 27profile documents, 106public, 360reassigning to forms, 396removing form from, 396resaving, 395response, 92security for, 351, 355,

356, 361, 368sending summary, 290sorting in views, 201storing forms with, 162tracking, 111unread, 222updating, 393URL commands and, 484, 485Using This Database, 377version tracking, 93viewing deleted, 178views and, 186, 189, 194,

195, 197, 201Web, 87

Domainssearching, 490

Domino-generated fields. SeeReserved fields

Domino Connectorsdescribed, 426

Domino Directoryaccessing, 455, 457Address book provider

and, 455using to enter names, 139

Domino Directory Server documentservlet manager settings, 435

Domino Global Workbench, 27Domino Java Virtual Machine

(JVM), 435Domino Servlet Manager, 434Domino URL commands

authentication and, 494count parameter, 493implicit and explicit, 486maximum size, 475opening documents by key, 485server commands, 477ServerRequest, 496start parameters, 493syntax, 475

DominoObjectin URL commands, 476

Duration controlscreating, 135in Web applications, 465setting separator for, 155

EECL

setting up for secure Java appletaccess, 314

Edit modefor forms and documents, 90hidden data in, 29

Editable fieldsdefined, 146

EditDocument command, 483Editing

documents, 395fields, 360forms, 393images with the editor

applet, 467navigators, 230restricting, 356URL commands and, 484window titles, 95

Editor appletdescribed, 22using, 126

Index 507

Editorsanonymous, 90sections and, 369tracking, 359

E-mail. See MailEmbedded controls

date picker, 72file upload control, 102forms and, 102group scheduler, 102, 465

Embedded elementsgroup scheduler, 102keyboard accessibility and, 36pages and, 71reserved fields for, 160

Embeddingdefined, 327folders, 219navigators, 215, 240objects, 325outlines, 45, 46views, 215, 218

Enablingeditor applet, 127encryption, 365Notes/FX, 343

Encapsulated documents, 419Encryption

default, 365defined, 361enabling, 365examples, 143, 363fields, 363, 365

Encryption keyscreating, 364defined, 361examples, 367fields for, 160, 366listing, 366password fields and, 143secret, 161

Entry helper button, 138ERP systems

connecting to, 425Error executing agent

error message, 284Events

agent, 252calendar view, 251click, 252database, 250described, 249examples, 266field, 252

folder, 251form, 251page, 75programming, 250view, 250

Examplesaccess, 358actions, 256agents, 422autolaunching, 334automating navigators, 236buttons, 262choice list field generation, 140columns, programming, 195computed fields, 150customizing window titles, 96Date/Time fields, 135default value formulas, 149displaying documents in a

view, 190encryption, 363encryption keys, 367events, 266exchanging data, 344fields, 344fields that control mailing

options, 420hiding, 339hotspots, formula pop-up, 264hotspots, text pop-up, 263inheriting information, 158input translation formula, 150Java servlet, 439links, 261password fields, 142restricting access, 352routing review requests, 413security, 358servlet, 439servlets.properties file, 439templates, 399

Excel filesimporting and exporting to, 443

Exchangingfield data, 342

Execution Control List. See ECLExpanding

columns, 197sections, 369views, 207, 479

Exponential notation, 129Exporting

from views, 452Java applets, 314

External database accesswith Domino Connectors, 425with Lotus Enterprise

Integrator, 425with ODBC, 428, 429

ExternalData parameterin Java applets, 317

Externalization for Java applets, 317

FField-exchange. See Notes/FX,

Notes FlowField data

deleting from documents, 122reassigning, 123shared fields and, 124

Field formulascreating, 146described, 148

Field helpwriting, 380

Field labeldefined, 124

Field namesdescribed, 124requirements for, 124

Field typesdefined, 121list of, 125listed for choice list fields, 138

Field valuescalculating, 146, 196default for editable fields, 148displaying, 194, 394

Fields, types ofAuthors, 351, 356Category, 187checkbox, 138choice list fields, 138combobox, 138computed, 85, 146computed for display, 147computed when composed, 147Date/Time, 129dialog list, 138editable, 146embedded elements, 160for data entry, 146Formula fields, 144hidden, 90HTML, 157listbox, 138mail-enabling, 160


Names, 136Numbers, 128Password fields, 142Radio button, 138Readers, 351, 355reserved, 160, 394Rich text, 126shared, 122Text, 126

Fields, working withadding to existing

documents, 395annotating, 380CGI variables and, 499copying, 122creating, 121, 342default active, 153default values for, 128, 148defined, 81deleting, 122described, 121editing, 360encrypting, 363examples, 344exchanging data in, 326formulas, 148hiding, 61, 153, 154HTML attached to, 156inheriting documents in, 158inheriting values in, 158layout regions and, 155modifying, 288naming, 124recalculating computed, 148renaming, 125, 396replacing field values, 288resizing, 156setting input validation

formula, 148setting translation formula, 148shared resources as, 31signing, 368Web and, 465

File field, 394File formats

importing from and exporting toviews, table for, 443

File upload control, 102Flat style outline, 48Floating point arithmetic, 129Folder pane, 11

described, 41embedding, 219

FolderOptions field, 164

Foldersaccess to, restricting, 351adding documents to, 161, 164copying documents to, 287creating, 227defined, 227embedding, 219hiding, 351MAPI Folder Interface and, 456removing documents from

without deleting, 287security, 353Web, 227

Fontsapplying to text, 57changing in a form, 58

Footerscreating, 92

Foreign language applicationsdesigning for, 27

Foreign symbolstranslating, 444

Form buttonscreating multiple on Web, 23

Form elementslisted, 80

Form processed confirmation, 112overriding, 162

Formattingcolumns, 223dates, 223HTML, 156, 210numbers, 224text, 57times, 223views, 210

Forms, types ofanonymous, 90billing, 111dialog, 108customized results forms, 493Domain Search forms, 113profile forms, 106response, 92version tracking, 94

Forms, working withaccess lists and, 351Authors fields on, 351autolaunching and, 332, 336choices on, 110compared to pages, 53, 79copying, 84creating, 79, 84, 360default form selection,

overriding, 83deleting, 84described, 79designing, 85, 332designing prompts, 109dialog boxes as, 108displaying as Web page, 483displaying documents with

forms, 82displaying without editable

fields, 483edit mode, 90embedded controls on, 102embedded navigators and, 241embedding objects in, 327examples, 344field-exchange in, 326footers on, 92headers on, 92hiding, 88improving performance of, 118launching an OLE object, 333linking objects in, 327naming, 86navigators and, 228objects and, 325OLE and, 328Readers fields on, 351redesigning, 393removing, 396renaming, 391replication and, 90restricting access to, 355storing, 396storing with documents, 82, 162templates and, 160testing, 119, 384Web applications and, 466Web users‘ access to, 89window titles, 95

Formula fieldsdescribed, 144programming, 144

Formula languagein Web applications, 497

Formula pop-upscreating, 263defined, 248deleting, 263editing, 263

FormulasCOL files and, 452columns and, 194creating, 263

Index 509

deleting, 263dialog box, 108editing, 263entering in the Script area, 5field, 146for automating applications, 294input translation, 146, 148input validation, 146literalizing, 144lookup, 211prompting users, 109providing Web navigation

with, 220view, 189

Forwardingdocuments, 417restricting, 355

Framesborders for, 167, 170described, 165in Web applications, 468naming, 168scroll bar for, 171sizing, 170specifying a target frame, 169

Framesetscontent for, 168creating, 166defined, 12, 165keyboard accessibility and, 36launching automatically, 165opening with URL

commands, 481outlines and, 52

From field, 160Full-text index

copying settings, 18

GgetCodeBase

in Java applets, 323getDocumentBase

in Java applets, 322GIF files. See GraphicsGlobal Workbench. See Domino

Global WorkbenchGraphical date/time controls, 133Graphics

adding to navigators, 231adding to outline entries, 46alternate text for, 35backgrounds, 68changing when moused over, 33

choosing colors for, 64copying, 232creating, 66database management and, 31design tools for, 231dynamic, 32hiding, 32importing, 232layout regions and, 101navigators and, 231pasting, 232shared resources, 30text over, 155

Gray scaleusing to blend colors, 33

Group calendarsin Web applications, 465

Group schedulerusing, 102

Guides. See Outlines, Navigators

HHeaders

creating, 92Headlines database

described, 144subscriptions and, 30

Helpcreating, 377displaying, 328writing, 380

Hide-when conditionsCGI fields and, 499field settings, 154options, setting, 29

Hidingautomated components, 302button hotspots, 261columns, 207databases, 411design elements, 29, 411designs, 18, 409documents, 337examples, 339fields, 61, 153, 154folders, 351formula pop-ups, 264graphics, 32Java applets, 311link hotspots, 260menu choices, 239objects, 339outline entries, 47

paragraphs, 153section titles, 369servlet names, 438subforms, 97text pop-ups, 263views, 183, 221, 239, 351

Hierarchy. See Expanding views,Response documents

Hierarchical namedisplaying as common name, 136

Home pagescreating, 53defined, 56launching, 56specifying, 382URLs, 382

Horizontal rulescreating, 59in Web applications, 469

Host forms, 108Hotspots

action hotspot, 265and imagemaps, 69button hotspot, 261creating, 234defined, 13, 234examples, 248formula pop-up hotspot, 263link hotspot, 260navigators and, 234text pop-up hotspot, 262URLs in, 260Web applications and, 469

HTMLadding, 205alternate text tag, 35attributes, 156, 309columns and, 205core attributes, 28displaying information with Print

statement, 291field, 157formatting, 156, 210generating for hidden fields, 91on pages and forms, 73passing to server, 162referencing objects with

JavaScript, 28tag attributes, 28viewing frameset source, 167views and, 210

HttpSession instance, 436


IIcons

creating database, 376displaying in columns, 200

Image files, 489Image resources

as dynamic graphic, 32changing, 34creating, 32described, 30inserting, 34maintaining, 31sharing among databases, 34

Image setdescribed, 32

Imagemapsdescribed, 69

Images. See GraphicsImperial measurement, 129Importing

column format, 444documents, 444files into views, 443, 452foreign characters and symbols

into views, 444graphics, 232Java applets, 305lines per page, 446navigators, 241

Indentingdocuments, 196response documents, 213

Indexesdeleting, 225refreshing, 225settings, copied, 18view, 225

Info field, 394Infoboxes. See Dialog boxes,

Properties boxesInheriting

creating fields for, 158documents in fields, 158field values, 149related documents, 93subjects in a response

hierarchy, 159Input forms, 108Input translation formulas

defined, 148example, 150settings for field, 148

Input validation formulasdefined, 148

Insertingsubforms, 98

International charactersdisplaying on the Web, 127in Web applications, 467

Items. See Field data

JJAR files, 306Java servlets, 431Java applet properties

Base class, 310CodeBase, 310CORBA classes, 310CORBA SSL security, 311DocBase, 310Size, 310

Java appletsalternate text for, 35as shared resource, 31BeanMachine and, 304compared to servlets, 431copying, 313debugging, 320deleting, 313Domino, listed, 22enabling on workstation, 304exporting, 314hiding, 311importing, 305linking to, on the Web, 306overview, 303pages and, 70parameters, 307persistence for, 317refreshing, 314requirements for, 304running, 308security, 314selecting, 313serialization, 319servlets and, 431setting HTML attributes, 309shared resources, 312starting, 313stopping, 313storing files for, 304Troubleshooting, 320Web and, 22Web applications and, 498

Java compiler, 434Java Debug Console, 320Java programs

creating for agents, 299editing and the Reference tab, 5importing into agents, 299restricting use in agents, 274servlets, 431storing, 31using for data access, 426

Java servlets, 434JavaScript, 75

automating applications with, 295

editing, and the Reference tab, 5table of supported objects, 296Web applications and, 498

JavaScript codepassing, 162

JavaScript headerfor pages and forms, 75

JDBCusing for data access, 426

JPEG graphics. See Graphics

KKeyboard

accessibility, 35Keyboard shortcuts

and form names, 87Keys. See Encryption keysKeywords

COL files and, 449See also Choice list fields

LLabels

fields, 124Language preference

setting, 27Launch properties

for pages or forms, 74Launching

databases, 25databases into framesets, 172documents, 378documents or pages into

framesets, 172framesets, 165home pages, 56links, 26objects, 74, 325

Index 511

pages, 26target frames and, 169

Layout regionschanging, 100defined, 81described, 99fields in, 155graphics in, 101read access, 29unsupported features, 138

Legacy databasesconnecting to, 425

Legendgroup scheduler, 105

Levels. See Expanding views,Response documents

Line wrapin Web views, 175, 185

Linkingcolumns to documents, 205databases, 402design elements, 402designs, 402documents, 415mail, 415objects, 325templates and, 402

Linkscreating, 127, 260defined, 247deleting, 260displaying, 205editing, 260launching automatically, 26on pages and forms, 62sending, 415target frames and, 169

Links field, 394Listbox fields

aliases in, 140creating, 138

Lists of choicesdisplaying, 110

Loginargument, 494command, 477, 494URL command guidelines, 476

Logout command, 477Lookup formulas, 211Lookup options

for names, 136Lookups

creating, 111view lookups, 137, 139, 141

Lotus componentsusing, 326

Lotus Enterprise Integratordescribed, 426

Lotus paletttegrays, 33See also Color palettes

LotusScriptbrowser window, 5debugger, 278for application automation, 291OLE and, 327restricting use in agents, 274storing programs, 31using for data access, 426Web agents and, 500Web and, 464

LS:DOusing for data access, 425

MMacros. See AgentsMail

agents, 422applications, 414automatic, 415changing default font of, 58fields, 418fields for automatic, 417fields for enabling, 160forwarding, 417in workflow applications, 414linking, 415MAPI classes and methods, 459sending, 416, 419

Mail-in Databaseagents and, 422creating, 421

Mail-in Database Documentdescribed, 421

Mail fileaccessing, 455

Mail integrationoverview, 455

Mail messagesdelivery, 456, 457MAPI, 457, 459non-Notes, 457

Mail option fieldsexamples, 420

Mail queueoutgoing, 456

Mail router, 457

Mail Send dialog boxoverriding choices, 419

Mail templatechanging fonts in, 58

MailFormat field, 419Mailing documents, 416Main class name, 305MAPI

Address Book provider, 455classes and methods, 459defined, 455Message Store provider, 456Message Transport provider, 457overview, 455platforms, 457recipient types, 457requirements, 457service providers, 455, 456, 457spooler, 457

MAPI Folder Interfaceand folders, 456

Maps. See Outlines, NavigatorsMaster design copies

creating, 383Menu bar, 4Menus

actions, 254displaying, 328hiding choices, 239shortcut keys and, 301simulating for Web users, 254

Message sortingarbitrary, 456

Message store providerdescribed, 456

Message Transport provideraddress type and, 457message type and, 457

Messagesdelivery of, 456MAPI classes and

methods, 459See also Mail

Messaging application programinterface (MAPI)

Address Book provider, 455classes and methods, 459Message Store provider, 456Message Transport provider, 457overview, 458platforms, 457requirements, 457service providers, 455, 456, 457spooler, 457


Meta datapassing, 162

Metric measurement, 129Microsoft files

importing into views, 445Microsoft Internet Information

Server (MIIS)server commands, 476

Microsoft Office Library template, 442

Mouse-over imagecreating, 33

Multilingual applicationsdesigning for, 27settings for, 27

NNamed elements

defined, 260Names

cascading, 301displaying, 136entering from a list, 136

Names dialog boxdisplaying, 137

Names fieldsdescribed, 136in Web applications, 465

Namingcategories, 187databases, 18forms, 86frames, 168framesets, 167views, 181

Native controls, 152Navigating

Web sites, 215, 240Navigation pane. See Folder paneNavigator templates

forms as, 228Navigators. See also Outlines

actions in, 230automating, 234color, 233creating, 229designing, 229displaying, 239editing, 230embedding, 240examples, 236formulas and, 235graphics and, 231

highlighting, 233hotspots and, 234imagemaps and, 69importing, 241opening, 239programming, 230renaming, 391scripts and, 235styling, 233templates and, 228, 241testing, 242text on, 233Web, 228, 229, 469web applications and, 229

Notes/FX. See also Notes Flowenabling, 343in Web applications, 465setting up, 342using, 342

NOTES.INIrecording debugging

information, 283NOTES.INI settings

Default_Index_Lifetime_Days,225

Notes Browserpreviewing in, 37

Notes classessetting up applet access to, 314

Notes Clientdesigning for Web

and, 21, 90, 127, 157launch options, 25search forms and, 113

NotesFlow. See also Notes/FXactions, 326applications, 325field-exchange, 326

NotesLog class debuggingsetting up, 283

Notes Mail. See MailNotesSession class, 500NSF files

copying, 18creating, 20

NTF filescreating, 388defined, 16, 397using, 16

Number fieldsdescribed, 128

Numberingdocuments in views, 194

Numberscolumns for, 224formatting in Number fields, 128

OObject parameter

in Java applets, 319Objects

autolaunching, 331drawing, 232embedding, 327enhancing, 233hiding, 339hotspot, 234launching, 325linking, 327referencing with JavaScript, 28resizing, 329updating, 331viewing properties and

events of, 5Objects tab, 5OCX. See Custom controlsODBC

data sources, 429Datalens and, 429described, 425using, 428

OLEactions and, 340applications, 325autolaunching objects, 336automating, 340custom controls, 327exchanging data, 342launching objects from

a form, 333launching objects in-place, 335LotusScript and, 327publishing actions using, 341resizing objects, 329Web and, 325

OLE custom controls. See Custom controls

OLE objectsautolaunching, 330, 333, 338launching, 329opening with URL

commands, 489OpenAbout command, 480OpenAgent command, 481

Web agents and, 500OpenDatabase command, 477

Index 513

OpenDocument command, 484OpenElement command, 489

OpenForm commandSearchDomain and, 490SpecialAction argument and, 495

OpenFrameset command, 481OpenHelp command, 480OpenIcon command, 481OpenPage command, 486OpenServer command, 477OpenView command, 477

optional arguments, 479Ordered lists

in Web applications, 467Outbox folder

transferring responses and, 456Outline applet, 51

described, 22Outline entries

adding graphics to, 47customizing, 46described, 42displaying as a hierarchy, 47hiding, 47styles for, 50

Outline viewsdefined, 173described, 174

Outlinescreating, 42described, 11, 41designing, 41displaying in framesets, 52embedding, 45, 46styles for, 50Web users‘ access to, 51

Overriding, 112default form selection, 83Form processed

confirmation, 162proxy settings for previewing, 39

PPage breaks

in views, 210Pages

backgrounds for, 68compared to forms, 53defined, 53, 74elements on, 53embedding controls on, 71events for, 75fonts in, changing, 58

graphics on, 66HTML and, 73Java applets and, 70launching, 26launching into framesets, 172links and, 62opening with URL

commands, 486programming, 75styling text in, 57

Palettesfor choosing colors, 64grays, 33using to blend colors, 31

Parallel reviewsin workflow applications, 413

Parameterssetting for Java applets, 307

Password fieldsdescribed, 142

PasswordsURL commands and, 494

PCX graphics. See GraphicsPercentage

calculating, 206formatting numbers as, 129

Performance forms and, 85, 118computed fields and, 147group scheduler and, 105headline monitoring and, 30improving on Web, 24lookups and, 140stored forms and, 82

Perl scriptWeb applications and, 498

PersistenceJava applets, 317session, 436

Personal Address Bookusing to enter names, 139

Personal agentscontrolling, 274creating, 267defined, 249Web users and, 274

Personal views. See Private viewsPersonal Journal template, 442Pictures. See GraphicsPop-up calendar controls, 465Pop-ups

formula, 263text, 262

Precisionin Number fields, 129

Predefined fieldslist of, 160

Preview icons, 4Previewing

applications, 37databases, 27documents, 27framesets, 167hiding information during, 153Notes client vs. Notes

Browser, 37setting up, 39

Printingheaders and footers, 92hidden information, 29, 154restricting, 355

Private views, 178Profiles

creating user, 106Programmable tables, 60Programmer's pane, 5Programming

columns, 194formula language in Web

applications, 497JavaScript in Web

applications, 498navigators, 230Perl script in Web applications,

498views, 477Visual Basic script, 498

Programscreating for events, 266

Projectscreating, 284

Promptscreating, 109displaying, 109

Propertiesaction hotspots, 265changing, 23changing database and design

element, 23for Java applets, 310

Properties boxesdescribed, 6

Protectinganonymity, 90design elements, 408designs, 408


Proxy settingsfor previewing in browsers, 39

Public accessagents, 360defined, 360described, 46documents, 360forms, 360framesets and, 167outlines, 46views, 360

PublicAccess field, 360

RRadio button fields, 137RANGE statement, 450Read-mode

custom controls and, 331Read access

layout regions and, 29restricting, 354

Read access listfolders, 351forms, 353, 354views, 351

Readers field, 394Readers fields

creating, 355described, 351

ReadExternalData parameterin Java applets, 317

ReadForm command, 483Reading

restricting, 353Redesigning

forms, 393templates, 398

Redirect command, 477domain search and, 490

Reference listusing, 146

Reference tab, 5Refreshing, 148

choice list field values, 152defined, 404designs, 406field values, 146, 152Java applets, 314views, 225

Relational databasesaccessing with ODBC, 428connecting to, 425

Release 4.5attachment fields, 25

Release 4.6hiding paragraphs from, 153URL generation, 25

Reloading. See RefreshingRenaming

agents, 391databases, 391fields, 125, 396forms, 391navigators, 391shared fields, 123views, 181, 391

Replace Design commanddefined, 406

Replicationdisabling, 349forms and, 90templates and, 407

Replication conflictsand agents, 269, 271

Repliesautomating, 422

Report on database design, 391Reserved fields

$Anonymous, 359$PublicAccess, 360$UpdatedBy, 359list of, 160, 394

Reserved form namesfor navigator or view

templates, 228Resources. See Shared resourcesResponse documents, 92

columns for, 214displaying, 197indenting, 213inheriting subject, 159limits on, 181

Response forms, 92Restricting. See also Security

access, 347copying, 355design changes, 383editing, 356examples of, 358forwarding, 355printing, 355reading, 353, 354

Review requestsin workflow

applications, 413, 442

Revision tracking, 93Revisions field, 39Rich text fields, 126

on Web, 126Rounding

in Number fields, 129Route. See Outlines, NavigatorsRouting

automatically, 414Rows

opening to, 210spacing, 207styling, 207

SSaveDocument command, 485Schedules

coordinating, 102Scientific notation, 129Screen-reader software

designing for, 35Script area, 5Script libraries

defined, 31Scripts

creating, 266deleting, 266

Scroll barsfor frames, 171

Search forms, 113SearchDomain command, 490SearchEntry, 491Searches

displaying results, 493navigating through paged

results, 116navigating through results, 494

SearchFuzzy, 491Searching

multiple databases, views,domains, etc., 491

multiple Domino Directories, 455URL commands and, 490

SearchSite command, 491count parameter, 493optional arguments, 491start parameter, 493

SearchViewcount parameter, 493optional arguments, 491

SearchView commandexamples and syntax, 491start parameter, 493

Index 515

Secret encryption keys. SeeEncryption keys

Sectionsaccess to, 369collapsing, 369creating, 61, 369defined, 80editors and, 369hiding titles, 369

Secure Socket Layer. See SSLSecurity

agents, 434CGI and, 498CGI programs, 434database, 349defined, 347documents, 351examples, 358folders, 353for agents, 273for automation, 294for servlets, agents, and CGI

programs, 432hidden fields and, 153Java applet access to Notes

classes, 314loading servlet classes, 434servlets, 434, 438signatures and, 371SSL and, 350SSL certificates, 495types of, 347URL commands and, 494, 495

Serial reviewsin workflow applications, 413

Server certificate requestcreating, 496

Server commandsOpenServer, 477Redirect, 477

Server tasksDesign, 16Updall, 225

ServerRequest commandexamples, 496optional and required fields, 497syntax, 496

Serversconsole commands, 280restricting creation of databases

on, 275Service providers

for MAPI, 455installing, 457

Servlet API, 434Servlet classes

loading, 436Servlet manager, 435Servlets

aliases, 434compared to agents and CGI

programs, 432defined, 431enabling, 435enabling Domino support, 434example, 439including in applications, 431initializing, 434invoking, 433loading, 438properties of, 432running, 434security for, 434servlets.properties file, 434setting properties for, 437URL extension mapping, 434uses for, 432writing, 434

servlets.properties file, 434example, 439

sessdata.ser, 436Sessions

tracking, 436Shared actions

creating, 258defined, 246editing, 259inserting, 258

Shared agentscontrolling, 274creating, 267defined, 249on the Web, 500

Shared databases, 414Shared fields

converting to single-use, 124copying, 122creating, 122deleting, 123inserting, 123renaming, 123stored forms and, 83

Shared graphics. See Image resourcesShared resources

deleting, 313described, 30for Java applets, 312

Shared views, 178

Shortcutsmenu choices and, 301

Signaturesdefined, 368storing, 372verifying, 372

Signingdocuments, 368, 371

Simple actionsdefined, 246table of, 287

Simple agents. See AgentsSimple functions

for columns, 197Site maps. See OutlinesSite Registration template, 442Size property

for Java applets, 310Sorting

documents in views, 201Sorting columns

defined, 201hidden, 204

Sorting ordercolumn, customizing, 204

SpecialAction argument, 495SSL

creating user certificates, 496enforcing for a database, 350server certificate request, 496URL commands and, 495

Start parametersearch results and, 494

Status tracking, 214Stop Java applet, 313Storing

files for Java applets, 304forms with documents, 81, 162Java code, 31LotusScript programs, 31programs, 433signatures, 372

Structured text filesdefined, 447exporting to, 453importing into views, 447

Style editor applet. See Editor appletStyles

CSS, 28Styling

columns, 207frames, 170horizontal rules, 59navigators, 233


rows, 207text, 57titles, 184views, 207

Subcategories, 188Subforms

defined, 31, 81described, 97examples, 98

Subject field, 160Submit button

generating automatically onWeb, 24

SubmitCert commandexamples and syntax, 496optional and required fields, 496

Subscription documentsstoring, 144

Subscription formscreating, 30, 144

Subscriptionsdescribed, 144enabling, 30

Symbolscurrency, 128

Symphony filesimporting into views, 445

Synopsis, 391

TTab order

specifying for fields, 151Tables

in forms, 85in the editor applet, 467in Web applications, 470programmable, 60

Tabular text filesCOL files and, 450, 453defined, 445exporting to, 453importing into views, 446, 453

Target frames, 169TeamRoom template, 442Templates

agents and, 398changing, 397, 403customizing, 398defined, 16, 397design changes and, 17examples of, 399fields in, 160linking, 402

linking to, 402list of Domino Designer, 441master, 16navigator, 241redesigning, 398replacing design and, 406replication and, 403, 407server, 17unlinking design elements

from, 409Testing

applications, 389design, 385forms, 119, 384navigators, 242views, 386

Textcomputed, 58fields, 126graphics with, 155navigators and, 233styling, 57Web, 471

Text filesexporting, 452importing to a view, 445, 446, 447

Text pop-upscreating, 262defined, 247deleting, 262editing, 262

Thousands separatorsetting, 129

TIFF files. See GraphicsTime controls

creating, 134in Web applications, 465

Time zone options, 131Times

calculating by formula, 133columns for, 223displaying, 223entering, 130formatting, 130, 132, 223

Title field, 83, 394Titles

database, 17frameset, 167window, 95

Totalscalculating, 206

Trackingdocument status, 214editors, 359

server usage, 111sessions, 436unread documents, 222versions, 93, 162

TranslateForm argument, 496Translating

applications, 27applications, and choice list

aliases, 140foreign symbols and

characters, 444Translation formulas

defined, 146setting for fields, 148

Tree style outline, 47Troubleshooting

agents, 277calendar views, 177fields, 394framesets, 172Java applets, 320

Truncationin imported text, 446

UUnlinking

templates and databases, 409templates and design elements,

409Unread marks

color, 222displaying, 222

Updall, 225UpdatedBy field, 359, 394Updating

custom controls, 331design elements, 404designs, 404documents, 393Java applet files, 31objects, 331views, 225

Upgradingframesets and, 166Web and, 24

URL commandsauthentication and, 494count parameters, 493explicit, 486guidelines, 475home page, 382implicit, 486opening documents by key, 485

Index 517

search, 113searching and, 493server commands, 477ServerRequest, 496start parameters, 493syntax, 475

URL extensionsfor Java servlets, mapping, 434

URL linkspages and, 62

URLsgenerating, 477generating in Release 4.6, 25in link hotspots, 260servlet, 433

Use JavaScript when generatingpages setting

when to use, 23User profiles

creating, 106Using This Database document

creating, 377inheriting from template, 399opening with URL

commands, 480

VValues

recalculating for computed fields,146

refreshing, 152Version control

forms for, 94Version tracking

field for, 161VersionOpt field, 162Versions

conflict documents as, 90forms for creating, 162tracking, 93, 162

View appletdescribed, 22, 216view properties and, 472

View lookupschoice list aliases and, 141choice list fields and, 139Names fields and, 137

View menuworking with framesets and, 170

View templatedefined, 215

View templatesforms as, 228

Views, 449access to, 351alias names, 181All by Category, 186calendar, 173categories and, 185categorized, and aliases, 141character sorting rules, 201character translation file (.CLS)

and, 444COL files and, 452collapsing, 207columns in, 10copying, 179creating, 179, 360default, 210defined, 10, 173deleting, 179designing, 179displaying, 210documents and, 189embedding, 215, 218entering names from columns

in, 139exporting, 443, 452, 453formatting, 210grouping, 183hiding, 183, 221, 239, 351HTML and, 210icons in, 200importing, 443, 444importing tabular text into, 446indenting in, 213indexes, 225limits on, 181lookups in, 111mapping imported columns to

fields, 448naming, 181opening, 210page breaks and, 210private, 178programming, 189public access, 360refreshing, 225renaming, 181, 391searching, 490, 491setting line counts, 221shared, 178single category, 220sorting documents in, 201styling, 207switching, 205testing, 386

troubleshooting, 177types of, 173unread marks, 222updating, 225URL commands and, 477Web, 175, 471

Vision-impaired usersdesigning for, 35

Visual Basic scriptWeb applications and, 498

WWeb

@commands and, 23, 497@functions, 463, 497actions, 220, 464agents, 464, 500authentication and, 494CGI variables, 499creating forms for, 466documents, 87example of agents, 272fields and, 465file attachments on, 102folders, 227formulas, 220hidden fields and, 90hiding design elements, 411improving performance on, 24Java applets, 498Java programming, 498JavaScript, 498LotusScript and, 464mailing features, 417navigating, 215, 240navigators, 228, 229, 469Notes/FX and, 326Perl script, 498previewing requirements for, 38private views and, 179search forms and, 113security and SSL, 350Server document and, 382simulating Notes menus for, 254tables, 470text, 471unsupported features, 24,

133, 137upgrading and, 24views, 175, 471Visual Basic script, 498

Web agent scriptsDocumentContext property, 500


Web applicationscolor for, 21designing, 21displaying text in, 57home pages for, 56Notes client and, 15

Web browsershiding paragraphs from, 153launch options, 25proxy settings for, 39setting up for previewing, 37using with Notes client, 127

Web elementsdate picker, 72embedding on pages, 71

Web pagesin frames, 169

Web usersaccess to outlines, 51attaching files, 102designing for Notes and, 157Domino applets for, 22form access, providing, 89registering for Domino

applications, 442WebQueryOpen events

agents and, 433described, 272

WebQuerySave eventsagents and, 433described, 272

Widthcolumns, 207

Window buttons, 4Window titles, 95Windows. See FramesetsWindowTitle field, 394WKSCOL statement, 449Work area overview, 4Work pane, 4Workflow

applications, 325, 442applications, planning, 414defined, 413features, 415overview, 413

Worksheet filesCOL files and, 448, 449exporting to, 452importing into views, 445

WriteExternalData parameterin Java applets, 317

WriteObject parameterin Java applets, 319

YY2K

Notes and, 129

ZZIP files, 306

Index 519

Lotus Domino Designer

Documents

Transcript of Lotus Domino Designer