Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED AS IS WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.
COPYRIGHT
Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software. Copyright 1985 1999 Lotus Development Corporation 55 Cambridge Parkway Cambridge, MA 02142
LIST OF TRADEMARKS
Domino, cc:Mail, Notes, NotesBench, NotesFlow, and Notes/FX are trademarks and Freelance, Freelance Graphics, Lotus, Lotus Components, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporation. AS/400, OS/2 Warp, RS/6000, and PowerPC are trademarks and AIX, IBM, OS/2, Presentation Manager, and SNA are registered trademarks of International Business Machines Corporation. Tivoli/Courier is a trademark of Tivoli Systems Inc., a wholly owned subsidiary of International Business Machines Corporation. All other trademarks are the property of their respective owners.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . xi 1 Introduction to Domino Designer . . . . . . . . . . . . . . . 1
Overview applications and databases . . . . 1 Starting Designer . . . . . . . . . . . . . . . . . . . . . . 3 Exploring Designer . . . . . . . . . . . . . . . . . . . . 4 Displaying, collecting, and storing information pages, forms, documents, and fields . . . . . . . . . . . . . 6 Organizing your data views and folders . . . . . . . . . . . . . . . . . . . . . Creating navigation outlines and navigators . . . . . . . . . . . . . . . . . . Structuring your display framesets .... Adding automation actions, hotspots, and agents . . . . . . . . . . . . . . . . . . . . . Getting database information design synopsis . . . . . . . . . . . . . . . . . 10 11 12 13 14 Settings for multilingual applications . . . HTML tag attributes for a Domino server . . . . . . . . . . . . . . . . . . Hide-when options . . . . . . . . . . . . . . . . . Enabling subscriptions . . . . . . . . . . . . . . Reducing database maintenance with shared resources . . . . . . . . . . . . . . . . Creating an image resource . . . . . . . . . . . . . Designing an application for maximum accessibility for people with disabilities . . . . . . . . . . . . . . . . . Previewing your design work . . . . . . . . . . . 27 28 29 30 30 31
35 37
3 Designing Outlines . . . . . . . . .
Outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an outline . . . . . . . . . . . . . . . . . Embedding an outline .............. Outline, outline entry, and embedded outline properties . . . . . . . . . . . . . . . . Selected outline properties . . . . . . . . . . . Selected outline entry properties ...... Selected embedded outline properties . . . . . . . . . . . . . . . . Using the outline applet ............... Displaying the outline in a Frameset . . . . . .
41
41 42 45 46 46 46 47 51 52
2 Creating an Application . . . . .
Domino databases . . . . . . . . . . . . . . . . . . . . Creating databases ................... Creating a database from a template . . . . . . Copying an existing Domino database . . . . Starting a database from scratch . . . . . . . . . Tips for designing Web applications . . . . . . Domino Applets ..................... Changing database and design properties . . . . . . . . . . . . . . . . . . . . . . Setting Use JavaScript when generating pages for a database . . . . Setting database launch properties . . . . .
15
15 16 16 18 20 21 22 23 23 25
4 Designing Pages . . . . . . . . . . .
Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a page . . . . . . . . . . . . . . . . . . . . Displaying a page . . . . . . . . . . . . . . . . . . Creating a home page for an application . . . . . . . . . . . . . . . . . . Styling text for the Web .............
53
53 55 55 56 57
Contents iii
.............
58 58 59 60 61 62 64 68 69 70 71 71 73 74 75 75 75
Layout regions . . . . . . . . . . . . . . . . . . . . . . . Aligning and rearranging elements in a layout region . . . . . . . . . . . . . . . Changing the size and style of a layout region . . . . . . . . . . . . . . . . . . Adding a graphic to a layout region . . . Embedded Controls . . . . . . . . . . . . . . . . . . Adding a file upload control . . . . . . . . . Adding a group scheduler . . . . . . . . . . Profile forms . . . . . . . . . . . . . . . . . . . . . . . Designing forms that prompt users for input . . . . . . . . . . . . . . . . . . . . . . Designing a form that presents a dialog box . . . . . . . . . . . . . . . . . . . . Designing a form that prompts users for information . . . . . . . . . . . . . . . . . Designing a form that lets users make selections from a view . . . . . . Designing a form for a Domino billing application . . . . . . . . . . . . . . Customizing Form processed confirmation for the Web . . . . . . . . . Customizing search forms . . . . . . . . . . . . . Tips for improving document display time . . . . . . . . . . . . . . . . . . . Testing a form before deploying it . . . . . . .
99 100 100 101 102 102 102 106 108 108 109 110 111 112 113 118 119
Changing all text styles . . . . . . . . . . . . . . Creating and formatting horizontal rules . . . . . . . . . . . . . . . . . Creating programmable tables . . . . . . . . Creating sections . . . . . . . . . . . . . . . . . . . Creating links . . . . . . . . . . . . . . . . . . . . . Adding graphics . . . . . . . . . . . . . . . . . . . Adding a background color or graphic . . . . . . . . . . . . . . . . . . . . . . Creating an imagemap . . . . . . . . . . . . . . Adding an applet . . . . . . . . . . . . . . . . . . Creating an attachment . . . . . . . . . . . . . . Embedding elements ............... Importing, pasting, or entering HTML . . . . . . . . . . . . . . . . . Launch properties for pages or forms . . . . . . . . . . . . . . . . . . . . . . . Programming a page or form Adding JavaScript header information ........... .... Adding HTML header information
..............
5 Designing Forms . . . . . . . . . . .
Forms ............................. Form Elements . . . . . . . . . . . . . . . . . . . . . . . Forms and documents . . . . . . . . . . . . . . . . . Creating a form . . . . . . . . . . . . . . . . . . . . . . Tips for designing forms . . . . . . . . . . . . . Naming forms . . . . . . . . . . . . . . . . . . . . . Making a form available to Web browsers . . . . . . . . . . . . . . . . . . Selected form properties . . . . . . . . . . . . . . . Creating a response hierarchy ........ Version tracking . . . . . . . . . . . . . . . . . . . Customizing a forms window title . . . . . . . Subforms . . . . . . . . . . . . . . . . . . . . . . . . . . .
79
79 80 81 84 85 86 88 90 92 93 95 97
6 Designing Fields . . . . . . . . . .
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a shared field Field names and labels ............... ............... ............
121
121 122 124 125 126 126 128 129 133
Defining field types . . . . . . . . . . . . . . . . . . Text and rich text fields Rich text fields on the Web . . . . . . . . . . Number fields . . . . . . . . . . . . . . . . . . . . Date/Time fields . . . . . . . . . . . . . . . . . . Formulas for Date/Time fields . . . . . . .
Creating a graphical display for Date/Time fields . . . . . . . . . . . . . . . Names fields . . . . . . . . . . . . . . . . . . . . . Readers and Authors fields ......... Creating fields to display lists of choices . . . . . . . . . . . . . . . . . . . . . Generating choices for lists . . . . . . . . . . Creating aliases for choices in a list ... Password fields . . . . . . . . . . . . . . . . . . . Formula fields . . . . . . . . . . . . . . . . . . . . Editable and computed fields . . . . . . . . . . Editable field formulas . . . . . . . . . . . . . Selected Field Properties . . . . . . . . . . . . . . Hiding fields . . . . . . . . . . . . . . . . . . . . . . . Creating a field in a layout region . . . . . . . Adding HTML attributes to a field . . . . . . Storing HTML in a field . . . . . . . . . . . . . . . Creating fields that inherit values . . . . . . . Creating a field that inherits an entire document . . . . . . . . . . . . . . . . Inheriting information in a response hierarchy . . . . . . . . . . . . . . Standard fields used in templates . . . . . . . Predefined fields with built-in functionality ............
133 136 137 137 139 140 142 144 146 148 151 153 155 156 157 157 158 159 160 160 162 164
8 Designing Views . . . . . . . . . .
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard views . . . . . . . . . . . . . . . . . . . Calendar views . . . . . . . . . . . . . . . . . . . Shared and private views Naming a view Columns ............. Creating a view . . . . . . . . . . . . . . . . . . . . . ..................... ..........................
173
173 174 176 178 179 181 184 184 185 186 187 189 191 194 197 200 201 204 205 205 205 206 207 210 210 210
Adding titles to columns . . . . . . . . . . . . Adding categories to views . . . . . . . . . . Categorizing in the All by Category view . . . . . . . . . . . . . . . . . Generating category names ......... Programming which documents display in a view . . . . . . . . . . . . . . . Table of document selection conditions for views . . . . . . . . . . . . . . . . . . . . . Adding programming to columns . . . . . . . Table of simple functions for columns . . . . Displaying an icon in a column . . . . . . . . . Sorting documents in views ........... Overriding alphabetical sorting with a hidden column . . . . . . . . . . . . . . . . . Customizing which column links to Web documents . . . . . . . . . . . . . . . . Adding pass-thru HTML to a column . . . . Using a column to switch to another view . . . . . . . . . . . . . . . . . . Generating column totals, averages, and percents . . . . . . . . . . . . . . . . . . . Table of view, row, and column styles ... Using HTML formatting for views and columns . . . . . . . . . . . . . . . . . . . Default views . . . . . . . . . . . . . . . . . . . . . . . Defining what users see when they open views . . . . . . . . . . . . . . . . . . . .
Fields for version tracking . . . . . . . . . . . . . Fields that prompt users to select folders . . . . . . . . . . . . . . . . . .
7 Designing Framesets
.....
165
165 166 168 170 171 172
Overview of framesets . . . . . . . . . . . . . . . . Creating a frameset . . . . . . . . . . . . . . . . . . Providing content for a frame . . . . . . . . . . Setting the style for frames ............ Launching a database into a frameset . . . . Launching a document or page into a frameset . . . . . . . . . . . . . . . . . . . . .
Contents v
Formulas that look for values in columns and views . . . . . . . . . . . . . Indenting response documents . . . . . . . . . Formulas for response columns . . . . . . . . . Displaying views in Web applications . . . . . . . . . . . . . . . View applet . . . . . . . . . . . . . . . . . . . . . . . . Creating an embedded view or embedded folder pane . . . . . . . . . . . Show single category in embedded views . . . . . . . . . . . . . . . Setting line counts in embedded views . . . . . . . . . . . . . . . Hiding a view . . . . . . . . . . . . . . . . . . . . . . Identifying unread documents ......... Formatting date and time columns . . . . . . . . . . . . . . . . . . Displaying numbers in columns . . . . . . . . Refreshing view indexes . . . . . . . . . . . . . . Designing folders ................... Designing a form as a view or navigator template . . . . . . . . . . . . . .
211 213 214 215 216 218 220 221 221 222 223 224 225 227 228
......
Overriding an embedded navigator with a navigator template . . . . . . . . Importing a navigator into a form, subform, page, or document ......
Testing navigators . . . . . . . . . . . . . . . . . . .
10 Automation in Applications . . . . . . . . . . . . . .
Automation . . . . . . . . . . . . . . . . . . . . . . . . Actions Hotspots ........................... ..........................
245
245 246 247 248 249 253 257 258 260 261 262 263 265 266 267 269 271
Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an unshared form action or view action . . . . . . . . . . . . . . . . . . . . Action bar . . . . . . . . . . . . . . . . . . . . . . . . . Creating and inserting shared actions . . . . Creating a link . . . . . . . . . . . . . . . . . . . . . . Creating a button . . . . . . . . . . . . . . . . . . . . Creating a text pop-up . . . . . . . . . . . . . . . . Creating a formula pop-up . . . . . . . . . . . . Creating an action hotspot . . . . . . . . . . . . . Creating a program for an event . . . . . . . . Building an agent ................... Options for running agents . . . . . . . . . . . .
9 Designing Navigators . . . . . .
Navigators . . . . . . . . . . . . . . . . . . . . . . . . . Creating a navigator . . . . . . . . . . . . . . . . . Adding graphic objects to navigators . . . . Adding and enhancing graphics in a navigator . . . . . . . . . . . . . . . . . . Adding text to and highlighting a navigator object . . . . . . . . . . . . . . . . Adding hotspots to navigators . . . . . . . Automating navigators . . . . . . . . . . . . . . . Navigators, imagemaps, and outlines . . . . Displaying a navigator when users open a database . . . . . . . . . . . . . . . . . . . . Hiding navigators . . . . . . . . . . . . . . . . . . .
229
229 230 231 232 233 234 234 238 239 239
Selecting where to run a scheduled agent . . . . . . . . . . . . . . . Examples of agents to run before Web users open or save documents . . . . . . . . . . . . . . . . . . . . Setting up agent security . . . . . . . . . . . . . .
272 273
Troubleshooting agents . . . . . . . . . . . . . . . Simulating the running of an agent ... Agent Log . . . . . . . . . . . . . . . . . . . . . . . Notes server console commands . . . . . . Agent Manager debugging information AgentRunner ..........
277 278 279 280 282 283 284 287 291 292 294 295 296 299 299 300 302
Selecting, running, deleting, and copying applets . . . . . . . . . . . . . . . . Refreshing and exporting applet files . . . . . . . . . . . . . . . . . . . . Setting security for applets . . . . . . . . . . Saving applet data ................ Tips and troubleshooting for Java applets . . . . . . . . . . . . . . . . . . .
NotesLog Class . . . . . . . . . . . . . . . . . . . .................... Simple actions for automation components . . . . . . . . . . LotusScript for automation components . . . . . . . . . . . . . . . . . . . Restricted LotusScript and Java agent operations . . . . . . . . . . . . . . . . Formulas for automation components . . . . JavaScript for automation components . . . Table of supported JavaScript objects for automated components . . . . . . . Importing Java programs ............. ...... Creating Java programs for agents
325
325 327 328 329 330 331 331 331 333 334 335 336 337 337 339
303
303 304 305 306 307 308 309 309 310 312
Contents vii
Publishing actions . . . . . . . . . . . . . . . . . . . Exchanging data using Notes/FX . . . . . . . Preparing a form to exchange data . . . . . .
Encrypting documents automatically . . . . . . . . . . . . . . . . . . Creating a field that generates a list of secret encryption keys . . . . . . . . . Restricting who can edit a section . . . . . . . Restricting who can access a section of a document . . . . . . . . . . . . . . . . . . . Attaching electronic signatures to documents and sections in Notes applications . . . . . . . . . . . . . . How Designer stores and verifies electronic signatures in Notes applications . . . . . . . . . . . . . .
347
347 349 350 351 351 353 353 354 355 355 356 356 359 360 360 361 363 364
371
372
375
375 375 377 377 379 380 381 382 383 383 384 385 386 388
............
389 391 391 391 393 394 395 397 398 401 402 402 403 404 406 407 408 409 411
422 423
Renaming a database . . . . . . . . . . . . . . . . . Renaming design elements . . . . . . . . . . Design synopsis . . . . . . . . . . . . . . . . . . . . . Updating documents after redesigning a form . . . . . . . . . . . . . . . . . . . . . . . . Checking field values in a document . . . . . Using agents to update documents affected by form changes . . . . . . . . . Templates ......................... Creating templates . . . . . . . . . . . . . . . . . . . Creating a design library template . . . . Linking a database to a template ..... Linking individual design elements to a template . . . . . . . . . . . . . . . . . . Making and distributing design changes . . . . . . . . . . . . . . . . . Refreshing a design . . . . . . . . . . . . . . . . . . Replacing a design . . . . . . . . . . . . . . . . . . . Design changes and replication . . . . . . . . . Preventing design changes . . . . . . . . . . . . Hiding the design of a database ........ Hiding design elements . . . . . . . . . . . . . . .
425
425 428 429 430
431
431 432 434
Appendix A Domino Designer Templates . . . . . . . . . Appendix B Importing to and Exporting from Views . . . . Appendix C Developing Applications Using MAPI . . . . . Appendix D Features to Avoid Using in Web Applications . . . . . . . . . . . . . . . . Appendix E Programming a Web Site . . . . . . . . . . . . . . . . . Index . . . . . . . . . . . . . . . . . . . . . .
413
413 414 415 416 417 417 421 421 422
Contents ix
Preface
This guide describes how to create all the design elements used in building Domino applications, how to share information with other applications, and how to customize applications. This guide is intended for developers who are creating applications with Domino Designer.
Chapter 11, Including Java Applets in Applications, describes adding Java applets to forms, documents, and pages. Chapter 12, Including OLE Objects in Applications, illustrates ways to design applications that use OLE technology to integrate data from other applications. Chapter 13, Restricting Access to and Securing Parts of an Application, briefly describes Designer features for limiting access to parts of an application. Chapter 14, Completing an Application and Managing Design Changes, describes how to document an application and how to test it before deployment, as well as how to make, control, and distribute design changes to applications that are already in use. Chapter 15, Creating a Workflow Application, describes how to create a workflow application by using automatic mailing features. Chapter 16, Connecting to Enterprise Data, briefly describes tools and techniques for connecting a Designer application to enterprise data. Chapter 17, Including Java Servlets in Web Applications, describes creating and running Java servlets on a Domino Web server. Appendix A, Domino Designer Templates, lists the templates available with Domino Designer that are specifically intended for use by application developers. Appendix B, Importing to and Exporting from Views, provides tips and restrictions on moving data to and from views. Appendix C, Developing Applications Using MAPI, provides information on the available support for accessing Notes mail files. Appendix D, Features to Avoid Using in a Web Applications, identifies features that are not applicable to Web browsers or are not yet supported for them. Appendix E, Programming a Web Site, contains information about using Domino URL commands for programming related to Web applications, such as formulas, Java, JavaScript, Perl and CGI scripting, and Visual Basic script.
Preface xiii
Provides information on managing databases, including putting databases into production, setting up access control lists and replication, and maintaining databases.
Domino Designer Programming Guide Volume 1: Formula Language Domino Designer Programming Guide Volume 2: LotusScript Classes Domino Designer Programming Guide Volume 3: Java Classes LotusScript Language Guide
Notes Help *
Step by Step
**
Release Notes
Administration Help
Setting up a Domino Server Moving to Notes and Domino Release 5 Configuring the Domino Network Administering Domino Clusters Administering the Domino System, Volume 1 Administering the Domino System, Volume 2
Designer Help
Application Development with Domino Designer Domino Objects Domino Designer Templates Guide Posters Domino Designer Programming Guide, Volume 1: Formula Language Domino Designer Programming Guide, Volume 2: LotusScript Classes Domino Designer Programming Guide, Volume 3: Java Classes LotusScript Language Guide Domino Enterprise Integration Guide
Preface xv
Databases
A database is the container for the data, logic, and design elements in your application. Design elements are building blocks you use to create your application. Design elements include: Pages Forms Outlines Navigators Views Folders Framesets Shared Resources Agents
Creating a database
There are three ways to create a database: Using a template. The fastest way to create a database is to use one of the Domino templates included with Designer R5. Designer includes templates for creating a variety of applications. Applications created using one of the Designer templates can be used as is or customized. To decide if there is a template that is right for you, see the Table of Domino Designer templates. Copying an existing database. If you have access to a database that already has all the elements you are looking for, you can copy the design and create a new database with the same features. Once you have created the database, you can customize it to meet your companys needs. Starting from scratch. If the database you need is unique, the best method for you is to start from scratch. When you create a database from scratch, you start with a blank or empty database and create all of the design elements. In order to begin creating your application, you need to start Designer.
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
Exploring Designer
Building a great application requires the right tools. You can think of Designer as your workshop it contains all the tools you need to build a great application. Before you get started building, well explore the work area.
Tabbed windows Menu bar Design bookmarks Design list Design pane Work pane Design action buttons Properties box Preview button buttons
Purpose Presents context-sensitive menus of Designer commands. Launches the browser of your choice to preview your work. Navigates among the open windows on your workspace.
Design action buttons Perform actions such as creating elements, saving, closing. Properties box button Opens the properties box for the active design element. Design pane Design bookmarks Design list Work pane Contains the Design bookmarks icons and the Design list. Opens lists of bookmarked applications. Takes you to Work pane of a design element or resource. Lists everything in the database for the currently selected design element in top level view. Once an element is opened, becomes the Work area for that element.
When you open a design element such as a page or form, you will be in the work area for that design element. In addition to items in the Designer Workspace, the Programmers pane appears.
Reference tab
Objects tab
Script area
Purpose The Reference tab of the Info List replaces the R4.x LotusScript browser window and is language-sensitive. The contents of the Reference tab change depending on the language selected. If you are editing in the Formula language, the window contains @Commands, @Functions and fields. If you are editing in LotusScript, the window contains LotusScript information. If you are editing in JaveScript, the window contains information about the Document Object Model. If you are editing in Java, the window contains Java-related information. The Objects tab of the Info List lets you navigate between objects and events in the Programmers pane. To work on an object, select it to expand its list of properties and events. If you select a property or event, the script area of the Programmers pane changes to show the code that describes it. Events and properties that are already programmed appear in a darker color. Enter formulas in the Script area. Formulas can be written in Formula language, LotusScript, JavaScript, or Simple Actions.
Objects tab
Script area
Properties boxes
Properties boxes are tools for working the various pieces of your application. With them you can select or modify settings for the element you are working with. Properties boxes have tabbed panes, and each pane gives you access to different attributes or options. In most windows, rightclicking will open up the Properties box for that design element. You can also choose Design - <element> Properties from the menu.
Properties boxes are context-sensitive so you can leave them open on your workspace and they will change to reflect the element that you are working with. Collapse a Properties box by double-clicking the top of the box. When collapsed, some of the properties boxes become context-sensitive tool bars.
Displaying, collecting, and storing information pages, forms, documents, and fields
How you display, collect, and store information is an important part of any application. The design elements you use to accomplish these tasks are pages, forms and documents, and fields.
Pages
A page is a database design element that displays information. Pages are a familiar Web concept. Almost every Web site has a home page a page
that contains information about the company, graphics that enhance the page, and links that take you to other places within the site or elsewhere on the Web.
Pages can be used anytime you are displaying information to the user. Pages can contain: Text Tables Graphics Applets Embedded objects such as navigators Links Pages often work in conjunction with framesets to display graphics, site navigation, or applets. For more information on pages, see Designing Pages.
forms can be used to collect information. A form provides the structure for creating and displaying documents. Documents are the elements that store data in the database.
When you create a form in Designer, you can choose to have a user open the form in the Notes client from the Create menu. On the Web, you provide the user a button or action that opens the form. When the user fills out the information and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data. For more information on forms and documents, see Designing Forms.
Fields
Fields are the element that collect data. You can create fields only on forms. Each field on a form stores a single type of information. A fields data type defines the kind of information a field accepts.
You can create fields in the following data types: Text Date/Time Number Dialog List Checkbox Radio button Rich Text Authors Names Readers Password Formula You decide if a field is editable that is, populated by user input or calculated that is, based on formulas. You can also program fields to retrieve data from other Domino applications or from external sources. You can even create shared fields, which can be used in many forms within the same database. The information collected in fields is stored in documents. For more information, see Designing Fields.
Views
A view is a sorted or categorized list of documents. Views are the entry point to the data stored in a database. Every database must have at least one view, although most databases have more than one view. Views select the documents they display programatically. You can create a view that shows all of the documents in your database or only some of the documents, based on a formula. Views can sort the documents they display by a field on the form, such as date, category, or author. You can create views that are hidden from users but organize your data so that other applications can retrieve the information from the documents. Views can have multiple columns that display any of the information contained in the document.
Folders
A folder is a container that stores documents. Folders have the same design elements as views, and you design folders in much the same way as a view. The difference between folders and views is that a view always has a document selection formula that collects and displays documents automatically. A folder remains empty until users or programs add documents to the folder. For more information on folders, see Notes 5 Client Help.
Outlines
You can create an outline to customize the Folder pane of an application. An outline is the skeleton of your application: each outline entry represents a key piece of the application. An outline can include background graphics, custom icons, links, or actions. When the outline is embedded on a page or form, users can click on the outline entries, which will take them where you want them to go. The process of creating a navigation structure with an outline involves three steps: Create a new or default outline and create an outline entry for each piece of the application you want to include in the navigation structure or site map. Embed your outline on a form or page. Format the display of the embedded outline. You can include the page or form that the outline is embedded on in a frameset if you choose. You can also use an outline to plan your application before you create any design elements.
Navigators
Navigators are graphical roadmaps that direct users to specific parts of a database. They let users find documents or take actions without having to open views. Navigators are like imagemaps. You can create hotspots on a graphic that take the users to links within or outside of your application. You can embed navigators on forms or pages. Navigators can take the place of the folder pane or work in conjunction with it. For more information on navigators, see Designing Navigators.
Designer lets you: Create an effective multi-paned user interface for your applications Control frame attributes such as size, scrolling, border colors and width, and frame spacing
Determine frame source content at runtime Create programmable links that are maintained automatically Set a frameset to launch automatically when a database, form, or page opens For more information on framesets, see Designing Framesets.
Actions
Actions automate tasks such as mimicking the Notes menus or tasks defined by formulas or a LotusScript program. Users click a button, hotspot, or pick from the Action menu to execute the action. In particular, use actions to simulate Notes menu items for web browser users.
Hotspots
A hotspot is text or a picture that a user can click to perform an action, run a formula or script, or follow a link. The hotspot can be a link to another web site, database, or element in a database; a button; a pop-up; or an action.
Agents
Agents are programs that perform a series of automated tasks according to a set schedule or at the request of a user. An agent consists of three components: when it acts (the trigger), what documents it acts on (the search), and what it does (the action). Use agents to set up user-activated tasks, or background tasks, in any part of a Domino application. Agents can be simple, such as moving documents to a folder, or complex, using Java programs to run multiple automated tasks at scheduled times. Agents are stored with databases, but you can use them to run automated tasks for views, documents, fields, and databases. For more information, see Adding Automation to Applications.
Domino databases
All Domino applications begin with a Domino database. Domino databases are the containers for your application. Databases hold the data, logic, and design elements for your application. Your Domino application can be made up of one or more Domino databases.
DATABASE
DOCUMENT
Fields
With Designer, you create one application to use on both your intranet and the Internet. The structure of a database is the same whether for the Notes client or a Web browser. What makes a database a Web database is the viewing mechanism: users view it through a Web browser instead of the Notes client. You do all design work in Designer and use the same design elements forms, fields, views, outlines to display and organize the content.
15
Creating databases
There are three ways to create a new database: Using a template Copying an existing database Starting from scratch
1. Choose File - Database - New. In the server field do one of the following: Leave Local selected to store the new database on your hard disk. Select or enter a server name to store the new database on a server. This allows multiple people to work on the database design. 2. In the Title field, enter a title for the new database. The Title can have a maximum of 32 characters. Note As you type a title, Designer adds a name to the File Name field. You can accept this database file name or change it. Database file names can be up to 8 characters and end with the file extension .nsf. If you plan to use the database you are creating as a template for other databases, use the file extension .ntf. 3. Select a template from the list. To display additional templates, do one following: Click Show advanced templates and select a template from the list. Click Template Server to use templates that reside on a server. 4. (Optional) Click Encryption, select Locally encrypt this database using:, select an encryption type, and click OK. For information on encrypting a database, see Notes and Domino encryption in Managing Domino Databases. 5. (Optional) If you are creating a database that will be on a Domino Release 4.x server, click Size limit and select a size (in gigabytes), and click OK. 6. (Optional) Click the Advanced tab and select the options that you want applied to your database. Click OK. For a description of the advanced options, see Managing Domino Databases. 7. Click OK. 8. (Optional) Choose File - Database - Properties, click the Design tab, and deselect Inherit design from template. This will prevent the new database from inheriting design changes from the master template whose design the database is based on.
6. (Optional) If you are creating a database that will be on a Domino Release 4.x server, click Size limit and select a size (in gigabytes), and click OK. 7. Select Database design only so that the databases documents will not be copied to your new database. 8. Deselect Access Control List so that the original databases access control list will not be copied to your new database. 9. Click OK. 10. (Optional) Choose File - Database - Properties, click the Design tab, and deselect Inherit design from template. This will prevent the new database from inheriting design changes from the template whose design the database is based on.
Domino Applets
When users run a Domino application from a Web browser, some Domino design elements are more effectively presented to Web users using Java instead of HTML. Domino provides Java applets for these design elements so that the interface for Web users is closer to the interface for Notes client users. You can easily enable the Java applets when you create the design element. When you consider whether to use the Java applets or HTML, keep these points in mind: The applets provide a more interactive interface. The Domino applets will require download time to the Web user. The applets use the Java Developers Kit (JDK), Release 1.0.2 to support Web users with any java-enabled Web browsers. The only fonts supported are typically Courier, Helvetica, and Times. For a complete description of how the applets work, see the description for each design element: Outline applet The outline applet lets Web users work with outlines embedded in a page or form. View applet The view applet lets Web users use many of the Domino view features, including column resizing, multiple document selection, and section collapse/expand without page regeneration. Action bar applet The Action bar applet lets users scroll and easily view and select sub-actions. Editor applet The editor applet lets Web users change the font, color, size, and style for text in rich text fields.
Documents and navigators display faster Documents and navigators display more because hotspot formulas are not slowly because the hotspot formulas are evaluated until users click each hotspot. all evaluated at the display time. Domino doesnt generate a Submit button automatically. Create a Submit button, hotspot, or action whose formula includes these commands: If there are no buttons, Domino automatically generates a Submit button at the bottom of the form. Domino only recognizes one button on a form. If there are multiple buttons on the form, @Command([FileSave]); Domino recognizes only the first button @Command([FileCloseWindow]) and converts it to a Submit button You can have multiple buttons on a form. automatically. The following commands are supported on the Web: @Command([FileCloseWindow]), @Command([FileSave]), and @Command([ViewRefreshFields]) The following commands are not supported on the Web: @Command([FileCloseWindow]), @Command([FileSave]), and @Command([ViewRefreshFields]) Domino checks the formulas before displaying pages. Actions that contain unsupported @commands or @functions will not be displayed on the Web.
Upgrade issues for Use JavaScript when generating pages for a Web database
Elements with unsupported formulas that Domino hid automatically in Release 4.5 may now display if you select the Use JavaScript property. With the property selected, Domino doesnt check any hotspot or button formulas before using JavaScript to generate the page. Web users see all buttons, actions, and hotspots even those that contain @commands and @functions that arent supported for Web applications. Revise any formulas that relied on hotspot formulas being evaluated at display time. Make sure these formulas evaluate correctly after the user clicks the hotspot, not before.
Replace Release 4.5 attachment fields with Embedded Element - File Upload Controls if you set the Use JavaScript property. The Use JavaScript setting disables @Command([EditInsertFileAttachment]) hotspots used to create attachment fields in Release 4.5, because the hotspot is not evaluated when the page is displayed. The Use JavaScript property can cause unexpected results because the URL generation in Release 5.0 is different than it was in Release 4.6. Check any formulas that rely on accessing a Query_String or Path_Info URL fragment. The URLs will frequently be different. For example, POST URLs that included ?CreateDocument and ?SaveDocument are no longer generated in Release 5.0. The new POST URL is a variation of ?OpenForm or ?EditDocument.
Displaying a document preview automatically You can automatically display a preview pane that shows the contents of the highlighted document in a database view before the user opens the document. This gives users a sense of what is in a database without having to open and close each document. If you do not display the preview pane automatically, users choose View - Document Preview to access it. 1. Select or open the database you are designing and choose File Database - Properties. 2. Click the Launch tab. 3. Click the Preview Pane Default button. 4. Choose a location where the document preview pane will display. 5. Check Maximize document preview on database open to automatically display the preview pane.
Class: used to specify a CSS class for an object. For example, if the objects name is ZipCode, the class could be Numeric.CSS styles are defined in the HTML Head Content event for a form or page. Style: used to apply a specific CSS styles to an object. For example, if the objects name is ZipCode, the class is Numeric, the style could be font-size:10pt, or if you have more then one value, separate them with a semi-colon, for example, font-size:10pt; color:blue. Title: used to prompt the user to enter a value for the object. For example, if the objects name is ZipCode, the class is Numeric, the style is Bold, the title could be Enter your Zip Code. The title displays differently on different browsers. Other: used for additional HTML tag attributes and must be written as pure HTML code. For example, instead of writing ZipCode in the Name/ID box, you have to write ID=ZipCode.
Hide-when options
Designer lets you hide many of the design elements and components of an application. If hide options are available, the hide when tab appears on the properties box for that element. To set hide-when options, select the element you want to hide and open the properties box for that element. 1. Click the Hide tab. 2. For basic options, select all situations in the Hide paragraph when document is: section in which the components dont need to be seen by users. 3. For programmer options, select Hide paragraph if formula is true and write a formula in the design pane to describe the situations in which users dont need to see the layout region. You can hide elements, including its text, graphics, and fields, in any of these situations. When users read, hide information that is useful only when users create or edit documents. When users edit, print, and copy, hide information that is useful when users read documents.
If an element is hidden Then: when: Previewed for reading Previewed for editing Opened for reading The hidden information isnt visible when users read documents in the document preview pane. The hidden information isnt visible when users work on documents in Edit mode in the document preview pane. The hidden information isnt visible when users open documents in Read mode. A layout region that cant be read cant be printed either. The hidden information isnt visible when users work on documents in Edit mode. The hidden information isnt visible on printed documents. The hidden information isnt visible when information is copied to and pasted from the Clipboard. This setting doesnt affect documents copied at the view level. A formula determines the circumstances in which information is hidden.
Enabling subscriptions
Subscriptions work in conjunction with the Headlines database. The Headlines database enables users to stay informed of current events both within their company and on the Web. The headlines database lets users subscribe to databases that are of interest to them and then receive notification when a posting meets their subscription profile. To design a database that can be subscribed to by users: The database must reside on a server that allows subscription monitoring. The Domino administrator must enable subscriptions on the server document. See Administering the Domino System for more information on enabling subscriptions at the server level. The database must enable headline monitoring. This is enabled on the Advanced tab of the Database Properties box. It is enabled by default. For more information about performance issues with headline monitoring, see Prevent headline monitoring in Managing Domino Databases. The database must contain a subscription form. You can design one yourself or copy the subscription form from the headlines.nsf database installed with the Notes client. To copy the subscription form from the headlines database to your database, see To copy and individual design element. If you are creating a subscription form from scratch, you must use a formula field. For more information, see the topic Formula fields.
Shared Fields You can define a field for use on more than one form. For example, many forms have a creation date field; you can define this field once and reuse it. When you define a field as a shared field, Designer displays the field with a dark border and adds the field name to a list of shared fields available for use in a database. For more information, see the topic Creating shared fields. Subforms A subform is a collection of fields you plan to use in more than one form. For example, you might create a corporate letterhead in a subform and then use the subform on a variety of business forms. For more information, see the topic Subforms. Script libraries A script library is a place for storing and sharing LotusScript programs and Java code. The script library contains (Option), (Declaration), Initialize, Terminate, and user scripts. All scripts in a database can share the code in a library in that database. For more information about Script Libraries, see Using script libraries in the Programming Guide. Shared Java files For large Java applets with multiple files, it is most efficient to store some of the related files as shared resources in the database. When you set up files as shared resources, all the applets can use a single copy of the file, instead of each applet storing its own copy. Then, if a file requires updating, you only need to update one file. For more information, see the topic Setting up shared applet resources. Shared Actions Use shared actions in forms or views to set up user-activated tasks. You can make shared actions available in the Actions menu or as buttons on the action bar. In particular, actions let users complete tasks when accessing Domino databases on the Web. For more information on shared actions, see Create and insert a shared action.
To Create an image resource 1. Expand Resources in the Design pane. 2. Select Image from the list of Resources. 3. Click the New Image Resource button. 4. Select gif, bmp, or jpeg in the Files of Type: list. 5. Select one or more graphic files you want to include as image resources. 6. Click Open. Designer creates an entry for each of the files you select.
2. In a gif, bmp, or jpeg file, line up the images horizontally separated by a one-pixel space or line. 3. Create an image resource entry for image file.
4. On the Basics tab of the Image Resource Properties box, choose the number of images across Note The order of the states is predetermined and cannot be changed. However, if you want to take advantage of only two of the states, for example, if you want to use a different image in the normal state (the first position) only, copy the second image two or three times so that the different image is in the first position.
Using a vertical image set Use a vertical image set for icons you add to the bookmark bar. The bookmark bar can display small, medium, or large icons if the image resources for the icons are part of a vertical image set. A vertical image set includes an icon in three different sizes. (Users choose what size icons they want displayed in the bookmark bar in their User Preferences.)
To create a vertical image set, follow the steps for creating a horizontal image set but, in Step 2, line up three differently sized images vertically, with a one-pixel space between each one, and in Step 4, select how many images down you are using. In addition, use a background around the images to create a rectangle. To colorize grays If you want an image to blend with the users system colors, select the option Colorize grays on the Basics tab of the Image Resource Properties box. When enabled, the grays in an image that correspond to the Lotus
Chapter 2: Creating an Application 33
palette grays change to a corresponding color scale using the color scheme of the users operating system. This feature lets the image resources blend in with the other elements of the users system, such as dialog boxes and menu bars. Inserting an image resource 1. Open a form, document, or page. 2. Place the cursor where you want to add the image. 3. Choose Create - Image Resource. 4. Choose the type of image gif, jpeg, or All Images from the Image Type list. 5. Select the name of the image file. 6. Click OK to display the image in the form, document, or page. Tip To use the images among multiple databases, put the image into a template and inherit the resources into all the databases where theyre needed. For more information on creating templates and inheriting design, see Completing an application. Making design changes to an image resource To make design changes to a graphic used as an image resource, export the image to a graphics program. Once the changes are made, update the image resource and distribute the design changes. To export an image resource 1. Select the image you want to redesign. 2. Choose Image - Export. 3. Select the directory you want to copy the image to. 4. Click Open. To distribute design changes for an image If the image you are using changes, you can distribute those changes wherever the image appears in the database. 1. Select the image that has changed and choose Resource - Refresh. 2. Select the new image from the filing system. It doesnt matter if the name of the image has changed. 3. Click Open. Designer automatically updates the image in all of the places it is referenced in the application.
Use Action buttons that echo items in the Action menu. Screen readers cannot always provide information about action buttons. By echoing action buttons in the Action menu, you ensure accessibility in this area. To make sure that an action button is echoed on the Action menu, open the properties box for the action and select Include in Action Menu. Avoid: Using Java applets as the sole means of navigating or performing an action. Java accessibility is currently not widely supported, and a keyboard-only user cannot navigate to a Java applet in many browsers. Excessive use of embedded objects. Although these are keyboardaccessible, navigating through too many objects can be a burden for keyboard-only users. Excessive use of framesets. It is laborious for keyboard-only users to navigate through framesets. The fewer frames used in an application, the easier it will be for a keyboard user to navigate. Using color and graphics as the sole means of communicating meaning in your application. To test if your application is usable for color-blind users, set your display to monochrome and check all graphics for legibility. Very small text. Some operating systems support a large font user preference, but this preference is not respected by all objects in an application. Avoid using text smaller than 10 point Helvetica. If accessibility is a major priority for your application, you may want to consider creating an alternate interface for your application using only text and non-embedded controls. For more information about accessibility, visit the IBM Special Needs Web site at http://www.austin.ibm.com/sns/ or the W3 Web Accessibility Initiative (WAI) site at http://www.w3.org/WAI.
To preview in Notes or in the default Web browser using the preview icons 1. Open the design element you want to preview or select it from the Design list. 2. Make design changes if necessary. 3. Click the icon on the Menu bar that represents the browser in which you want to preview. You will be prompted to save any changes. If you do not save your changes, Designer will preview your work without the changes.
Notes client Domino Internet Explorer Netscape version 3.x Netscape version 4.x
To shut down the HTTP process that runs the Web Browser preview without exiting Notes, choose File - Tools - Stop Local Web Preview Process.
1. In Designer, choose File - Preferences - Location Preferences. 2. Next to Proxy, click the Advanced icon. 3. Next to No proxy for these domains, add these case-sensitive entries:
localhost <Domino server name>
4. Click OK. 5. Close and save the Location document. To override proxy settings for additional browsers If you use alternate browsers, you must set them up for previewing. See the Help for your browsers for more specific information on proxy settings. 1. Open each browser, and then open its Proxy settings page. 2. Specify these case-sensitive entries:
localhost <Domino server name>
3. Click OK.
Outlines
Outlines, like imagemaps and navigators, are tools that let you provide navigation in your application. All databases come with a default navigation structure called the folder pane (also referred to as the navigation pane). The folder pane, by default, displays a list of shared views and shared folders. In the Notes client it appears in the left pane, and in a Web browser, the folder pane displays at the top left of the browser window. When users click on the view or folder they want to access, that view or folder is displayed in the right pane. If you want create a custom navigation structure for your application, create an outline. In addition to jumps to all of the views and folders in your database, you can include actions or links to other elements. You can create an outline that navigates through your entire application or site, or through part of it. You can also use outlines to help you plan your application. To do so, you create an outline that represents the skeleton of your application, in which each outline entry represents a design element or component of the application. Once you create an outline, you embed it on a page or form. This displays it to users, who use it as a site map or navigational structure. Users can click on the outline entries to take them where you want them to go. The process of creating a navigation structure using an outline involves the following steps: 1. Create a new blank or default outline. 2. Create outline entries for jumps or actions you want to present to the user. 3. Embed your outline on a form or page or in a rich text field of a document.
41
4. Format the display of the embedded outline. 5. (Optional) Include embedded outline in a frameset. Some important features of the Outline include: You can completely customize an outline, reordering how items appear in the folder pane as well as including jumps to elements outside of your application. You can control how the outline appears to users by changing text and button styles and adding icons from your databases shared resources. Outline entries are fully programmable. You can add logic that controls how outline entries are rendered by the Notes client or Web browser. By combining the outline with Framesets, your application can include multiple outlines that launch links in target frames.
Creating an outline
You can create an outline from scratch or generate a default outline. If you are using the outline to help you plan your application, you can create the outline entries prior to designing the actual design elements. Begin by creating a new outline and then adding entries for each element you plan to include in your navigator or site map.You can include outline entries for any element that will be part of your application or site, such as jumps to pages, documents, views, folders, Web pages, or other Domino databases. Outline entries represent each piece or planned piece of your application or navigation structure. Outline entries can also be clickable actions or can be top-level categories that organize other entries. You can also choose what icons display with the entry. You can organize your application into units and create multiple outlines to represent the different portions of your application. If you have already created all of your design elements or are working with a database created from a template, you can begin by creating a default outline and customizing it. To create a new outline from scratch 1. Click Outlines in the Design pane. 2. Click New Outline. 3. Add outline entries for each design element, action, or link you want to include in the outline.
To create a default outline The default outline creates outline entries for all the views and folders in the database. In addition, the default outline contains placeholders called Other views, Other folders, Other private views, and Other private folders. Click Generate Default Outline. To add a new outline entry: 1. Click New Entry. 2. In the Outline Entry Properties box, enter the label you want appear in the outline, for example, Home Page or Main View. 3. Enter a type for the element in the Content field. If you are creating a jump to a named element that does not yet exist, Designer will display a prompt letting you know that you will need to create the element later. Jump to: A URL (enter entire URL including protocol, for example http://www.lotus.com) A link - such as to an anchor, document, view, or database link A named element - such as a Page, Form, or View Perform an action - such as open or create a document. To enter an action, click the @ button, and enter a formula. None (use this to create a top-level category for nesting entries). 4. (Optional) Enter an alias for the outline entry. 5. (Optional) Enter the target frame for the jump or action. If you have not yet created your frameset, you can either enter the name you are planning to use in your frameset or you can add this entry later, after you have created your frameset. Note You can cut and paste outline entries from other outlines. Once you have created outline entries for the elements that you are including in your application, you can reorder the elements or create a hierarchy between them.
To reorder elements in an outline Create the order for the outline entries as you want them to appear to the user. You can reorder the elements after you create them. To reorder the elements in an outline: Select one or more outline entries in the Design pane and drag to move them up or down in the list. To create a hierarchy between elements Outline elements can have a hierarchy, that is, there can be top-level entries and sub-level entries.
This is especially useful, for example, if you would like to create nested outline entries. To create a hierarchy between elements do one of the following: Select one or more outline entries and click the Indent Entry button (or press the TAB key) to indent the element one tab stop to the right. Select one or more outline entries and click the Outdent Entry button (or press SHIFT-TAB) to outdent the elements one tab stop to the left.
To delete an outline entry 1. Select the outline entry that you want to delete. 2. Press DEL or choose Edit - Clear.
Embedding an outline
To use an outline as a navigational device, it must be embedded on a form, page, or rich text field of a document. Whether you choose to embed your outline on a form, page, or document will depend on how you want to use it. You can embed the outline on a form so that each document created from that form includes the embedded outline. The outline then presents an easy way for users to navigate to other views, create a new document, move to the next document, and so on. For example, in a Discussion database, you can embed the outline on the Main Topic form. When an user creates a document with that form, the outline appears on the document. Embed the outline on a Page if you want to use the outline as part of a Frameset or as part of your home page. Embed the outline on multiple pages if you need to have several occurrences of the same outline with different styles (for example, one outline with only text, another with graphical buttons). If you want several navigational structures in one application you can do two things. You can create one outline and embed it several times on different pages, or you can create several different outlines and embed each on different pages. Embedding the outline on a page 1. Click Outlines in the Design pane. 2. Open the outline you wish to embed. 3. Click Use Outline on the action bar at the top of the Design pane. The embedded outline appears on a new page with the default style applied to it. 4. Choose File - Save. You will be prompted to enter a name for the Page which the outline is now embedded on. Embedding the outline on a form, page, or document 1. Open or create the form, page, or document you want to embed the outline on. 2. Position the cursor where you want the outline to appear. In a document you must be in a rich text field. 3. Choose Create - Embedded Element - Outline. Once you have embedded your outline, you can format it.
To add an image to appear next to your entry 1. Select an outline entry and choose Design - Outline Entry Properties. 2. On the Outline Entry Info tab click the folder icon in the Image section and select the shared image resource for your graphic. 3. (Optional) Click the @ button to use a formula to control the display of the image. 4. (Optional) If you do not want to display an icon with the outline entry, select Do not display an image. Does not keep selection focus After a user clicks on the entry, the entry will not remain selected. The previously selected entry will retain the focus. To hide an entry You may want certain entries to show up only under certain circumstances. For example, you can program an entry to be hidden when viewed with a Web browser. To hide outline entries: 1. In the Outline Entry Properties box, click the Entry Hide When tab 2. Select an option for hiding the entry or enter a formula in the formula box.
A Flat style outline displays one level of entries at a time. Initially, all top-level entries display. When you click an entry, if it is expandable, the sub-level entries associated with that entry will display. If it is not expandable, it will jump to whatever link or action is associated with it. If you want users to be able to navigate back up the outline, select Simple for the title style. The title will continue to display allowing users to click on it to get back to the previous level. If you choose Hide for the title style you must provide a button or action if you want users to be able to return to the top-level of the outline.
To change display attributes: 1. Open the form or page that the outline is embedded on. 2. Select the outline. 3. Choose Element - Outline Properties to display the Embedded Outline properties box. In the Embedded Outline properties box you can set the overall display of the embedded outline. On the Info tab you can set: Type style - Tree or Flat. This setting allows you to decide whether to show the hierarchy of the Outline or not. Tree style shows all of the outline entries in the hierarchy, while Flat shows only one level at a time. Use the Flat style selection in conjunction with the Title style setting. If you choose Flat style, you have the option of displaying the outline vertically or horizontally. Display horizontally displays entries to fit the window across instead of down.
Title style - Hide or Simple. These settings work in conjunction with the Type: Flat Style setting. In a Flat style outline, Simple style lets users navigate back up to prior levels by displaying the parent of the current level in a flat outline. Hide style does not display any hierarchy, so once users go down a level in the outline they cannot navigate back up. Root entry - Defining a root entry will show the children of the specified entry only. This can be used as a way to restrict users access to elements in your site or database. Specify a root by using the alias of the parent entry. For example, if a parent entry has an alias of Main, enter Main in the Root entry box and only that entrys children will display in the outline initially. If the specified entry does not have any children, then nothing will display in the outline. If you want to give users a way to navigate back up the hierarchy from the root entrys children, enable Simple as the Title style for either a Tree or Flat outline. If you want to limit users access to those children entries only, set the root, and dont enable a Title style. On the Font tab, select either Top-level font or Sub-level font to format the font of the outline entries. If Title style is set to Simple, select the Title Font. You can also select font colors for: Normal state of entries On Select (when the entry is selected) On Mouse (when the mouse passes over the entry) For each of the areas on the embedded outline, you can specify color or image backgrounds on the Background tab. You can set mouse-over and selection colors. Images can be tiled in various ways, such as top to bottom, or left to right, or positioned under the text, for button effects. Images must be shared image resources for the database. On the Layout tab you can set the positioning for the title-level (if Simple title is enabled), top-level, or the subsequent levels of: The entire outline entry Height - height of each entry. (This setting represents the width of each entry in a flat horizontal outline.) Vertical offset - aligns the outline entries relative to the top edge of the embedded outline. If you want to customize the spacing between outline entries, use this setting. Horizontal offset - aligns the outline entry relative to left edge of the embedded outline, for title or top-level entries. Sub-level offset is relative to parent entrys left edge.
The label text of the outline entry Alignment - within the outline entry. Vertical offset - relative to the embedded outline, depending on alignment; ignored for a middle vertical alignment. Horizontal offset - relative to the embedded outline, depending on alignment; ignored for a center horizontal alignment. The outline entry image Alignment - within the outline entry. Vertical offset - relative to the embedded outline, depending on alignment; ignored for a middle vertical alignment. Horizontal offset - relative to the embedded outline, depending on alignment; ignored for a center horizontal alignment.
Pages
A page is a database design element that displays information. Pages can be used anywhere in your application where you have text, graphics, or an embedded control, such as an outline, to present to the user. A page or form can contain the following: Text Use text anywhere on a page or form and apply text attributes, such as color, size, and font styles to the text. For complete information on creating and formatting text, see Notes 5 Client Help. Add horizontal rules to separate different parts of a page or form, or to make a page or form more interesting visually. Use tables to summarize information, align text and graphics in rows and columns, or position elements on a page or form. For information on creating programmable tables, see the topic Creating a programmable tables. For all other information on creating and formatting tables, see Notes 5 Client Help. A section is a collapsible and expandable area that can include objects, text, and graphics. An access-controlled section allows only certain users to read the section. Add links to take users to other pages, views, databases, or a URL when they click on text or a graphic. Place a graphic anywhere on a page or form. Use graphics to add color to a page or form or to create imagemaps.
continued
Sections
Links Graphics
53
Imagemaps
An imagemap is a graphic you enhance with programmable hotspots. Hotspots, in the form of pop-up text, actions, links, and formulas, perform an action when clicked by a user. Use Imagemaps as navigational structures in an application. Attach files to a page or form so users can detach or launch files locally. Actions automate tasks for the user. Add actions to the menu in a Notes client, or through buttons or hotspots on a page or form. For more information, see Automation in applications. Use Java applets to include small programs, such as an animated logo or a self-contained application, in a page or form. For more information about including Java applets on a page or form, see Including Java Applets in Applications. Embed the following elements in a page or form: a view, folder pane, navigator, outline, or date picker. Use these elements alone or combine them to control how users navigate through your application. If you have existing HTML or you prefer using HTML to using the formatting tools Designer offers, you can import, paste, or you can write your own HTML on a page or form. Designer supports object linking and embedding (OLE) as well as custom controls, sometimes called OCX controls. Including a linked or embedded object on a page or form lets you use a page or form as a gateway to another application. For example, an Employee Information page or form can include an OLE object that links to a Word Pro file where the employee annual performance reviews are stored. Notes/FX 2.0 fields create a two-way exchange between Notes and a supporting application by allowing field data to be shared and updated from either application. Lotus Components are examples of controls that let you include other Lotus products such as a spreadsheet or chart in a form. For information on including OLE objects and custom controls on a form, see Designing applications that share information.
Attachments Actions
Applets
Embedded elements
HTML
Creating a page
To create a page 1. Click Pages in the Design pane. 2. Click the New Page button. 3. Create the contents for the page, using elements such as text and graphics. 4. Choose Design - Page Properties to assign a name and set other page properties, such as the target frame in which the page should display. To delete a page 1. Click Pages in the Design pane. 2. Select the page you want to delete. 3. Press DEL or choose Edit - Clear. 4. Click Yes to confirm.
Displaying a page
Pages do not display in views. You can display pages to the user by: Designating the page to be part of a frameset. For more information on Framesets, see Designing Framesets. Creating a link to the page from another design element such as a form, an outline, or another page. For more information on creating links, see Adding links to a page. Creating an action that opens the page. For more information on creating actions, see Actions. Creating an outline entry that opens the page. For more information on creating outline entries, see Outlines. Setting the database launch property to launch the page when the database is opened. For more information on the database launch property, see Setting database launch properties.
Note that Domino does not map font sizes to HTML heading tags (H1, H2, and so on). Preserving spaces To align a column of numbers or preserve or insert spaces, use the default monospaced font. On a Windows system, the default monospaced font is Courier. Domino converts the default monospaced font to a monospaced font on the Web and preserves any spaces you enter. Text colors Web users see the same approximate text colors as Notes users, but the colors may not match exactly.
Chapter 4: Designing Pages 57
For the Computed text value (located on the Object tab of the Info List) enter the formula:
@Name([CN];@UserName)
If the users name is Sara Ryan/Acme, when she opens the page or form she will see: Welcome Sara Ryan. Note Domino publishes a <span> tag around the computed text for access via JavaScript.
Example: Creating Hotspots to control a programmable table 1. Create a two-row, two-column, programmable table on a page. Name the table CompanyInfo. Name the first row a and the second row b. 2. Enter text and graphics in each row and column of the table. 3. Enter a line of text on the page (below the table) that is related to what users will see when that row of the table is displayed. Enter a line for each row of the table. For example, if you have a two-row table one row has the company location and the other has the company history enter two lines of text: Our company locations Our company history 4. Select the text for the first line and choose Create - Hotspot Action Hotspot. 5. Click the Hotspot Click event in the Objects tab of the Info list in the Programmers pane. 6. Enter a formula in the Script area of the Programmers pane that sets the field $CompanyInfo to the name of the row of the table you want to display.
FIELD $CompanyInfo:= "a"; @Command([RefreshHideFormulas])
7. Select the second line of text and create a hotspot with the formula:
FIELD $CompanyInfo:= "b"; @Command([RefreshHideFormulas])
When users clicks on the first hotspot they will see the text and graphics in the first row of the table only. When they click on the second hotspot they will see the text and graphics in the second row of the table only. For more information about writing formulas, see the Programming Guide. For more information on creating basic, tabbed, or animated tables, see Notes 5 Client Help.
Creating sections
Use sections to group and organize elements on a page or form. Sections work well to present large amounts of information in an uncluttered way. For example, if you have two different procedures on a page, and users will only need to see one, you can put them into a collapsible section so that the users can expand only the section that they need.
To create a section
1. Open the page or form. 2. Highlight the text, graphics, and other elements to include in the section. 3. Choose Create - Section.
To format a section
1. Select the section and choose Section - Section Properties. 2. On the Section Title and Border tab you can: Enter a title for the section. Titles can be either text or a formula. Use text if the title should be the same all the time. Use a formula if you want the title to appear differently under different conditions. Select the border style. The border appears around the section. Select a border color. 3. On the Expand/Collapse tab: Select options for showing the section expanded or collapsed depending on whether a document is being previewed, opened for reading, opened for editing, or printed. Select Hide title when expanded if users dont need to see the section title when the fields are displayed.
To delete a section
Select the section and choose Section - Remove Section.
Creating links
You can create links that let users navigate to other parts of an application or to external sites on the Web. When users click on the text or graphic that is serving as a link, they jump to the element that you have linked to. You can set how the link displays to users in the properties box. You can use a different color text, or a hotspot around a graphic that shows up on mouse over. Domino converts these links to Hypertext links on the Web.
Framesets Views Folders Navigators When you link to a named element, the link references the elements name. Any change in the name of the element will break the link. Whenever possible, create aliases for design elements. If the design element has an alias, the link will be maintained as long as the alias does not change. There are two ways to link to a named element. You can copy and paste, or you can use the link properties box. To copy and paste a link 1. Select the design element you want to link to. 2. Choose Edit - Copy as Link - Named Element. 3. Select the text or graphic that will serve as the link and choose Create Hotspot - Link Hotspot. 4. Click the Paste icon on the Properties box. 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.) To create a link using the properties box 1. Select the text or graphic that you want to serve as the link. 2. Choose create Hotspot - Link Hotspot. 3. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select Named Element as the type of link. 4. Select the type of Named element you want to link to and do one of the following: Enter the name of the element Click the folder icon to browse Click the @ icon to enter a formula that resolves to a link 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.)
Linking to a URL
Use a URL link to create a link based on a URL name. Since this type of link is based on a hard-coded URL name, any changes to the URL break the link. To create a URL link 1. Select the text or graphic that you want to use as the URL link. 2. Choose create Hotspot - Link Hotspot. 3. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select URL as the type of link. 4. Enter a full URL (including protocol) for the value. 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.)
Adding graphics
A page or form that contains a graphic is visually appealing but takes more time to display and print. You can paste or import graphics into pages, as you can into documents, forms, views, and navigators. Designer stores graphics in Graphics Interchange Format (GIF) and Joint Photographic Experts Group (JPEG) in their native formats. Therefore, these are the best
choices for graphic fidelity. Designer stores other types of graphics in a platform-independent 256-color format that is similar to GIF89a format. (GIFs are 256-color images.) Graphics can be: Stand-alone graphics that add aesthetics or focus to a page or form Background graphics Imagemaps navigation structures composed of graphics that contain links.
Preparing graphics
Your goal, when preparing a graphic, is to have it look as much as possible like the graphic you created in your drawing program. How graphics look depends on the users viewer, operating system, and color mode. Viewer Notes client or a Web browser Depending on your audience, you should use either the Lotus color palette or the Web color palette. If your audience is only Notes users, use either the Lotus color palette or the Web color palette. If your audience is only Web users, use the Web color palette. If your audience is both Notes and Web users, use black and white or very simply colored graphics, or use the Web color palette. Operating system Macintosh, Windows NT, Windows 95/98, OS/2, or UNIX Always reduce graphics in formats other than gif or jpeg to 256 or fewer colors. Although doing this may reduce the quality of high-resolution graphics, it ensures a more reliable color display across platforms. Color mode 16-color mode, 256-color mode, or High/True/24-bit color mode. If all users have machines that display in true color mode, reducing the colors to 256 or fewer is all you need to do to prepare a graphic. If users have machines running in 256-color mode, use a color palette to map colors in the graphic to a table of predefined colors.
Changing the color palette If you are designing applications for users to access on the Web, you can change from the Lotus color palette to a Web color palette while designing to provide greater color fidelity. To change palettes: Choose File - Preferences - Notes Preferences. Check Use Web Palette on the Advanced options list of the Basics tab. If this option is unchecked, Designer uses the Lotus color palette. Note When Web users open a database, Domino converts non-gif and non-jpeg graphics to gif or jpeg formats. The system administrator specifies the format in the Image conversion format field, which is part of the HTTP Server section of the Server document. For more information, see Administering the Domino System.
To insert a shared image 1. Move the cursor to where you want to place the graphic. 2. Choose Create - Image Resource. 3. Choose the type of image gif, jpeg, or All Images from the Image Type list. 4. Select the name of the image file. 5. Click OK. Changing the display properties of the graphic Once you have added the graphic you can change the display properties using the properties box. Keep in mind that Domino passes the size and scaling information for graphics to the browser. If the browser supports scaling, the graphic has the same size and scale as it does in Notes; otherwise, the graphic appears in its original size, regardless of how you size it.
To resize a graphic
1. Select the graphic. 2. Choose Picture - Picture Properties. 3. Do one of the following: Drag the box in the graphics lower right corner In the Scaling field of the properties box, enter a value for the width and height To return a graphic to its original size 1. Select the graphic. 2. Choose Picture - Picture Properties. 3. On the Picture Info tab, click Reset. To set the text wrap properties for the graphic There are several alignment and text wrap properties you can set in the Picture Properties box. Alignment options indicate how the picture lines up with text on either side of it. By default, Designer aligns a picture with the bottom of the text around it. To wrap text around the picture, choose either Wrap, float image left or Wrap, float image right. 1. Select the graphic. 2. Choose Picture - Properties. 3. Choose an option for wrapping the text around the graphic.
To add alternate text for the Web You can make your application accessible to people with physical disabilities. Many of these users access applications with screen readers. Screen reader software, in conjunction with a digital speech synthesizer, provides an aural representation of what is on the screen or the cursor. In order to function, the screen reader software must have detailed information about graphics, so that it can translate the graphical display into speech. You can provide this information by making sure you include alternate text for all the graphics in your application. 1. Select the graphic. 2. Choose Picture - Picture Properties. 3. Click the Picture Info tab. 4. Enter text in the Alternate text box. 5. (Optional) Enter a caption and a caption display option.
To import a bitmap, jpeg, gif, pcx image, or tiff 5.0 bitmap as a background 1. Choose Design -<Design element> Properties and click the Background tab. 2. Click the Import Graphic button and select the file to import. 3. Click OK. To delete a page or form background 1. Choose Design - <Design element> Properties. 2. Click the Background tab then click Remove Graphic. For more information, see Adding a picture in Notes 5 Client Help.
Creating an imagemap
An imagemap is a graphic you enhance with programmable hotspots that perform some action when a user clicks on them. Imagemaps are often used as navigational structures in an application. For example, an imagemap of a plate of food might have hotspots users click to see recipes for the food pictured. Unlike a navigator, which is an independent design element, an imagemap resides on a page or form, so you can easily combine an imagemap with text and other page or form elements, and you can control the display of an imagemap using a hide-when or computed-for-display formula. If you plan to create a sitemap or navigator that combines several graphics with text and action buttons, create a navigator instead of an imagemap. An imagemap can be any graphic you can paste or import into a page or form, with the exception of graphics in the pic format. If you create an imagemap and then need to change the graphic, you can change the graphic while keeping the hotspots intact. To create an imagemap 1. Paste, create, or import a graphic or shared image on a page or form. 2. Select the graphic. 3. Choose Picture - Add Hotspot <hotspot shape>. 4. Click and drag to draw the hotspot on the graphic. Note To draw a polygon hotspot, click the points of the polygon, double-clicking to close the shape. To draw a hotspot around the entire graphic, choose Default Hotspot. 5. Choose Picture - Hotspot properties. 6. On the Hotspot Info tab of the Hotspot <shape> Properties box, specify a link. For information on linking, see Adding links.
7. (Optional) Specify a target frame where the linked document will display when a user clicks the hotspot. 8. On the Advanced tab add alternate text. 9. (Optional) On the Advanced tab, specify the Imagemap tab order for the hotspot. The tab order specifies the order in which hotspots are selected when a user presses the TAB key. 10. (Optional) In the Script area of the Programmers pane, specify a simple action, formula, or LotusScript or JavaScript routine to run when a user clicks the hotspot. To move a hotspot Once you create a hotspot you can move it as necessary. To move a hotspot do one of the following: Click and drag the hotspot that you want to move. Select the hotspot and use the arrow keys to move one pixel at a time. To delete a hotspot from an imagemap 1. Select the hotspot. 2. Choose Picture - Delete Hotspot. To copy an imagemap You can copy an imagemap from another page or form, form, or document, and Designer will maintain all of the hotspots from the original imagemap. 1. Select the imagemap you want and copy it to the clipboard. 2. Open the page or form where you want the imagemap and choose Edit - Paste. To change the graphic for imagemap 1. Select the current graphic. 2. Choose Picture - Replace picture.
Adding an applet
You can add a Java applet to provide visual interest or additional functionality for example, you might use animation to make your home page or form appealing. Applets can range from programs you build yourself to pre-built programs that you simply drop into a page or form. In Web applications, there may be times when you want to display an embedded object, for example, a view or outline, as an applet rather than as HTML to provide a richer user interface.
The Designer elements that you can display as applets are outlines, views, rich text fields, and action bars. For more information, see the documentation for creating an outline applet, view applet, editor applet, or action bar applet. In the case of custom or pre-built applets you want to include in a page or form, follow the steps for inserting, modifying, and running applets described in Including Java applets in an application.
Creating an attachment
Add a file attachment to make the file available for users to launch or detach. You can also create attachments to store files. For example, attach a file for use in a Web application, so that it can be accessed using a Domino URL. For more information about opening an attachment with a URL command, see the topic URL commands for opening attachments, image files, and OLE objects. To create an attachment 1. Open the page or form. 2. Move the cursor to the location where you want to create the attachment. 3. Choose File - Attach. 4. Select the file and click Create.
Embedding elements
Embedded elements are a group of objects and controls that can be embedded on a page or form, form, subform, or document. Elements that can be embedded include: Views Folders Outlines Navigators Date pickers One reason to embed an element on a page or form is to make the applications display consistent for both the Notes client and Web browser. Most design elements have different display properties depending on whether a user views them from a Web browser or from a Notes client. To better control the display and functionality of views, folders, navigators, and outlines, you can embed them on a page or form, form, subform, or document. Embedded elements provides functionality in Web applications that closely resembles functionality already available in Notes applications.
Chapter 4: Designing Pages 71
Embedding makes it easier to design a single application for use by Notes and Web clients. Additionally, embedding lets you combine elements on a page or form and use a full range of design features, including frames, tables, styled text, and graphics, to create a high-impact design.
Setting properties for the date picker Choose Element - Date Picker Properties to set: Horizontal and vertical size Font style and color Alignment and spacing Hide-when options
To enter HTML directly on a page or form 1. Open a page or form. 2. Enter the HTML directly on the page or form. 3. Choose Design - <Design element > Properties. 4. Click the HTML tab and check the Treat contents as HTML setting. When you select the Treat document contents as HTML property, Domino passes all data on the page or form directly to the browser. Domino ignores embedded navigators and folders and any embedded views that dont have the property Treat view contents as HTML selected. To include some HTML on a page or form You can include some HTML on a page or form and mark this text as HTML. Designer will serve it correctly to the browser. 1. Enter or paste HTML on the page or form. 2. Select the text and choose Text - Pass-thru HTML.
Example: Adding JavaScript header information This example uses JavaScript and cookies to load a page or form into the browser and save a cookie called Cookie_Man in the users cookie file. It also displays a message that shows the number of times a user has visited the site. It uses two functions, doCookie() and getTimes(), written in the JS Header. These functions are called from the onLoad event and the inline script on the page or form. Note The actual expiration date in the code has to be changed to a future date in order to make the cookies work properly. In the JS Header Event enter the following code:
cookieName = "Cookie_Man"; function doCookie() { if(document.cookie) { index = document.cookie.indexOf(cookieName); } else { index = -1; } if (index == -1) { document.cookie=cookieName+ "=1; expires=Saturday, 01-Apr-2000 08:00:00 GMT"; } else { countbegin = (document.cookie.indexOf("=", index) + 1); countend = document.cookie.indexOf(";", index); if (countend == -1) { countend = document.cookie.length } count = eval(document.cookie.substring(countbegin, countend)) + 1; document.cookie=cookieName+"="+count+"; expires=Saturday, 01-Apr-2000 08:00:00 GMT"; } } function getTimes() { if(document.cookie) { index = document.cookie.indexOf(cookieName); if (index != -1) { countbegin = 76 Application Development with Domino Designer
(document.cookie.indexOf("=", index) + 1); countend = document.cookie.indexOf(";", index); if (countend == -1) { countend = document.cookie.length; } count = document.cookie.substring(countbegin, countend); if (count == 1) { return ("<b>"+count+"</b> time before.</b>"); } else { return ("<b>"+count+"</b> times before.</b>"); } } } return ("<b>0</b> times before.</b></b>"); }
This HTML code is at the bottom of the form, formatted as Pass-Thru HTML text.
<script>document.write("You have visited this site "+getTimes());</script>
Forms
Forms, like pages, display information. Everything that can be done with a page can be done with a form. What sets forms apart from pages is that forms can be used to collect information. A form provides the structure for creating and displaying documents, and documents are the design element that store data in the database. When a user fills out the information in a form and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data. The following are the basic steps involved in designing a form: Decide on the purpose and type of form you need. To do so, consider: The kind of information you want to collect and what elements you will need. How and where the resulting documents, which contain and display the collected information, will appear. Create the form. Add elements to the form. Name the form. Assign its properties. Preview and test the form in the browsers users access it with.
79
Form Elements
Form elements are the components you use to create a forms aesthetics and function. Like pages, forms can contain:
Text Horizontal rules Tables Text is often used to label fields so users understand the purpose of each field. Add horizontal rules to separate different parts of a form, or to make a form more interesting visually. Use tables for summarizing information and aligning elements such as fields and graphics in rows and column. A table placed on a form appears in every document created with the form. A section is a collapsible and expandable area defined on a form. It can include fields, objects, layout regions, and text. An access-controlled section allows only certain users to edit the fields in the section. When you place a graphic anywhere on a form, it appears on every document created with the form. For example, on a form for correspondence, placing your company logo at the top of the form creates a letterhead. Imagemaps are graphics you enhance with programmable hotspots that perform some action when clicked by a user. Imagemaps are often used as navigational structures in an application. Within a form, you can add links to databases, views, specific documents, or URL links that open pages on the Internet. Form actions, buttons, or hotspots automate simple or complex tasks. For more information on creating these elements see Automation in applications. Use Java applets to include small programs, such as an animated logo or a self-contained application, in a form. You can attach files to a form so users can detach files locally or launch them from every document created with the form. Embed the following elements in a form: an outline, view, folder pane, import navigator, navigator, and date picker. Use these elements alone or combine them to control how users navigate through your application. If you have existing HTML or you prefer HTML, you can use it on forms. Use existing HTML by importing or pasting it into your form, or you can write your own.
Sections
Graphics
Imagemaps
Links Automation
HTML
For information on including any of these elements in a form, follow the steps given for adding them to a page in Designing Pages.
80 Application Development with Domino Designer
Subforms
Access-controlled You can restrict access to a section by creating an access control sections list. For information on creating an access-control list for a section, see Restricting who can access a section of a document. Layout regions A layout region on a form or subform is a fixed-length design area in which related elements can be dragged and moved easily and can be displayed in ways not possible on regular forms and subforms. A layout region can contain static text, graphics, buttons, and all fields except rich text fields. You can hide or collapse a layout region and all its components under certain conditions. Layout regions are not supported for Web applications. Embedded elements such as the file upload and the group scheduler that require programming support can be used on a form only. For more information, see Embedded elements.
Embedded elements
with each document created from it. Storing the form with each document does consume more memory. When a user opens a document, Domino uses these rules to determine which form to use to display it:
Condition If the form used to create the document is available and there is no form stored in the document and no form formula If a form is stored with the document If the view has a form formula If the form used to create the document is not available in the database Form used to display document The form that was used to create the document. The original form name is stored in a hidden field called Form in the document. To find the value of the field you can check the Document Properties box under the Fields tab. The form stored with the document. (When a form is stored in a document, the form name is stored in an internal field called $Title.) The form is determined by the views form formula. The default form for the database. Each database can have only one default form, which is marked with an arrow in the Forms list.
3. Click the Form Info tab. 4. Select Store form in document. 5. Switch to Database Properties in the drop-down list on the Properties box and select Allow use of stored forms in this database on the Database Basics tab. Overriding the stored form When a form is stored in a document, the form name is stored in a hidden field called $Title. Additional information is stored in the $Info, $WindowTitle, and $Body fields. To use a different form to display the document, create an agent that deletes this stored form information and designates another form to display the document. Shared fields and documents with stored forms If the form contains a shared field, that field is converted to a single-use field in the copy of the form that is actually stored in the document. This ensures that if a copy of the document is stored in a database that does not contain the shared field definition, the field can still be used. In the original form, the field is still defined as shared.
Form formulas
To override the default form selection, write a form formula for a particular view. For example, you can write a form formula that uses one form to display all fields when a user edits a document and a different form that resequences or omits fields when a user reads a document. Since form formulas apply only to a specific view, documents created in other views do not use the form formula. For more information on writing form formulas, see the Programming Guide.
Creating a form
To create a form, you must have at least Designer access in the access control list of the database. For information on database access, see Managing Domino Databases. If the form you need is similar to one that exists in the same database, another database, or a Designer template, copy and paste the form and then modify it. If no existing form suits your purpose, create a new form. To create a new form 1. In the open database, click Forms in the Design pane and click the New Form button. 2. Design the form. Create fields, text, and other elements on the form. 3. Choose Design - Form Properties to assign a name and other form properties. To copy an existing form 1. In the Design pane, click Forms. 2. From the list of forms in the Work pane, select the form you want to copy. 3. Choose Edit - Copy to copy the form to the clipboard. 4. Open the database you want to copy the form into and click Forms in the Design pane. 5. Choose Edit - Paste to paste the copy into the list of forms in the target database. If you are copying a form from a different database, resources such as shared field definitions and shared images are not sent with the copied form. You must copy resources separately to the new database to avoid an error message. Special types of forms There are several types of forms that you can create for specific purposes. See the following topics for information on creating any of these types of forms. Profile forms Forms that prompt users for input Forms for a Domino billing application To delete a form Remove a form when users no longer need it. After you delete the form, documents that were created with the deleted form are displayed with the default form instead. After you delete a form, to prevent users from seeing
84 Application Development with Domino Designer
a message that the form cant be found when they open existing documents, create an agent that reassigns the form name. For information on using agents to reassign documents to a new form, see Adding automation to your application. 1. Open the database. 2. In the Design pane, click Forms. 3. Select the form you want to delete. 4. Press DEL or choose Edit - Clear.
Naming forms
Each form in a database must have a unique name. If you make a copy of a form and paste it into the same database it came from, Designer will automatically prepend Copy of to the form name to keep the names unique. If you create multiple databases that contain the same information, use the same names for the forms. Standard names enable users to recognize commonly used forms; they also make it easier for users with similar databases to communicate. For example, suppose you have four customer-tracking databases, one in each regional sales office. If the Southern regional manager wants to discuss a shared account with the Western regional manager, both managers should know what a Company Profile document is. To name or rename a form, choose Design - Form Properties and enter a name for the form. Name requirements The name is case-sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation. The full form name, including all synonyms and the cascading name, cannot exceed 256 bytes. If youre using multibyte characters, 256 bytes is different from 256 characters. Only the first 64 characters of a form name appear in the Create menu.
Creating aliases
A form can have additional names (aliases). Using aliases lets you change the form name that appears on the Create menu without having to rewrite every formula that references a form name. It also lets you reassign existing documents to the new form, and rewrite formulas or reassign documents if the form name is translated. The the form name and its aliases are separated by a vertical bar |. If a form has only one name, it appears on the Create menu and in the documents FORM field. If there are two or more names, the forms first (leftmost) name always appears on the Create menu, while the forms last (rightmost) name, which is typically the alias, appears in the FORM field. Sometimes a form can have multiple names usually due to translation. In those cases the middle names are ignored. As long as the alias does not change, documents will display using the original form and all formulas referencing the form will continue to work.
To add an alias 1. Choose Design - Form Properties. 2. In the name field on the properties box, add a | (vertical bar) to the right of any other names. In the following example, Interview is the alias and Main Topic is the original name:
Main Topic | Interview
To move a form to the Create - Other menu in Notes client If you dont expect a form to be used frequently, move it to the Create Other dialog box to shorten the list of forms in the main Create menu. 1. Open the form. 2. Choose Design - Form Properties. 3. On the Form Info tab, select Include in Menu and select Create Other dialog. To remove a form from the Create menu in Notes client Removing a form from the Create menu hides the form from all users. For example, the Mail template hides the NonDelivery Report and Return Receipt forms because only the Notes Mail Router uses them. For compatibility with earlier releases of Notes, putting parentheses around the form names when you name a form will also remove forms from the Create menu. 1. In the Form Properties box deselect Include in Menu. 2. Save the form. To hide a form from only some users, use a create access list. For more information about create access lists, see Managing Domino Databases. To hide a form Another way to remove a form from the Create menu is to hide it. Hiding allows you to specify conditions under which the form is hidden or displayed. For example, you can hide a form from Notes clients, but display it for Web clients. 1. Close the form you want to hide. 2. In the Design pane, click Forms in the Design pane. 3. From the forms list, select the form you want to hide. 4. Choose Design - Design Properties. 5. Click the Design tab. 6. Select a hide option.
The following screens compare how a new document appears to Netscape Navigator users and Notes client users.
To make a form available to Web users You must use this technique to allow Web users to create a document from a form, but it also works in Notes applications. 1. Add a button, action, or hotspot to a form. 2. In the Programmers pane, choose the Click event and program the event with a formula or script that creates a document from the form. For example, this formula opens a new Main Topic document in the current database:
@Command([Compose];"Main Topic")
calculation. The HTML generated for the hidden fields is also accessible through JavaScript, so you can change the value or find out the state of a hidden field with a script. Checking this option creates larger files on the Web and may decrease application performance. Consider security, since information in hidden fields, though not visible in the browser, is visible through the View Source menu item on the browser. To generate HTML for hidden fields On the Defaults tab, in the For Web Access section, check the option Generate HTML for all fields and deselect the option Treat document contents as HTML. Defining a header on a form If you are designing a form for use in a Notes application, you can define a header that does not scroll off screen when the user scrolls down the form or document created with that form. For example, in the Notes mail template, a header displays all of the information contained in the mail sender and recipient fields. This section remains static while you scroll through a mail message. Headers can contain any element that a form can contain. The only caveat is that a table cannot be the first element in a header; it must be preceded by a text object, even if the text object is blank. 1. Enter the text, graphics, tables, or other elements you want in the header region of the form. 2. Move the cursor to the line below where you want the header to start. 3. Choose Design - Form Properties. 4. On the Header tab, select "Add header for form," to mark off the header area. 5. Set the display properties for the header. Height can be set in pixels as a percentage of the form height, or to fit contents. Select a scrolling option. Auto automatically turns scrolling on when the content of the header exceeds the space allotted. Allow resizing lets users resize the header area. Border controls the display of the dividing line between the header and the body of the form. You can turn the border off or change the thickness and color. Displaying a graphic in a header To display a graphic in a header, add a background graphic to the form. This becomes the background for the header only. Note that if you do this, the remainder of the form is blank and cannot display another background graphic.
Chapter 5: Designing Forms 91
Creating a print header and footer You can define a header and footer that will print on all documents created with that form. Headers and footers are not supported for Web applications. 1. On the Printing tab, click Header and type the header and/or click Footer and type the footer. 2. Click the icons to add the page number, date, time, and so on. 3. (Optional) Assign a font, size, and style for header or footer text. Header and footer alignment Headers and footers have three preset, permanent tab stops: left, center, and right. When you insert one tab, text to the left of the tab is left justified, and text to its right is right justified. With two tabs, text to the left of the first tab is left justified; text between the two tabs is centered; and text to the right of the second tab is right justified. For example: &D|&T|&P Left justifies the date, centers the time, and right justifies the page number. |URGENT| Centers the text URGENT. ||URGENT Right justifies the text URGENT.
Version tracking
Version tracking allows you to maintain a history of changes to a document. In order to activate version tracking, you must designate the form used to create documents as a version-tracking form.
Make sure users understand that version tracking is active, so that they understand the impact of editing documents. Explain version tracking in the Using Database document. If there is a response hierarchy set up in the database, responses to version-controlled documents display as responses to the original document only.
To customize a forms window title 1. Open the form. 2. On the Object tab of the Info List in the Programmers pane, select the Window Title - attribute. 3. In the Script area of the Programmer's pane, enter text enclosed in quotation marks or a formula that evaluates to text.
Chapter 5: Designing Forms 95
4. Click the check mark to save the formula. 5. To test the window title, create, save, and read a new document. Make sure the title is appropriate for all three situations. For more information on creating window title formulas, see the Programming Guide. Examples: Customizing window titles Title includes creation date and company name This formula displays the date the document was created, form name, and company that was billed. @Text converts the date to a text string, and the extra spaces within the quotation marks force the words in the title to be properly spaced.
@Text(@created) + " Inventory Invoice for " + CompanyName
This formula uses the field form to refer to the form name instead of hard coding it into the formula.
@Text(@created) + " " + form + " for " + Company Name
Title includes number of responses This formula is useful for a main document form in a discussion database.
@If(@IsNewDoc;"New Topic";Subject + @DocDescendants(" (No Responses)";" (1 Response)";" (% Responses)));
If the document has never been saved, New Topic shows in the title bar while the user composes the document. After the document is saved, the title is the subject combined with the number of responses. If the subject is Icebox 2000 and there are no responses, the title of the document is Icebox 2000 (No Responses). With one response, the title becomes Icebox 2000 (1 Response). With two responses, the title becomes Icebox 2000 (2 Responses). Response includes the subject When the response or response-to-response is first composed, this formula displays New Response To and the subject of the main document.
@If(@IsNewDoc;"New Response to " + Subject; "Response " + @DocNumber("") + " of " + @DocSiblings + " to " + Subject);
When a user reads the response, the window title displays the total number of responses to the main document, the response being displayed, and the subject of the main document. For example, if the response document is the second of four responses to Icebox 2000, the title displays as Response 2 of 4 to Icebox 2000.
Subforms
A subform is a collection of form elements that are stored as a single object. Subforms can contain the same elements as regular forms. Subforms save redesign time. When you change a field on a subform, every form that uses the subform updates. Common uses of subforms include adding a company logo to business documents or adding mailing label information to mail and memo forms. A subform can be a permanent part of a form or can appear conditionally, depending on the result of a formula. For example, you might offer users a choice of custom mail forms with different graphics and styles for various types of mail messages, such as memos, alerts, or letters. Field names used in the subform cant be used elsewhere on the form. Changes you make to a subform affect all forms and documents that use the subform.
Creating a subform
You can copy and modify a subform that is similar to the one you need or create a new subform and design it yourself. 1. Select the database that will have the new subform and click Resources - Subforms. 2. Click the New Subform button. 3. Create the subform using the same elements you use to create a form. 4. Choose Design - Subform Properties. 5. Enter a name for the new subform. 6. Choose display options for including the subform in the Insert Subform or the New Form dialog box. 7. Close and save the subform. Display options for subforms The following options do not apply to computed subforms. Select Include in Insert Subform dialog so designers see it when inserting a subform. Excluding a subform from the Insert Subform dialog box is not a security measure. Users with Designer access or higher can open any subform in Designer and copy individual components. Select Include in New Form dialog if you want the subform to appear immediately when designers choose Create - Design - Form.
Deleting subforms
When a user opens a document that references a deleted subform, the message Subform: <subform name> not loaded appears on the status bar. The document opens without any representation of the deleted subform. When a designer opens a form that references a deleted subform, the message Subform: <subform name> not loaded appears on the status bar. When a designer clicks the deleted subform area on the form, the message Invalid or nonexistent document appears and the designer cant open the subform. To avoid these messages, add another subform to the database and give it the same name as the deleted one.
To delete a subform from a form You can remove a subform from an individual form, without disturbing other forms that use it. 1. Click the subform area on a form. 2. Choose Edit - Clear. 3. Adjust the formatting if necessary. To delete a subform from a database You can remove all instances of a subform from a database. Be aware that this will cause errors in any form that refers to the subform. 1. Click Subforms in the design list for the database. 2. Choose Edit - Clear.
Layout regions
A layout region is a design area on a form that affords flexibility for combining and arranging text and graphics. Layout regions are not supported in Web applications. A layout region can contain: Text Graphics (either in the background or as graphic buttons) Fields (except rich text fields and dialog list fields) Buttons You cannot add the following elements to a layout region: Attachments Horizontal Rules Hotspots Java Applets Links OLE Objects Page Breaks Pop-ups Sections Shared Actions Shared Fields Subforms Tables
Chapter 5: Designing Forms 99
You can hide or collapse a layout region and all its components under certain conditions. For example, you can hide a layout region when Web users view the application, or when users edit the form.
5. (Optional) Deselect Show border to make the layout region borders invisible. 6. (Optional) Select 3D style to show the layout region in gray and to show fields and buttons as they look in dialog boxes.
Embedded Controls
There are two types of embedded controls that can only be used on a form: The file upload control - allows you to create a form so that Web users can attach files to documents The group scheduler - allows you to create a form that displays the schedules of specified users
Creating a group scheduler on a form Only one group scheduler can be embedded per form. 1. Open or create a form for the group scheduler. 2. Move the cursor where you want the group scheduler to appear on the form. 3. Choose Create - Embedded element - Group Scheduler. Note The group scheduler does not display scheduling information while you are designing the form. Creating fields for the group scheduler The group scheduler needs three pieces of information before it can display anyones schedule. Whose schedule to display (individuals or group). What week to start the schedule information from. How many hours per day of schedule information to display. One way to collect this data is to create editable fields on the form and have users enter in those fields the information they want displayed. You can also use LotusScript or the Formula language to create the field items. For an example of collecting the data using an action button and Formula language, look at the GroupScheduler form in the Mail5.0 Template. Once you have created the fields or other method for collecting the data, associate those fields with the Group Scheduler attributes. Programming the group scheduler Once you have created the fields for collecting the data, you must program the group scheduler so that it can retrieve the data from the fields. The group scheduler has three attributes that must be programmed: Group member items Points the group scheduler to where the data is for whose schedules are displayed Start time item Points the group scheduler to where the data is for the week the scheduler should start the display from The group scheduler displays one week of scheduling information at a time. The Notes Preference settings for the user accessing the form determines the day of the week that the display starts on. Duration item Points the group scheduler to the data that determines how many hours to display for each day
To associate the fields with the attributes, select the attribute from Objects tab of the Info List and enter a field name in quotation marks in the Script area of the Programmers Pane.
Group Member items When a user creates a form containing the group scheduler, the group scheduler evaluates the contents of this attribute to determine the location of the data that indicates whose schedules to display. When the group scheduler finds the field, it returns scheduling information for those people whose names or group name is specified in the field. If the contents of the field contains a group name, the group is expanded into its individual members, each of whose scheduling information is displayed. If you are writing a LotusScript formula to obtain the data for this attribute, the formula must evaluate to a text list of one or more field names. Start Time item When a user creates a form containing the group scheduler, group scheduler examines the contents of this attribute to determine where to find the data for the date and time on which to begin the display. The value of this field should be a date and time. If the value is not a date and time, the current date and time of the users system is the default. If the value is a date only, that date and the current time on the users system are the default. If the value is only a time, that time and the current date on the users system are the default. When a user accesses the form, the scheduling information starts from the specified date. The user can change which week is displayed by clicking on the left and right arrow keys. Each day will begin at the specified time. The time is rounded down to the nearest hour. Note The schedules are displayed in terms of the users local time zone for example, a Pacific time zone user free between 9 and 5 PST will appear free between 12 and 8 to an EST user.
Duration item This attribute is examined to determine where to find the data for how many hours of each persons schedule to display. The value of this field should be an integer between 1 and 24, inclusive. A value less than 1 will be defaulted to 1 and a value greater than 24 will be defaulted to 12. Setting a refresh mode When a user creates a document that contains a group scheduler, the group scheduler retrieves the scheduling information from the mail servers of the group members. The user can change any of the scheduling information displayed by changing the values in the fields. When any of the information in the fields used by the group scheduler changes, the user must refresh the document to see the changes reflected in the scheduler display. The default refresh mode is a full refresh. That is, whenever a user refreshes, all three pieces of scheduling information are updated regardless of which fields have been changed. This includes retrieving the scheduling data for all group members. Therefore, it could unnecessarily affect performance if all a user did was change the value in the duration field. To limit the refresh, add an optional, reserved field on the form named $GroupScheduleRefreshMode. This field controls how the group scheduler refreshes the scheduling information. The value of $GroupScheduleRefreshMode can be 0 or 1. If the value of $GroupScheduleRefreshMode is 0, the group scheduler performs a partial refresh which refreshes only data in the field that has changed. This is useful when the users have added or deleted a group member or changed the duration item or start time item. If the value of the $GroupScheduleRefreshMode field is 1, group scheduler will update all data for all members on refresh. Displaying the legend You can create a reserved field on the form that contains the group scheduler to allow users to turn the legend off or on. The reserved field name is $GroupScheduleShowLegend. Valid values are 0 (to turn the legend off), and 1 (to display the legend). Setting properties for the group scheduler Use the Group Scheduler Properties box to set the following properties for the group scheduler: Target frame - Clicking on a group members name in the group scheduler opens that members calendar in its own window. You can specify a target frame to display group members calendar views and appointment documents.
Size - Set the horizontal size as either a percentage of the window width or a fixed width. Set the vertical size to fit to contents (number of group members) or a fixed height. If you select fixed height, the scheduler displays a scroll bar if all of the members do not fit on the screen. Color - The group scheduler uses a number of colors to display calendar information. All of the colors can be customized on the Background tab of the properties box. For an example of a group scheduler form, see the Group Calendar form in the Mail (R5.0) template.
Profile forms
Profile forms are forms that collect user-specific or database-specific values. These values are stored and retrieved in Profile documents. What sets these documents apart as profile documents is not the form they are created with, but rather the way the documents are displayed and values in the fields passed back. Only one profile document per form can exist for each user of a database. Or, only one profile document can exist for a database if that form is available to all users. Profile documents allow for quick data retrieval, because they are cached while the database that stores them is open. Profile documents are like other database documents except they are somewhat invisible they do not display in views and are not included in a document count for the database. Users create profile documents through an action button or agent you design that uses LotusScript or the formula language. A database can have a single profile document or multiple profile documents that match a key you specify for example, an @username key that creates one profile document for each user of a database, or a key that specifies a different profile document for each day of the week. Whether you use one profile document for a database or use multiple profile documents depends on your design needs. Use a single profile document to contain settings that all documents in the database need, such as environment variables. Use multiple profile documents for more customizable settings, such as user preferences. A user must have at least Author access in the access control list (ACL) of a database to create a profile document that is available to all users. You can use any form to create a profile document. After creating the form, you create a button, action, or agent for the application that uses either @CommandEditProfile in a formula or UIWorkspace.EditProfile or NotesDatabase GetProfileDocument in a LotusScript program to create or retrieve a document. In each case, Notes looks for a profile document with the form name you specify, and creates a profile document if one does
106 Application Development with Domino Designer
not already exist. For an example of a profile document, see the Interest Profile form in the Discussion - Notes & Web (R5.0) template. For more information about accessing or editing a profile document using Formula language or LotusScript, see the Programming Guide.
10. On the Display tab, add a label and width for the button. 11. In the Programmers pane, click Formula, and write a formula using @DialogBox Include the name of the dialog form. For information on using @Dialogbox, see the Programming Guide. Guidelines for designing a form that presents a dialog box To match the Notes user interface as closely as possible, follow these guidelines: For the dialog form, use a layout region with the 3D property selected. Although you can design the dialog form in any way, a 3D layout region most closely resembles a dialog box. A layout region that is 3 inches square is big enough to display a few fields and two or three buttons. In the @DialogBox formula, include the [AutoVertFit] and [AutoHorzFit] options to size the dialog box to fit the layout region. Use 9 point Helvetica for static text, fields, and buttons. Place static text labels above or to the left of fields and end them with a colon (for example, Name:). Place buttons at the bottom of forms. OK and Cancel buttons appear automatically to the right of the layout region. If you do not want the cancel button to appear, use the @DialogBox keyword [NoCancel]. If you do not want the OK or the Cancel button to appear use [NoOkCancel]. To arrange choices horizontally, use the multi-column display option with radio button and check box field; use None for the frame option so choices blend with the dialog box background. For button text with multiple words, use initial capital letters. Use ellipses for buttons that lead to another dialog box or task for example, Show Details...
4. Enter a formula in the Script area using @Prompt. 5. Close and save the form. For more information on the @Prompt command, see the Programming Guide. Examples: Using @Prompt [YesNoCancel] This formula displays a warning before sending the memo and gives the user a chance to select Yes, No, or Cancel.
Result := @Prompt([YesNoCancel]; "Send memo?"; "This memo will be sent to everyone listed in the To, CC, and BCC fields." );
[OkCancelEdit] This formula fills the Name field with the users response to the prompt. The default value is the users Notes name. If the user selects Cancel, Notes cancels the formula evaluation.
FIELD Name := @Prompt([OkCancelEdit]; "Enter Your Name"; "Type your name in the box below."; @UserName);
[OkCancelList] This formula captures the users response in a temporary variable called ComposeType and uses it to create a new report using the appropriate form.
ComposeType := @Prompt([OKCancelList]; "Report Type"; "Choose a report type."; "Adjustment Report";"Adjustment Report":"Infant Progress Report":"Toddler Progress Report":"Preschool Progress Report":"Transition to Kindergarten Report"); @Do(@Command([Compose]; ""; ComposeType));
Using @PickList The @PickList function looks up the values in a view as @DbColumn does, but lets the user pick a value from one document. This is similar to using @Prompt in a form, but is specifically for use with views. @Picklist offers the following advantages over formulas that use @DbColumn or @DbLookup. It is not limited to 64K of data. It is faster than @DbColumn or @DbLookup. It allows users to type the first few characters of an entry to find it quickly in the view. For more information on the @Picklist function, see the Programming Guide. Example This formula displays the Products view of PROD.NSF in a dialog box:
choice:=@PickList([Custom] ; "":"prod.nsf" ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 1 );
To specify which documents to charge for 1. On the form that you want to track, create a field named $ChargeRead or $ChargeWrite. 2. 3. 4. 5. Set the field type to Number. Select Currency. On the Hide tab, hide the field for all options. Assign a cost value to the field. When users read from or write to documents that contains one of these fields, the billing task retrieves the cost value in this field and places it in a document billing record. 6. Save the form.
Chapter 5: Designing Forms 111
Note If there are many documents for which you want to charge, you can create a shared field and add it to multiple forms. If a database is updated by a template, you can modify the template to include the hidden fields. For more information on setting up billing, see Setting up billing in Administering the Domino System.
SearchThesaurus Use thesaurus synonyms: TRUE or 1 or FALSE or FALSE 0 (This option is ignored by the R5 search engine) SearchFuzzy SearchEntry Start Count Scope Use fuzzy search: TRUE or 1 or FALSE or 0 Name of form to use for each result entry Start document for paged results; 0 = unpaged FALSE ResultEntry 0
Number to return for paged results; 0 = unpaged 0 Scope of search: 1 = notes databases only 2 = filesystem only 0 = both 0
If you are customizing a search form for use on in a Notes client, you will need to use the FTDomainSearch method. For more information about using the FTDomainSearch method, see the Programming Guide.
Chapter 5: Designing Forms 113
Customizing search results forms Search results are displayed using the SearchResults form, the ResultEntry, and the DetailedResultEntry form. The SearchResults form defines the layout of each page of results. The ResultEntry and DetailedResultEntry forms defines the format of a single result within that page, and is repeated for each result returned. On the Web you specify the name of this form through the SearchEntry field/argument. The fields below are for the ResultEntry and DetailedResultEntry forms.
Field Name DSCreationTime DSModifiedTime DSURL DSDBTitle DSDocSummary DSDocTitle DSDocAuthor DSScore DSSServer DSType Description Creation time of a document Modification time of a document URL to document Database title Document summary Document title Document author Relevance score Name of the server that the document was indexed on 0 indicates a Notes document, 1 indicates an external or file system document
You can name your results form whatever you want and then specify your chosen name in the SearchDomain URL or to the FTDomainSearch LotusScript call. The Web will look for a form named $$SearchDomainTemplate if you dont name one in the URL. How the SearchResults and ResultEntry/DetailedResultEntry forms are used. The LotusScript below is attached to the click event of the Search action hotspot used by the Notes client on the search form. The lines that call the name of the results form and the result entry form are underscored.
Sub Click(Source As Button) Dim s As New NotesSession Dim db As NotesDatabase Dim w As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim q As String Dim l As Integer Dim d As Integer Dim sort As String Dim stype As Integer 114 Application Development with Domino Designer
Dim useint As Integer Dim rtype As String Dim rformname As String Set db=s.CurrentDatabase Set uidoc = w.currentdocument uidoc.refresh Set doc=uidoc.Document q=doc.query(0) l=doc.resultlimit(0) d=doc.MaxDisplay(0) sort = doc.sort(0) usestr = doc.use sscope=doc.searchscope rtype=doc.GetItemValue("SearchType")(0) If rtype = "1" Then rformname="DetailedResultEntry" Else rformname="ResultEntry" End If Select Case sort Case "R" stype = FT_SCORES Case "O" stype = FT_DATE_ASC Case "N" stype = FT_DATE_DES End Select Forall values In usestr If values = "2" Then useint = useint + FT_STEMS If values = "3" Then useint = useint + FT_FUZZY End Forall Forall values In sscope If values = "1" Then useint = useint + FT_DATABASE If values = "2" Then useint = useint + FT_FILESYSTEM End Forall Chapter 5: Designing Forms 115
On Error Resume Next If db.isopen Then If Err <> 0 Then Messagebox STR_DBOPEN_ERROR Err = 0 Exit Sub End If Set srdoc = db.ftdomainsearch(q, l, stype,useint, 0,d,rformname) If Err <> 0 Then Messagebox STR_FTERROR_PREFIX & Error$, 0 , STR_ERROR Err=0 Exit Sub End If srdoc.Form="SearchResults" Call w.EditDocument(False, srdoc, True) End If End Sub
Tip You must select the Generate HTML for all fields option in the Form properties box to preserve field values when data is passed between a Web browser and the server. Using navigational buttons for paged results To make it possible to navigate forward and backward between pages of results, add buttons or hotspots to the SearchResults form. The fields available for use with next and previous buttons are listed in the table below. In the Notes client, the buttons should reinvoke the LotusScript FTDomainSearch function with revised arguments. On the Web they should be used to construct a new SearchDomain URL to fetch a new set of results.
Note If you use editable fields on a search result form, select the option Web Access: Use JavaScript when generating pages, in the Database properties. If selected, a URL attached to a hotspot or button will be computed on the click event. If it is not selected, the URL will be computed when the page is loaded.
Query Start Count Hits TotalHits SearchMax SearchWv (only for URL command) SearchOrder (only for URL command) SearchThesaurus (only for URL command) SearchFuzzy (only for URL command) SortOptions (only for Notes client) OtherOptions (only for Notes client) Search string used Starting document number Number of results requested for this page Actual number of results returned this page, may be less than Count Total number of hits found by the search Maximum number of entries to return in total; 0 = no limit Include word variants: 1 or 0 1 = by relevance 2 = by date ascending 3 = by date descending Use thesaurus synonyms: 1 or 0 Use fuzzy search: 1 or 0 FT_SCORES = by relevance FT_DATE_ASC = by date ascending FT_DATE_DES = by date descending FT_STEMS = Include word variants FT_FUZZY = Use fuzzy search FT_DATABASE = search databases FT_FILESYSTEM = search filesystems Name of the Result Entry form used Scope of search: 1 = notes databases only 2 = filesystem only 0 = both
The fields in the table below are available for use with the Start and Count parameters and should be added to the results form as needed.
Field Hits TotalHits Description The actual number of hits returned. This field is useful in determining the Start parameter of Next. The total number of hits returned without regard to paging.
Designing forms
Avoid large bitmaps or graphics. Avoid the form property Automatically refresh fields. Instead, use the Refresh fields on keyword change for a choice field, or write a LotusScript field event to recalculate the document or update other fields when users move from a specific field. Avoid long tables with many computed fields.
Designing fields
Use @DbColumn or @DbLookup formulas sparingly, or replace them with LotusScript programs, which are generally faster and support error checking. Use simple formulas for hide when conditions. Avoid recalculating fields, if possible. Otherwise, change such fields to computed-when-composed fields, which calculate only when the document is composed but can be updated later if needed through buttons, actions, or agents. Use LotusScript form events rather than conditional formulas in the field itself to set field values. For example, to reset the status field if the document is being saved, create a script for a QuerySave event, rather than write a formula that uses @If(@IsDocBeingSaved;x;y). Minimize the number of fields, especially hidden fields, and use form events rather than field formulas to execute processing logic and avoid unnecessary recalculations. For example, suppose a form contains a hidden computed field called State, which determines where documents are in the workflow and
118 Application Development with Domino Designer
where they need to be sent. By replacing the field with a LotusScript program that sets a field value during the QuerySave form event, you can set the field value in the document only when it is saved, not when it is opened or refreshed. For more information on writing lookup formulas, or hide-when formulas, see the Programming Guide.
Fields
A field is the part of an application that collects data. You create fields on forms, subforms, or in layout regions. Each field stores a single type of information. A fields field type defines the kind of information a field accepts, such as text, numbers, dates, or names. When a user, either in a Notes client or a Web browser, creates a form, fills out the information in the fields, and saves the form, the data in the fields is stored in an individual document. The contents of the fields can then be displayed in documents and views or can be retrieved for use in formulas. A field can be used on a single form, or you can create shared fields for use in multiple forms in a database. When you create a field on a form, you define the following: Field name Field type Display options and field properties Computed or editable attribute Formulas or scripts associated with the field To create a field When you create a field on a form, the field displays with its name surrounded by a rectangle and a letter or symbol that lets you know what type of field it is. You can use tabs, returns, and other formatting tools to refine the fields position on the form. 1. Open the form. 2. Move the cursor where you want the field to appear. 3. Choose Create - Field.
121
4. On the Field Info tab of the Field Properties box: Assign a name to the field. Assign a field type. Select the display style. Select Editable or one of the computed options. 5. On the Control tab, select a display option for the field. 6. On the Fonts tab, format the font style for the field. Copying fields If you copy a field from one place on form to another, each copy of the field has a sequential number appended to its name to preserve name uniqueness. You can rename the field after copying it. If you copy a shared field, the new field changes to a single-use field. Deleting fields To delete a field, you select the field on the form and press the Delete key or choose Edit - Clear. Deleting a field from a form means that data for that field is no longer displayed in documents. The data still exists, however, and you can display it by adding a field with the same name to the form. To delete the field data, use the @DeleteField function to remove the field and its data from all documents containing the field. For example, to purge the AssignedTo field and its data from all Schedule documents, create an agent or action that uses the form name and @DeleteField: SELECT Form=Schedule; Field AssignedTo:=@DeleteField;
To create a shared field 1. Expand Resources in the Design pane and click on Shared fields. 2. Click the button New Shared Field. 3. Enter a name for the shared field. 4. Assign a field type and choose Editable or a computed option. 5. Close the properties box. To insert a shared field 1. Move the cursor where you want the field to appear on the form. 2. Choose Create - Insert Shared Field. 3. Select the shared field you want to use and click OK. 4. (Optional) Type a text label next to or above the field. 5. (Optional) Highlight the label and choose Text - Text Properties to change the text style.
definition, its definition remains in the database. Unless you delete the field data with the @DeleteField function, the data from deleted shared fields can be displayed again by adding a field of the same name or re-inserting the shared field. When users open a document that refers to a deleted shared field, they see this message:
Cannot locate field definition for Field: <field name>.
When users click OK, they see the contents of the shared field as non-editable text. To prevent this message, modify each form to convert the old shared field to a single-use field (by cutting it and pasting it back on the form). The field definition is stored within each form, rather than in a central location, and documents can be displayed as they were when they referred to a shared field definition.
Naming a field
A field name must begin with a letter and can include letters, numbers, and the symbols _ and $. The name can contain up to 32 bytes. (If youre using multibyte characters, remember that 32 bytes is different than 32 characters). Use short, descriptive field names that you will remember when you write formulas that refer to the fields.
Field names cannot contain spaces. Run multiple words together, for example, ModifiedDate, or separate them with an underscore: Modified_Date. The Designer templates use the naming convention of an initial capital letter followed by lowercase letters, for example, SendCopyTo. If several fields on forms in a database contain similar information, for example, the date of creation and the authors name, use the same field name for all of them. This makes sharing information between forms easier as you continue to develop the application. Establishing and maintaining naming standards simplifies application design throughout your organization. Renaming a field Unlike forms and views that can have aliases, a field can have only one name. Renaming a field has the same effect as deleting a field from a form. For example, if you have a field called Comments, and users enter text into many instances of this field in documents, and you then rename the field to Observations, all of the data in Comments will no longer appear when you display the document. If you must rename a field and need to transfer data, create a new field, create and run an agent to reassign data to the new field, then delete the old field. Remember to update all formulas to refer to the new field name.
Align paragraphs (left, center, right) Indent paragraphs Use bulleted and numbered lists Create links Cut, copy, and paste text within the rich text field Note Web users cannot paste text from outside the editor because of the limitations of the JDK, Release 1.0.2. Enter international characters Note Not all international characters can be displayed in the editor applet. The ability to display international characters depends on the fonts installed on the users workstation and the version of the browser the user is working with. Most characters entered in the editor will be correctly transferred to Domino (depending on the browser).
If the same document is edited by both a Web browser and a Notes client, there are some additional caveats. For example, it is possible to format a document in the Notes client using a formatting feature that is not supported in the editor applet. Also, there are features that, once opened and edited in the editor applet, will subsequently not format properly if opened for editing in the Notes client. These are the formatting features to avoid if editing a document with both the Notes client and a Web browser: First line indent or outdent Full justification paragraph alignment
Chapter 6: Designing Fields 127
Tabs Images Ordered lists Tables In addition, any features that the editor applet cannot interpret are displayed as HTML in green on the document.
Number fields
Use Number fields for numeric and currency data. The Number field type lets you limit a field to numerical values and define how the numbers display in a form. For example, a Monthly Total field in a Budget form adds together all of the numeric values from the fields listed in the following formula to arrive at a total budget figure:
Advertising + Entertainment + Miscellaneous + Overhead + Salaries + Travel
If you dont want users to change the value of a numeric field, select a Computed option in the Field Properties box. In the example above, the Monthly Total field is computed so users cannot edit the value. Fields used in calculations must have default values. Otherwise, the message Incorrect data type for operator or @Function: Text expected appears. On the Control tab of the Field Properties box, you can specify whether the field should display formats according to the custom settings you specify, or whether it should use the default settings of the users workstation. In the case of currency, where you might want different fields to display different currency formats, you can apply settings on a field level. When you are defining a currency field, you can choose a currency symbol from an extensive list. If the symbol you need is not included in the list, you can create a custom currency symbol by pasting in the ASCII character for the currency symbol and entering the corresponding country code. Caution Applying different currency formats, such as displaying British pounds in one field and American dollars in another, might result in unexpected results if you combine values using the formula language or a scripting language.
Choose any of these number formats on the Control tab of the Field Properties box: Decimal displays numbers either as they are entered (zeroes to the right of the decimal point are suppressed), or with a fixed number of decimal places, depending on what you specify. To base the decimal symbol and thousands separator display on the type of measurement (Imperial or Metric) users set in the operating systems International User Preferences, choose Client. To set the decimal symbol and thousands separator yourself, choose Custom. Note A number field can store up to 8 non-zero decimal digits without loss of precision. Notes implements floating point arithmetic using the IEEE64 industry standard. In cases where a user enters more than 8 non-zero decimal digits, rounding may occur and the number may display and be stored differently from the number the user entered. Percent displays a number as a percentage. For example, 12 displays as 1200%, while .12 displays as 12%. Scientific displays numbers using exponential notation. For example, 10,000 displays as 1.00E+04. Select the number of decimal places from the Decimal Places list. Currency displays values with the currency symbol you specify. The default is the American dollar sign. For example, $15.00 is displayed when the value is 15 and 2 is selected in the Decimal Places list. You can select a different currency symbol from the list, or enter a custom currency symbol and country code. Designer recognizes the following formats for numbers: Integers Decimal fractions Scientific notation Currency 123, -123 1.23, 0.12, -.12 1.23E2, -1.23E12 $2.50, ($600.09)
Notes can store numbers from 2.225E-308 to 1.798E308 with 14-digit accuracy.
Date/Time fields
Date/Time fields display time and date information in a variety of formats. You can define a date or time field as editable by the user, or you can choose a computed option so the user cannot change the field value. Dates may range from 1/1/0001 through 12/31/9999. Entering two-digit years between 00 and 49 assumes the century starting in the year 2000. Entering two-digit years between 50 and 99 assumes the century starting in the year 1900. If you want users to enter a four-digit year in the field, on the
Chapter 6: Designing Fields 129
Control tab of the Field Properties box, select On input Require user to enter four digit years. Times may range from 00:00:00:00 through 23:59:59:59 in the 24-hour format and from 12:00:00 AM through 11:59:59 PM in the 12-hour format. Choosing a Date/Time format On the Control tab of the Field properties box you can select the format for the display of the Date/Time field. You can choose to use the date/time display based on users workstation preferences, or you can customize the display. To display a date 1. Select or create a Date/Time field. 2. On the Control tab, select Display Date. Select Users settings to use the preferences from the users workstations. Select Custom to customize the display. If you select Custom, choose display options. As you select options, the sample will change to show you what the user will see. Note If you specify a comma as a date separator (for example: 11,15,98) then you must use a semi-colon if you are separating multiple dates in a list (for example: 11,15,98; 12,15,98; 1,15,99). If you specify a semi-colon as the date separator, then you must use a comma to separate multiple values in the list. The following are the date display options: Show: All Only month, day, and year Only weekday, month, and day Only month and year Only month and day Only year Special: None Show today when appropriate. Always show four digit year. Show four digit year for the 21st century Show year only when not this year
130 Application Development with Domino Designer
Format: YMDW - Year, month, day, weekday. For example, 98 12/17/Thu. WMDY - Weekday, month, day, year. For example, Thu 12/17/98. WDMY - Weekday, day, month, year. For example, Thu 17/12/98. To display a time 1. Select or create a Date/Time field. 2. On the Control tab select Display Time. Select Client to use the preferences from the users workstations. Select Custom to customize the display. If you select Custom, choose display options. As you select options, the sample will change to show you what the user will see. The following are the time display options: Show: All Hours, minutes, and seconds Hours and minutes Hours only Format: 12 hour 24 hour To show both date and time together in the same field select both Display Date and Display Time. Time zone options Choose any of these time zone options on the Control tab of the Field Properties box: Adjust time to local zone - Displays the time relative to the time zone in which the document was created. For example, if the document was created at 3:00 PM in Boston and is read by a user in Los Angeles, the creation time is adjusted to the Pacific U.S. time zone and displays as 12:00 PM. Note In order to take advantage of time zone conversion, the date must be included in the field. Always show time zone - Displays the zone in which the document was created as a part of the value. In this case, the time itself is not adjusted for the readers time zone; instead, Notes displays the creators time zone. For example, if the
Chapter 6: Designing Fields 131
document was created in Boston at 3:00 PM, the user in Los Angeles sees the creation time as 3:00 PM EST. Show only if zone not local - Displays the zone in which the document was created only if the document was created in a different time zone than it is being viewed in. For example, if the document was created in Boston at 3:00 PM, users in the U.S. Eastern standard time zone see the creation date as 3:00 PM, while users in other time zones see the creation date as 3:00 PM EST. Note In order to take advantage of time zone options, the date must be included in the field. Examples: Possible date/time formats 10/30 10/30/95 10/30/1995 Monday 10/30/95 Monday 10/30/1995 October 30, 1995 Monday October 30, 1995 Today Yesterday Tomorrow Monday Tuesday Wednesday Thursday Friday Saturday Sunday 10/30 11:00 PM 10/30/95 11:45:30 AM 10/30/1995 11:45:30 AM Monday 10/30/1995 11:45:30 AM
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
Date a document is created Date and time Date a document is modified Current date Current date and time
To create a calendar pop-up control Users can click a helper button on the field box to bring up a one-month calendar on which they can select the date they want.
1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style. 3. On the Control tab, choose: Display Date Users settings or Custom display For Custom display, choose display options. To create a time control Users can select time by clicking on the control and sliding the selection bar to a new time.
1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style. 3. On the Control tab, choose: Display Time Users settings or Custom display
134 Application Development with Domino Designer
For Custom display, choose display options. To create a duration control Users can select a range of time with a duration control, for example, from 12:00pm - 1:00pm.
1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style and Allow Multi-Values. 3. On the Control tab, choose: Display Date Users settings or Custom display For Custom display, choose display options. Examples: Creating a field to display dates and times Tracking modification dates You want to track the dates on which purchase requisitions are created and modified. On the Purchase Requisition form, you create a computedwhen-composed Time field called CreationDate with the formula @Created. This date always shows the date the author first saves the document. To track editing dates, you also created a computed Time field called ModifiedDate with the formula @Modified. This date is the same as the CreationDate the first time the document is saved but is updated automatically each time the document is modified. Determining the daily age of a document In your Service Tracking database, you want to track the age of request documents. On the Request form, you create three fields to calculate the information.
The first field is a computed Time field called DateCreated containing this formula:
@Created
The second field is a Time field named CurrentDate containing this formula:
@Now
The third field is a computed Numbers field that is calculated by this formula, which uses the values from the previous two fields:
@Abs(@Integer((CurrentDate - DateCreated) / (60 * 60 * 24)))
Notes stores dates as a number of seconds, so that number is converted to days by dividing it by (seconds per minute [60]) * (minutes per hour [60]) * (hours per day [24]).
Names fields
Create a Names field to display user names. A names field can be computed or editable. If you associate the formula @UserName to a Names field, the name will appear the way it appears in Notes IDs for example, Sara Ryan/Acme/US. To display only the common name portion of names, use the [CN] parameters with @Name. For example, in an editable names field called Members use this formula as the default value:
@Name([CN];Members)
This formula displays the name Sara Ryan if the users hierarchical name is Sara Ryan/Acme/US For more information about formulas for displaying user names, see the Programming Guide.
select a lookup option for the field, users press CTRL + ENTER or click the entry helper button to the right of the field to see a list of possible entries. Lookup options are not supported on the Web. Lookup options Use Address dialog for choices - This option displays the Names dialog box so users can select names from a Personal Address Book or Domino Directory. Select Look up names as each character is entered to help users fill in a name quickly. Notes looks up a match for the typed letters in the open Address Book or directory. Use Access Control List for choices - This option brings up a list of people, servers, groups, and roles in the access control list. Use View dialog for choices - This option brings up a dialog box containing entries from a column in a database view. Select the database to look up, select a view, and select a column number. For information on the access control list for a database, see Managing Domino Databases.
Field Type
Usage
Available Dialog list Users either press ENTER or click the entry helper button to see all the choices at once, press the space bar to display choices one at a time, or type a letter to display the first choice beginning with that letter. Select Display entry helper button if you do not want to display a button next to the field that a user clicks to view all the choices. Dialog lists are not available in layout regions. Not available Checkbox Each choice is displayed with a box users click to select. Checkboxes have border and column options. To create a wide checkbox panel, choose a column number between 2 and 8. Radio button Each choice is displayed with a button; users can click only one. Radio buttons have border and column properties. To create a wide button panel, choose a column number between 2 and 8. Not available
Available
Not available
Not available List box Each choice is displayed with an expanded list box. Users click an entry to select it. List boxes have border, size, and placement options. To resize the list box without dragging it, change the Width and Height measurements. To move the list box in a layout region without dragging it, change the Left and Top measurements. Available Combo box Each choice is displayed with a drop-down list box. Users click the drop-down arrow to see the entries and click the one they want. Combo boxes have border, width, and placement options. To resize the combo box without dragging it, change the Width measurements. To move the combo box in the layout region without dragging it, change the Left and Top measurements.
Available
Not available
Use Address dialog This option displays the Names dialog box so users for choices can select names from a Personal Address Book or Domino Directory. Click Look up names as each character is entered to help users fill in a name quickly. Notes looks up a match for the typed letters in the open Address Book or directory. Use Access Control This option brings up a list of people, servers, groups, list for choices and roles in the access control list for the database. Use View dialog for This option brings up a dialog box containing entries choices from a column in a view. Select the database to look up, select a view, and select a column number. Use View dialog for choices Looking up values in a view lets you retrieve data from databases. This is convenient for displaying choices that change, such as customer names, sales territories, and job titles. View lookups provide the following benefits: Non-designers can maintain choices without having access to the rest of the database design. Designers can avoid hard-coding choices into fields. This makes verification and maintenance easier. Designers can hide the design of the database without affecting maintenance of choices. Designers or administrators can customize the application or conveniently translate lookup information to other languages. Users can review choices and codes more conveniently from outside the form or application.
Note Use lookups sparingly because they adversely affect the performance of the application. To retrieve information from Domino or non-Domino databases you can use @DbColumn and @DbLookup formulas instead of using a View dialog lookup. For more information on @DbColumn and @DbLookup, see the Programming Guide. Examples: Creating a field to display a list of choices You want to make it easy for users to include a product number when they fill out a Purchase Request. Create an editable Dialog List field named ProductNumber and use the Use View Dialog for choices property to generate choices. You select the Inventory Database, the By Product Number view, and Column 1, where product numbers are listed. Creating a formula-generated list A Travel Request form contains an editable Listbox field called Country that uses the following formula to show only those countries relevant to the location selected by the user:
@If(Location="Europe";"France":"Germany":"Italy":"Spain"; Location="Far East";"Japan":"Singapore":"South Korea";Location="North America";"Canada":"Mexico":"United States";"")
If you use aliases, the leftmost name is displayed in the document, but the rightmost name is stored internally.
This can be confusing to users. To display the full names as category names, you must use a hidden field or column formula that converts the aliases back to their full names. For example, the following is a column formula for the view to convert the alias back to their full names for display in the categorized column:
@If(RequestType="HW";"Hardware Request";RequestType="SW"; "Software Request";"Service Request");
Example: Using aliases for choices in a list You want Service Repair Requests to have a field for product groups. Create an editable dialog list field called Product and on the Control tab, select Enter choices (one per line). Include aliases, so that if the product groups change, any formula referencing the alias still works. Enter this list: Microwaves | 1 Ovens | 2 Refrigerators | 3 Specialty Items | 4 Toasters | 5
Columns that refer to list fields use the alias names in the view, not the word seen by users in the document. To display the contents of the Product field in a view, you need to use a hidden field or column formula that converts the alias name to its long form:
@If(Product="1";"Microwaves";Product="2";"Ovens";Product="3"; "Refrigerators";Product="4";"Specialty Items";Product="5";"Toasters";Product="";"";"");
Password fields
A Password field is a text field that maintains a users privacy by displaying each character a user enters as an asterisk on the screen. The contents of the Password field is not secure, and it is visible in the Document Properties box from the Notes client. There are several ways to secure the contents of a Password field. If you are using the Password field as a method for securing an application, the best way to secure the contents of a Password field is not to save the contents after the entry is verified. This can be done using a formula that clears the field once its been verified. You can use the input translation event or a LotusScript QuerySave event. Example: Using an input translation formula This formula is an input translation formula for a Password field. When the user enters a password, Domino looks up the user in the Domino Directory and gets the users HTTPPassword field. Then, it compares the value that the user inputs into the field with the HTTPPassword field. If the values match, it presents a prompt saying You passed. If the values do not match the prompt says You entered an incorrect password.
x:=@DbLookup("";"Server/Acme":"names.nsf";"($Users)"; @Username;"HTTPPassword"); REM REM REM REM "This compares the value above to the value the user entered after running it through the @Password hash function and prompts the user whether they typed in a valid password or not.";
@if(@isError(x);@Prompt([OK];"Error";"Error");@Password(Passwo rd) = x;@Prompt([OK];"You passed";"You passed");@Prompt([ok];"Password failure";"You entered an incorrect password")); REM "This deletes the password field."; @Unavailable
Example 1: Using a QuerySave event This script determines whether the password field contains a password. If it does it gets the name of the author of the document and puts the abbreviated form of the name into the PublicEncryptionKeys field. This effectively encrypts the Password field with the authors public key. This does not involve a lookup to the Domino Directory to get the key. It is retrieved from the users ID file.
Dim doc As NotesDocument Dim db As NotesDatabase Dim session As New NotesSession Set db = session.CurrentDatabase Set uidoc=Source Set doc=source.Document If doc.GetItemValue("Password")(0) <> "" Then Set PkName = New NotesName(doc.GetItemValue("Author")(0)) Call doc.ReplaceItemValue("PublicEncryptionKeys", PkName.Abbreviated ) End If
Example 2: Using a QuerySave event This script determines whether one or more Password fields contains a password. If one of the fields does contain a password, the script gets the values from the Author field and the OtherEditors field (which might contain a group) and expands the OtherEditors field so that it has names and puts the abbreviated form of the name into the PublicEncryptionKeys field. This effectively encrypts the Password field with the public keys for all unique entries in the two fields. This does involve a lookup to the Domino Directory to get the keys for each of the users listed, unless the only value is the name of the current user. If there is more than one name to look up, then it finds the public keys from the Domino Directory. If the only key to look up is the authors, it is retrieved from the users ID file.
Dim s As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Set db = s.CurrentDatabase Dim uidoc As notesuidocument
If (doc.GetItemValue("Password1")(0) <> "") Or (doc.GetItemValue("Password2")(0) <> "") Then Call doc.ReplaceItemValue("PublicEncryptionKeys",Evaluate(|@Name([A bbreviate];@Unique(Author:OtherEditors))|,doc)) End If
Formula fields
Formula fields are used to populate a subscription list, which works in conjunction with the Headlines.nsf database. The Headlines database is accessible from the Bookmark pane of the Notes client and can be used as the home page of a Notes client. The Headlines database includes a feature called subscriptions. Each database designer has the option of including a subscription form in a database. When a user subscribes to a database (by filling out and saving a subscription form in that database), it triggers a server task that will notify the user whenever a document of interest is saved in that particular database. The criteria that the server looks for is contained in a formula field on the subscription form. Although users fill out the subscription form in the database they want to subscribe to, the subscription documents are stored in users headlines databases on their local client. You can use the default subscription form, which is located in the headlines.ntf database. To use the default form, copy and paste it into your database. The subscription form, named $Subscription, is in the Headlines.nsf or Headlines.ntf database that is included with Designer. You can use the subscription form as is or you can customize it. If you customize it you must include the formula field. The formula field on the $Subcription form is named $HLFormula and is on the second tab of the tabbed table on the right side of the form. The $HLFormula field is a computed field. If you choose to keep the formula field computed, you write a formula that resolves to a formula for a subscription list. A formula field must resolve to a formula in order for the server to be able to retrieve the subscription criteria for the user. Another option for the formula field is to choose Literalize fields on the Field Info tab of the Field Property box. When you select the Literalize fields option, you are programming the formula field to accept the formula you put in without compiling it. If you literalize a formula, the field references must be: text, text list, number, number list, date, date range, or
144 Application Development with Domino Designer
date list. If the field referenced is of any other field type, it will be left out as a field reference. The following is an example of a formula for a formula field for which Literalize is selected as an option:
Select (Names = ExampleNames) & (Numbers = ExampleNumbers) & (Categories = ExampleCategories)& (Dates = ExampleDates)
If you choose the computed option, the formula you enter must resolve to another formula. This provides the ability to optimize complicated formulas before they are saved. After the formula is evaluated, the resulting formula is saved. If the resulting formula is invalid, the field is saved with a value of type error. In some cases, the user would never be able to exit out of the document. To differentiate between success and failure, you should test in the QuerySave event to determine if the Formula field is indeed a formula. If it is not, then the computation did not result in a valid formula. For example, a computed formula field has the following formula:
tLitNames := "\"" + @Implode( ExampleNames; "\" : \"") + "\""; tLitNumbers := @Implode( @Text(ExampleNumbers); " : "); tLitCategories := "\"" + @Implode( ExampleCategories; "\" : \"") + "\""; "Select (Names = " + tLitNames + ") & (Numbers = " + tLitNumbers + ") & (Categories = " + tLitCategories + ")"
field property Compute after validation is useful when a field is dependent on values in other fields and you want to be sure that the calculation occurs after those fields have been validated. When its important for users to see results as they proceed, you can force each field to be calculated as its filled in by selecting the form property Automatically refresh fields. This is useful when fields at the bottom of the form are dependent on field values at the top. Be aware that this property can slow down document display time if the form has many computed fields. There are three types of computed fields:
Type of computed field Computed Computed when composed Formula calculates A computed field formula calculates each time a user creates, saves, or refreshes a document. A computed-when-composed field formula calculates only once: when the user first creates the document. Use this type of formula in a field to preserve information about the origin of a document, such as the creation date or original author, or to create a field whose original value never changes, such as a document sequence number. A computed-for-display field formula recalculates each time a user opens a document. Use this type of formula in a field to display information that is relevant only to the immediate session, such as the current time or the results of calculations that you dont need to save. The field value exists during the current session only and is not stored. You cannot display the contents of a computed-fordisplay field in a view.
To create a formula for the value of a computed field 1. Select any type of computed field. 2. Select Value from the Objects tab of the Info list. 3. Write a formula, a field name, or a text string in quotation marks in the Script area of the Programmers pane. 4. Click the green check mark to verify and save the formula. 5. (Optional, for computed or computed-when-displayed fields) To delay computing until after validation formulas run, choose Design - Field Properties and select Compute after validation on the Field Info tab. 6. (Optional) To recalculate field values while users edit a document, click the form and choose Design - Form Properties, click the Form Info tab, and select Automatically refresh fields.
Note Automatically refreshing fields can slow down document display time. A faster alternative is to write a LotusScript field event to recalculate the document or update other fields when users move from a specific field. For information on writing formulas for fields, see the Programming Guide.
document is composed with this form, the field value is copied from the document that is currently highlighted if that document contains the specified field. An alternative to an input translation formula is to write a script for the Exiting event that verifies information. To create an input validation formula 1. Create an editable field. 2. Select the Input Validation event from the Objects tab of the Info List. 3. Write a formula in the Script area of the Programmers pane using @Failure and @Success. 4. Click the check mark to save the formula. @Failure prevents the user from saving the document until the user enters a value that meets the criteria. As part of the formula, include text that clearly indicates what is wrong and how the user can correct it. For information on writing formulas for fields, see the Programming Guide. Examples: Creating a formula for an editable field Default value formula examples The default value formula provides an initial value for an editable field. You can set the value to a specific number or text string, or you can use a formula. For example:
The formula 0 @Now @Name([CN];@Username) Price Returns The number 0 The current time and date The common name portion of a users hierarchical name The value of the field named Price
Connecticut:New York:New Jersey A text list containing Connecticut, New York, New Jersey Product + , + Department The value of the field named Product, followed by a comma and a space, and the value of the field named Department
Example: Input translation formula The following formula translates the text in the Attorney field for display with initial capital letters. If a user enters the text john smith in the Attorney field, it is translated to John Smith when the document is saved.
@ProperCase(Attorney);
The following formula gives documents a uniform look by capitalizing the initial letter of the value in the Subject field and removing extra spaces.
@Trim(@ProperCase(Subject));
User must enter a value for @If(Subject = ; @Failure(You must enter a subject the Subject field for your document.); @Success)
Examples: Calculating a value for a computed field Combining text and field values to create a message The SchedDisp field, which displays only when users read or print a document, can display two different messages depending on the value in the Sched field. If it is a special, temporary schedule, the message combines words with a text-based version of the value in the Date field. If the schedule is permanent, the message is Regular schedule.
@If(Sched = "Special schedule"; "Special schedule for week starting: " + @Text(Date); "Regular schedule")
Totaling monthly budget figures The MonthlyTotal field in the Budget form is a computed Numbers field that is formatted for Currency with two decimal places. The formula totals the values in each category to calculate the total budget.
Advertising + Entertainment + Miscellaneous + Overhead + Salaries + Travel
Storing the date and time a document is created Notes automatically uses internal fields to store the date and time a document is created. To display this information, define a Time field that is computed-when-displayed, and then write this formula for it:
@Created;
The field is defined as computed-when-displayed, rather than computed, to avoid storing the creation date information twice. Determining the normal work day age of a document This field formula determines the age of a document in work days, based on a five-day work week. In the following example: DateCreated is a field containing the date when the document was created. The fields data type is Date/Time, and it is computed using the formula @Created. Currentdate is a field containing the current date of the document. The field data type is Date/Time, and it is computed using the formula @Now. Because Notes sorts dates in seconds, you must divide by (seconds per minute) * (minutes per hour) * (hours in a day), which equals 86400. Weekend_days is a temporary variable that contains Age of document in days divided by Number of days in a week, multiplied by Days in a weekend.
temp := (@Date(Currentdate) - @Date(DateCreated)) / 86400; weekend_days := @Integer((temp / 7)) * 2; wkday := @Weekday(DateCreated); adjust := @If(((wkday + @Modulo(temp; 7) - 7) > 0); 2; 0); working_days := temp - (weekend_days + adjust); @If(Currentdate = ""; 0; working_days);
Hiding fields
Use hidden fields to perform interim calculations or to store information you do not want users to see. In the Designer templates, hidden fields appear at the bottom of forms, preceded by the heading Hidden fields. Hiding fields is not a security feature. Users can see the value of hidden fields on the Fields tab of the Document Properties box in the Notes client. To keep the data fields safe, encrypt, rather than hide, the fields.
Hiding options
When you hide a field, you are actually hiding the paragraph on the form that contains the field. If there is text, such as a field label or graphics in that paragraph, Designer hides them with the field. You can hide a field and any associated text or graphic all the time or only at certain times. For example, information useful only when users create or edit documents can be hidden during reading, printing, and copying; information that is used for display, such as a computed field that displays the result of an authors choice in an editable choice list field, can be hidden during editing. The following are options for hiding fields: Hide paragraph from Notes 4.6 or later Information is hidden when the application opens on a Notes 4.6 workstation. Hide paragraph from Web Browsers The information is hidden when the application opens on a Web browser.
Chapter 6: Designing Fields 153
If the paragraph is hidden when: Previewed for reading Previewed for editing
Then: The hidden information isnt visible when users read documents in the document preview pane. The hidden information isnt visible when users work on documents in Edit mode in the document preview pane. The hidden information isnt visible when users open documents in Read mode. A field that cant be read cant be printed either. The hidden information isnt visible when users work on documents in Edit mode. The hidden information isnt visible on printed documents. The hidden information isnt visible when information is copied to and pasted from the Clipboard. This setting doesnt affect documents copied at the view level. A formula determines the circumstances in which information is hidden.
To hide a field
If you have computed fields that users dont need to see, or if you create two fields one for display when reading and one for use when editing you can stipulate when to hide the fields. 1. Select the field you want to hide. 2. Choose Design - Field Properties. 3. On the Hide tab: Select Hide paragraph when document is: and click all situations when users dont need to see the field information. or Select Hide paragraph if formula is true and write a formula in the formula window on the Properties box to describe the situations when users dont need to see the fields. For more information on using a formula to hide a paragraph, see the Programming Guide. Choosing Refresh fields when keywords change displays documents faster than the form property Automatically refresh fields. It is useful for showing or hiding parts of the form when you have hide-when formulas that are dependent on values in the field.
154 Application Development with Domino Designer
Examples To make documents more readable, you decide to modify the Marketing Ideas form to show only the model name for the product that the author selects. The Models field is a radio button field that displays these choices for refrigerator models: Econo-Freeze Icebox 2000 InstaFreeze Premium The Chiller You hide the Models field when previewed and opened for reading. You create a computed text field called SelectedModel and locate it under the Models field. SelectedModel uses the value from the Models field. You hide the SelectedModel field when opened for editing. Now when users create a new document, all model names are shown. When users read a document, they see only the model name chosen by the author.
To create a field in a layout region: 1. Open the form. 2. Click the layout region and choose Create - Field. 3. Choose Design - Field Properties and assign a name to the field. 4. Assign any field type except Rich Text and then select Editable or a computed option. 5. Drag the field horizontally or vertically to adjust its width and height. To create a field label: 1. Choose Create - Layout Region - Text. 2. Click the text area, choose Design - Object Properties, and type a field label in the Text box. Click the green check mark. 3. Drag the text area above or to the left of the field and drag it to the size you want. 4. Click the Style tab to change the text style for the label. To resize a field: Placing a field in a layout region allows you to adjust the way field values appear or to limit the number of characters users can enter in a field. To resize a field, drag the borders of the field.
To inherit the parent document a Web browser user must open an existing document before creating the new document. The options Inherit as rich text and Inherit as Collapsible rich text both inherit the topic in its entirety into the new document. Collapsible sections and inheriting as link are not supported on the Web. To enable Web users to create a new document from an open document, you must provide a form action to create a new document. 1. Open the form. 2. Create a rich-text field to store the inherited document. 3. Choose Design - Form Properties. 4. Click the Defaults tab. 5. Select On Create: Inherit entire selected document into rich text field. 6. Enter or Select the name of the rich-text field and select a document display option.
For more information on creating a response hierarchy, see Creating a response hierarchy.
Use Sends blind copy to users listed in field Delivers mail high, medium, or low priority Returns a report when mail is delivered to recipient Returns a receipt when recipient reads mail Routes mail via cc:Mail
Use Passes HTML directly to the server Passes HTML information to be hosted within the <HEAD> tag for a document. The passed information might be meta data (using a <META ...> tag) or JavaScript code (using a <SCRIPT ...> tag) or CSS information (using a <STYLE ...> tag). After Web users submit a document, Domino responds with the default confirmation Form processed. To override the default response, add a computed text field to the form, name it $$Return, and use HTML as the computed value to create a customized confirmation.
$$Return
To create a choice list $VersionOpt field Use a choice list field if you want users to be able to choose the method of version control each time they create a document. 1. Create a field named $VersionOpt and define it as an editable dialog list field, in the Field Properties box. Do not select Allow multi-values or Allow values not in the list. 2. On the Control tab select Enter choices (one per line). 3. Enter one or more of the following options: Dont track versions | 0 Create response if File - Save As New Version is used | 1 Create response automatically | 2 Promote to main document if File - Save As New Version is used | 3 Promote to main document automatically | 4 Create additional main document if File - Save As New Version is used | 5 Create additional main document automatically | 6
3. For a computed field, select Value from the Objects tab of the Info List in the Programmers pane. For an editable field, select Default value from the Objects tab of the Info List in the Programmers pane. 4. Write a formula in the Script area of the Programmers pane. The FolderOptions field must contain the value or default value 1 or 2. 1 (Prompts user to choose folder) This value prompts the user with the Move to Folder dialog box. Selecting a folder and clicking Add puts the new document in a folder. Selecting Cancel saves the document without putting it in a folder. 2 (Save to current folder) If the user is creating the document from an open folder, this value saves and adds the document to that folder. If the user is not creating the document from a folder, the document is saved but not added to a folder.
Overview of framesets
A frameset is a collection of frames and can add structure to your Web site or Notes database. A frame is one section, or pane, of the larger frameset window and is independently scrollable. A frame can contain a form, folder, page, document, view, navigator, or frameset. The frame can also contain a Web page and be associated with a specific URL. Framesets let you create links and relationships between frames. For example, you can leave one page displayed as users scroll or link to other pages or databases.
Designers can set a frameset to launch automatically when a database, form, or page opens.
165
Note Framesets created with Release 5 do not work with previous releases of Notes. A database opened by a previous version of Notes will be launched using restored as last viewed by user.
Creating a frameset
1. Open Designer and choose Create - Design - Frameset. The Create New Frameset dialog box appears.
2. At the Number of frames drop-down box, select two, three, or four frames. You can make adjustments later. 3. Next to Arrangement, click one of the arrangements for the frames. 4. Click OK. The frameset with the chosen layout appears. 5. (Optional) Use the Frame action buttons, the Frame menu options, or keyboard keys to further refine your frameset. You can: Split the selected frame vertically by choosing Split into Columns (SHIFT - INSERT key). Split the selected frame horizontally by choosing Split into Rows (INSERT key). Delete the selected frame by choosing Delete Frame (CTRL - DELETE key). Refresh the content of the selected frame by choosing Refresh Content. Remove the content of the selected frame by choosing Remove Frame Content (DELETE key). Cycle through frames by using the TAB key (SHIFT - TAB cycles backwards).
166 Application Development with Domino Designer
6. Open the Frameset Properties box. At the Basics tab: Name the frameset. Provide an alias for the frameset. An alias is an internal name for the frameset. Use an alias to change or translate the frameset name without causing reference problems. The alias appears with the initial list of framesets in the Work pane. Add a comment. The comment appears with the initial list of framesets in the Work pane. Click Available for public access if you want to have the frameset available for public access. Enter a title for the frameset in the Title field or use a formula to compute the frameset title by clicking Formula Window and entering the formula. The frameset title is the name that appears in the Windows tab when the frameset is launched. 7. Add content to each frame by using the Frame Properties box. 8. To move borders between frames, you can: Drag borders with the mouse. Use the Arrow keys to drag the border in the direction of the arrow and the SHIFT + Arrow keys to drag the border in the opposite direction. 9. To preview the frameset: To preview the frameset on the Web, choose Frame - Preview in Web browser and choose a browser. To look at the HTML source, click Synopsis in the Design pane. In the Design Elements tab of the Design Synopsis dialog box, choose framesets and add each frameset for which you want to view the HTML source. Make sure to check Include JavaScript and HTML in the Contents tab. You can also look at the HTML source by previewing the frameset on the Web and then viewing the source with the chosen Web browser. To preview the frameset in Notes, you can launch the database into the frameset or select the frameset name in the Work pane and click the Preview in Notes icon from the Designer toolbar.
If you want a view or folder on the Web, consider first embedding the view or folder on a page or form. If you choose to make the embedded view an embedded view applet, you preserve much of the HTML view functionality and provide features such as resizeable columns, multiple document selection, and scrolling. URL To put a Web page into a frame, choose URL and enter the full URL specification (for example, http://www.lotus.com). You can also paste in a URL or use a formula that evaluates to a URL. You receive an error in the frame if the URL you specify is not accessible. Note that all content rendered in framesets in Designer uses the native Notes Web browser even if your current browser selection is something else. When you click a link in a Web page (in the Notes client or in a Web browser), the link may open within the same Web page or in a new window, depending on the setting for that Web page. 5. (Optional) Enter the target frame for links activated within the current frame.
Scroll bar properties. Choosing On forces a scroll bar for the frame; choosing Off causes no scroll bar to appear. If you choose Auto, the scroll bar appears if it is needed. The default is Auto. Allow Resizing. If you choose Yes, you allow users in the Notes client or Web browser to change the height and width of frames by dragging their borders. If you choose No, users cannot drag borders to resize the frame. 3. At the Frame Border tab, you can specify the following properties: For Border Style (Applies to this frame): 3-D border allows three-dimensional borders between the current frame and its adjacent frames. Apply to all frames adds three-dimensional borders between all frames in the frameset. For Border Style (Applies to all borders in frameset): Border width (in pixels) The default is 7 pixels. Border color choose a color from the drop-down color chart. Click on the system (monitor) icon at the top of the color chart to get the default color. Click on the wheel icon at the top of the color chart to create a custom color. 4. At the Advanced tab, specify the Frame spacing and margin height and width. Frame spacing. The default is minimal space between frames. You specify spacing between frames in pixels. This property is not supported in the Notes client. Margin height and width. The default is minimal space between the frame border and the frame content. You specify height and width in pixels. This property is not supported in the Notes client.
Views
A view is a sorted or categorized list of documents. Views are the entry point to the data stored in a database. Every database must have at least one view, although most databases have more than one view. Here are the general steps in planning your view: 1. Before you actually create the view, think about: The type of view you want (shared, private, and so on). Whether the view is a standard view or a calendar view. The categories in the view. Whether you want to create an embedded view on a form, subform, page, or document. Whether the view will be displayed on the Web. If so you may want to consider creating an embedded view on a form, subform, page, or document or consider creating a view applet or an embedded view applet. 2. Create the view by clicking the New View button in Designer. 3. Name the view. 4. Add columns to the view. 5. Set up which documents will display in the view by writing the views document selection formula. 6. Set up what will display in each column by programming the column value. 7. Set up the sorting order for the columns. 8. Set the style for the view, row, and columns. 9. Close and save the view.
173
In addition to creating views, you can create folders. Folders are containers used to store related documents or groupings of documents. Folders have the same design elements as views and are designed in much the same way as views. You embed a folder pane in the same way you embed a view.
Standard views
A standard outline view is a table of contents for a database and is the most common type of view. It organizes documents by rows and columns. Each column displays a type of information about the document, such as author or date of creation. Each row displays selected pieces of information from one document. One column in the view is usually the organizing element for example, a column entitled Date might organize the documents in chronological order. In a discussion database, you might use a column entitled Topic to display the contents of the Subject field for each document in the view. In a tracking database, it might be the customer or product name. Here is the same view from a review database as shown through Netscape Navigator and through Notes.
Standard views, whether in Notes or on the Web, contain the default settings in the View Properties box. For example, the checkboxes in the For Web Access section of the Advanced tab of the View Properties box are not checked. If you want to create a view for the Web, consider creating a view applet or embedded view applet. To open a document in a standard view, Notes users double-click a row; Web users click a document link in one of the columns. A standard view on the Web maintains the column and row format of standard Notes views (unless you use HTML formatting to customize a view), except that on the Web, a navigation bar on the top or bottom of the screen contains buttons that users click to expand, collapse, and scroll the view. On the Web, each time you open, scroll, expand, or collapse a view, Domino converts the view to an HTML page. Each snapshot of the view is a newly generated HTML page. The concept of a selected document in a view in Notes does not apply to a view on the Web. To prevent line wrap on the Web, specify 1 in the Lines per heading setting in the View Properties box. Domino converts this setting to a NOWRAP HTML attribute. Specifying a number greater than 1 causes lines to wrap on the Web. The same guidelines are true for the Lines per row setting.
Calendar views
A calendar view groups documents by date. In fact, the first column of a calendar view must evaluate to a date and time. Such views are useful for organizing schedules, meetings, and appointments.
When you create a calendar view, users have access to the following features: Choices for viewing entries in a Two-Day, Week, Two-Week, Month, or Year format. Point-and-click navigation among days, months, and years. The ability to create new calendar entries and edit existing entries. Integrated Task, Event, and Anniversary display. The ability to print calendar entries for a selected range of days. Web users can see all calendar entries. Domino converts calendar views to HTML tables. Therefore, Domino restrictions for tables also apply to calendar views. You cannot create new appointments or scroll through entries within a single day on the Web.
Shared views
Shared views are available to any user with at least Reader access to the database. Most views that you design for databases are shared views. Users with Designer or Manager access can create shared views, as can Editors for whom the manager has selected Create personal folders/views in the access control list. You can create the following specific types of shared views: Shared, contains documents not in folders Shared, contains deleted documents (used in conjunction with Allow soft deletions in the Advanced tab of the Database Properties box) Shared, private on first use Shared, desktop private on first use (saves private views in users desktop.dsk files rather than in the database) Shared, contains deleted documents A Shared, contains deleted documents view allows you to view a list of documents in the database which have been deleted. You can recover deleted documents by dragging them out of the trash to the folder where you want them. This view assumes that the database manager has already selected Allow soft deletions at the Advanced tab of the Database Properties box. The Allow soft deletions property lets deleted documents remain in the database and not be permanently removed for a set number of hours. The hours are set by the database manager in the Advanced tab of the Database Properties box. After that time, the document is permanently deleted from the database. Shared, private-on-first-use views A Shared, private-on-first-use view begins as a shared view and becomes a private view as soon as a user accesses and saves the view. These views are a convenient way to distribute customized personal views to multiple users. You usually create this type of view by using @UserName to customize the display for each user.
After a user saves a shared-to-private view, the users copy of the view no longer inherits design changes. For example, if you add a column to the view, anyone using a private version of the view wont see the new column. To obtain design changes, users must delete their private versions of the view and open the shared-to-private view again. Shared-to-private views are not a security measure, as they do not protect data. If you create a shared-to-private view that omits certain documents, a user can still create a private view that includes them. Shared-to-private views are stored in the database as long as they are shared. After the first use, Domino uses the Create personal folders/ views option to determine where to store the view. Shared, desktop private-on-first-use views If you want the shared-to-private view to be stored in a users desktop.dsk files rather than in the database, choose Shared, desktop private on first use as the View Type when you create the view.
Private views
Users can create private views to organize documents in personalized ways by choosing Create - View. If a user has rights to create private folders/views in the access control list, private views are stored in the Notes database. If the user does not have the access control list right to create private folders/views, personal views are stored in the users personal workspace file (desktop.dsk). Private views are not supported on the Web.
Creating a view
To design a view, you must have Designer access in the access control list of the database. For information on database access, see Managing Domino Databases. 1. Select or open a database in Designer. 2. Click Views in the Design pane. 3. Click the New View button above the Work pane. The Create View dialog box appears. 4. Enter a name for the view in the View name field. 5. Choose a View type in the View type field.
6. Select a location in the Select a location for the new view field. If you want the view to appear at the top level, do not select anything in this field. Otherwise, click the name of the view under which you want the new view to appear. 7. Click the Copy style from button. Click Blank if you do not want to copy another views style. Otherwise, click the view whose style you want to copy. If the style uses selection by formula, the views selection criteria appears in the Selection criteria field. 8. (Optional) You can use the Fields and Functions button and Formula window button to further refine the new views selection criteria. 9. Click OK to create the new view. 10. Double-click the new view in the Views list to open it. 11. Click the column labeled #, choose Edit - Clear, and Yes to confirm. 12. Choose Create - Insert New Column to create the first column. 13. Add other columns by choosing either: Create - Insert New Column to create a column to the left of the highlighted column. Create - Append New Column to add the column after all existing columns. 14. To give each column a title, choose Design - Column Properties and click the Column Info tab. Enter a name in the Title field. 15. Click each column in the Work pane. In the Programmers pane, add programming to determine the column value. For example, a column can list the creation date or the size of each document. 16. Click the current view in the Objects list and expand it. Select View Selection and add programming for the views document selection. 17. Choose Design - View Properties and click the Style tab to style the view. 18. Click each column and choose Design - Column Properties. Click the Title tab to determine the font, size, color, and alignment of the column title. Click the Font tab to do the same for values that display in the column. 19. Close and save the view.
Default design for new views To save design time, designate a view as the standard for newly created views or folders in the database. To use a view as the design standard, open the view in Designer and select Default design for new folders and views on the Options tab of the View Properties box. Copying and deleting views and columns To copy a view, click Views in the Design pane, in the Work pane click the view you want to copy, choose Edit - Copy, and then Edit - Paste. A copy of the selected view appears in the list of views. Until you rename it, the copied view is named Copy of <selected view name>. To delete a view, click Views in the Design pane, in the Work pane click the view you want to delete, click the view name, and choose Edit - Clear. To copy a column, open the view in Designer, click the column, copy it to the clipboard, select the column to the right of where you want the column to appear, and choose Edit - Paste. To delete a column, open the view in Designer, click the column, and choose Edit - Clear. Limits for views A view can display no more than 32 levels of responses and/or subcategories. For example, if you have 6 levels of subcategories, you can display 25 levels of responses to a main document. If there are more levels of responses than can be displayed, convert your view to a non-hierarchical, flat view, which displays all documents on a single level (by deselecting Show response documents in a hierarchy in the View Properties box). The combined number of sub-level forms, views, and agents that cascade from the top level cannot exceed 200; otherwise, the top-level menus do not display properly. This limit does not apply to the number of forms, views, and macros stored at the top level of each menu. Domino allows up to 200 cascading view and folder names to be displayed on the View menu.
Naming a view
The name you choose for a view is visible to Notes users in the View menu and in the folders pane (unless the view is hidden). The view name is visible to Web users in the Views list. The name is case-sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation. The full name, including all aliases, can have up to 64 characters.
Chapter 8: Designing Views 181
Naming tips
Views appear in alphabetical order in the View menu in Notes and in the View lists on the Web. To force names to appear in a different order, number or letter them. For example: 1. Zebra 2. Antelope If you start a name with a hyphen (-), the name appears before both numbers and letters. When possible, assign a name that indicates how the view sorts documents for example, By Company Name or All by Category or specifies which documents it includes, for example, New Customers. Use consistent names across databases to make it easier for users to recognize views.
Aliases
An alias is another name, or synonym, for a particular view. Use an alias to change or translate the view name without causing lookup formulas that reference the view to stop working. Aliases follow the same naming rules as view names. Enter an alias in the Alias field of the View Info tab of the View Properties box. You can append more than one alias by entering the | (vertical bar) symbol followed by the alias. Make sure you keep the original alias as the rightmost name.
Main View | Top View | View1
To keep both By Premiere Date and DateView as aliases, they enter the following in the Alias field of the View properties box:
Nach Premierendatum | By Premiere Date | DateView
Naming guidelines
Hidden views When you surround a name with parentheses for example, (All) the view does not appear to Notes users in the Notes View menu or to Web users or Notes users in the list of folders and views. For other ways to hide views, see Hiding a view later in this chapter. Shortcut keys Windows, OS/2, and UNIX users can type shortcut letters to select a view. The default shortcut, an underlined letter in a view name, is the first letter in the name that has not already been used by a preceding name on the menu. But if views or folders begin with the same letter, the default shortcut is the first letter that has not already been used by a preceding name. If views or folders begin with the same letter, the shortcut letters may be difficult to see and remember. For example, the shortcut letters (underlined) for these views are
By Author By Date
You can rename the views and omit the repeated word, but in some cases the word is needed to make the names understandable.
Authors Dates
If you cant change the names, you can specify a more meaningful shortcut by typing an underscore before the letter D to assign it as the shortcut for the By Date view, entering the name as
By _Date
Cascading views Creating cascading views lets you arrange lists of views in a hierarchy; that way, a group of related menu items are organized under one item. A user clicks on the higher-level name to display the cascaded list. You probably want to cascade views when you have long lists of views or when you have related views that should be grouped together. To create a cascading view, enter the name you want to appear on the Create menu followed by a \ (backslash), followed by the view name. For example, the Personal Address Book template has two views related to servers:
Server\Certificates Server\Connections Chapter 8: Designing Views 183
Columns
Columns display one type of information about the documents listed such as the document subject, author, or creation date. One column in a view is usually the organizing element for example, in a chronological view, the organizing column displays document creation dates. To add a column to a view in Designer, choose Create - Insert New Column or Create - Append New Column. A view can have a single column or as many columns as you can fit in 22.75 inches (the allotted width of a view).
Omitting a title
If you leave the title blank, the column doesnt have any identifying text. Omit a title if the column is: A responses-only column that indents response documents A categorizing column Hidden (and designers dont need any identifying text when the view is Designer) Not relevant to users
Guidelines
Column titles can contain up to 80 characters in any combination of letters, numbers, and punctuation. To change the font, size, or color of a column title, choose styles from the Title tab of the Column properties box. To allow long titles to wrap to several lines in Notes, set the Lines per heading in the Style tab of the View Properties box to a number greater than 1.
Note that long titles do not wrap on the Web. To prevent line wrap on the Web, specify 1 in the Lines per heading setting in the View Properties box. Domino converts this setting to a NOWRAP HTML attribute. Specifying a number greater than 1 causes lines to wrap on the Web. The same guidelines are true for the Lines per row setting. The number of characters that fit on one line depends on the font and size you select, as well as the width of the column. If a title is not set up to wrap to more than one line and the text is too long for the width of the column, the text is truncated.
To categorize a view, create a column to display categories and then select the option Type: Categorized on the Sorting tab of the Column Properties box. The resulting column, called a categorized column, groups documents with matching values and converts the common value to a category name. The column is usually one that appears on the left side of the view. This column must always appear to the left of any sorted columns.
Other options include: (Recommended) At the Text Properties tab of the Column Properties box, choose a different color for column text and use bold face to make categories stand out. (Recommended) At the Sorting tab of the Column Properties box, select the column style: Sort: Ascending or Sort: Descending to organize the category names. (Sort: Ascending organizes the categories in alphabetical order and descending in reverse alphabetical order.) (Recommended) At the Column Info tab of the Column Properties box, select Show twistie when row is expandable to display a triangle that users click to see categorized documents. (Optional) At the Options tab of the View Properties box, select Collapse all when database is first opened to show only the category names when users open the view. (Optional) At the Advanced tab of View Properties box, select Dont show categories having zero documents so that categories with no documents associated with them are not listed.
To sort these in proper order, add a hidden column to the left of this column that sorts documents in ascending order with the formula
d :=@Month(@Date); @If(d = 1; "A"; d = 2; "B"; d = 3; "C"; d = 4; "D"; d = 5; "E"; d = 6; "F"; d = 7; "G"; d = 8; "H"; d = 9; "I"; d = 10; "J"; d = 11; "K"; d = 12; "L"; "")
Adding subcategories to an All by Category view In your Furniture Catalog database, you want to add subcategories, indented under the main categories, to make documents easier to find in the All by Category view. Subcategories are indented under main categories automatically in a categorized column. You can have 32 levels of subcategories. The Categories field of the Furniture Description form is an editable choice list field with the following entries:
Bedroom Kitchen Living Room
To add subcategories, rewrite the choice list choices as follows, update existing documents, and refresh the view. A backslash (\) after a main entry denotes the subcategory name.
Bedroom\Beds Bedroom\Dressers Kitchen\Tables Kitchen\Chairs Living Room\Sofas Living Room\Tables
Recategorize the documents that already exist to assign them to one of the subcategories. You can do this manually with Actions - Categorize by typing the full subcategory specification (Bedroom\Beds) into the Categories dialog box. If there are many documents, create agents that set the new values for the Categories field of each document. Press SHIFT+F9 to rebuild the view index so documents display with their new subcategory names.
Easy Easy allows you to create a conditional document selection without knowing a programming language. In the Info List of the Programmers pane, click the Run drop-down box and select Easy. Then click Add Condition for each selection you want to include. To delete a condition, click it and choose Edit - Clear. Formula Formula allows you to create a program for selecting documents. The program uses the @function formula language. In the Programmers pane, click Formula and write the formula in the Script area. Examples: Programming documents to display in a view Selecting documents by form name and field value If a database contains an Action Item form that contains a Status field, a view in the database can select all documents that were created with the Action Item form whose Status field contains the value Open. The document selection formula is:
SELECT Form ="Action Item" & Status="Open"
Selecting only non-response documents To select only documents that were created with main document forms and exclude documents created with response or response-to-response forms, use this formula:
SELECT !@IsResponseDoc
Selecting main and response documents If a database contains a form called Action Item, you can select all documents that were created with the Action Item form, as well as responses to these documents, using the formula:
SELECT Form = "Action Item" | @IsResponseDoc
Selecting documents not created with a specified form The Databases by Title view in the Database Library template selects all documents that were not created with the Librarian form using this formula:
SELECT Form != "Librarian"
By Field
<field name>
Condition
Selection 2 is on is after is before is not on is in the last <n> days is in the next <n> days is older than <n> days is after the next <n> days is between is not between is equal to is greater than is less than is not equal to is between is not between <field values> for multiple fields
Table of document selection conditions Easy conditions The Easy condition determines whether a field contains one value. Because the Easy condition reads any separators you enter as text, it cant look for all the values in a multi-value field. The Easy condition also cant determine whether a particular field is present in a document. You must click Formula and write a formula to do that. Selecting documents by author Documents must have an Authors field for this selection method to work. When selecting By Authors, enter a name or names, separated by commas. If you know a users hierarchical name (such as Mary Sen/Development/ Acme), enter it. If you are not sure of how a name is spelled, use the Public Address Book to browse for person names, but do not select any group names. For more information, see Addressing a message by choosing names from an Address Book in Notes Client Help.
Selecting documents by date The Date created condition selects documents based on the Created date in the Document Properties box. The Date modified condition selects documents based on the Modified date in the Document Properties box. Selecting documents by field value If the field is of type Text, Designer looks for the exact text string you enter. You cant enter (empty quotes) to select documents in which the field is empty. You must click Formula and write a formula to do that. For example, to select documents where the Research field isnt empty, use this formula:
SELECT Research != ""
For example, to select documents that have the field Research, use the formula:
SELECT @IsAvailable(Research)
By form name When selecting By Form as a condition for a selection formula, the condition works only with forms that are part of the database design, not with forms stored in documents. Selecting main and response documents with a formula By default, selection formulas include only documents of the type Main Topic. You can include response documents in a selection formula created with one of the simple functions above by editing the formula Notes creates and appending
| @IsResponseDoc
Simple functions
Simple functions let you add programming without knowing a programming language. The default selection for a new column is # in View, which numbers documents according to their internal sequence (for example, 3.1.2).
Field
Field lets you populate the column with field values without writing a program. This technique works only with text fields because columns need a conversion formula to interpret other types of data that is, dates, rich text, or numbers, or encrypted text.
Formula
Formula lets you create a program for a column using the @function formula language. This is useful when you must process values in a document (such as changing field values to a text value) or calculate a value. Typical uses for formulas include converting field data to a text value (because only text values display in columns), writing a formula that displays an icon instead of a value, and adding text to field values. Click the Field button or the Simple Function button to paste fields, @functions, or @commands into the formula. Always convert information to the data type that your formula expects. For example, to append a numeric value to a text value in a column, use a formula like:
Product + ": " + @Text(Quantity)
Examples: Adding programming to columns Determining text, based on a field value In a column, you can show custom text based on a condition or on a number of conditions. For example, you can create a formula that displays custom text if sales exceed a certain amount. This formula tests the value in the Sales_February field (a number field) and displays text based on that value:
@If(Sales_February>60000;"Great month!";"")
Determining text, based on the form name The Subject column in the All Documents view of the Mail template uses the following formula. It displays a subject line based on the form the document was created with.
@If(Form = "NonDelivery Report"; "DELIVERY FAILURE: " + FailureReason; Form = "Delivery Report"; "DELIVERED: " + Subject; Form = "Return Receipt"; "RECEIVED: " + Subject; Form = "ReturnNonReceipt"; "NOT RECEIVED: " + Subject; Subject)
Combining text and dates You can combine text and field values in a column in a scheduling database to add an explanation about the documents. The formula below displays a text message and a date, with two variations that depend on the value in the Sched field. The D1S0 part of the @Text formula is a formatting option that removes clutter from the view by showing the month and day portion of the date field only and omitting the exact time.
@If(Sched = "Special schedule"; "Special schedule for the week of: " + @Text(Date; "D1S0"); "My regular schedule, as of " + @Text(@Modified; "D1S0"))
Combining text and names The following formula results in three possible results, based on the status of a request: @If(Status=Rejected ;Rejected by + LastApproveName; SignatureCount=0; Original Request ;Approved by + LastApproveName) If the request has been rejected, the column displays Rejected by and the name of the person who last signed the form. If the request has no signatures (meaning that no approver has acted on the request), the column displays Original Request. If the request has been approved, the column displays Approved by and the name of the person who last signed the form. Showing when a document was created The Created column in the By Author view of the Document Library template uses the following formula to display the date on which the document was created:
@Created
Expandable levels (variation on the simple function) The simple function Collapse/Expand (+/-) uses @IsExpandable without any arguments. If you want to display a + (plus symbol) when a document has responses, but suppress a - (minus symbol) when responses are expanded, use the formula:
@IsExpandable("+";"")
Displaying two field values in one column To show peoples names and phone numbers together in one column, create a column that is sorted in ascending order (the recommended order for alphabetical listings). The following formula separates the two field values with a blank space:
Name + " " + Phone
Creating fake indenting When Notes indents response documents, the indentation is always the same. If you want to make a document in a flat view appear indented without using response documents, or display document titles in the same column at different indentations, you can use a field on the form to determine how much each document indents and use a column formula that appends space characters to the document titles in the view. The following formula indents documents in three different ways depending on the value in the Indent field. For example, if the value of the Indent field is 3, Notes prepends 18 space characters to the Subject of the document in the column.
196 Application Development with Domino Designer
@If(Indent = 1; @Repeat(" "; 12) + Subject; Indent = 2; @Repeat(" "; 18) + Subject; @Repeat(" "; 6) + Subject)
Numbering documents In a By Author view, the following formula numbers (as in 1., 2., 3.) each of the documents within each authors category:
@IsCategory("";@DocNumber("") + ". ")
If the row is a category (the authors name), @IsCategory returns a null string (). If the row isnt a category, then the row represents a document, and @DocNumber returns a string that represents the entry number of the document. The documents full entry number is something like 1.1, 1.2, 1.3, and so on, but when used with the null string ( ), @DocNumber returns the rightmost component of the entry number. The formula then adds a period and a space . after the number.
Attachment Names Displays the file name of document attachments. The data type is a text list.
Attachments
Displays the number of files attached to each document. The data type is a number.
continued
Example
Displays the document author name without its fully distinguished format, as in Denise Lee.
Use in a column styled as a Sorted/Categorized column. Returns a + (plus symbol) if the view entry has descendants that are not visible because the main document is collapsed. Returns a (minus symbol) if there are no subordinate documents or if subordinate documents are currently visible. Useful when a view contains a large number of response documents. Displays the time and date a document was created.
Creation Date
Last Modified
Displays the last time and date a document was read or edited.
continued
Example
# in View
Displays a number for each document indicating its order in the view. Responses are numbered in outline style under Main documents for example, the first response to the first main is 1.1. Displays the number of direct descendant (response) documents for a document or next-level subcategories for a category.
# of Responses (1 Level)
# of Responses (All Displays the total number of Levels) descendant (response and response-to-response) documents for a document or subcategories for a category.
An icon column has two requirements: The column property Display values as icons is selected. The column uses a formula that results in a number that corresponds to the icon you want to display. The graphics used in column icons cant be customized, but you can choose from more than a hundred predefined column icons.
Use 0 as the false case when you want to leave the column blank. The formula above returns 0 when the document has no attachments, so nothing is displayed. A column that displays icons cant display anything else, such as a plus (+) sign for an expandable categories column.
column. You cant add your own icons; you must choose from the icons shown below.
User-sorted columns
Users see a triangle next to a column title whose values can be resorted. Users click the column and choose a sorting method to see the documents in the order they choose.
To set up a user-sorted column, select the option Click on column header to sort on the Sorting tab of the Column Properties box. Then select Ascending or Descending order, or select Both to allow users to cycle among ascending sort order, descending sort order, and no sort order for the column.
Auto-sorted columns
To set up a sorting style in advance, select the option Sort: Ascending or Sort: Descending on the Sorting tab of the Column Properties box. The sorting column is usually one that appears on the left side of the view.
Using an auto-sorted column as the secondary sorting column To add a secondary sorting column, add a column to the right of the first sorting column and then choose Sort: Ascending or Sort: Descending on the Sorting tab of the Column Properties box. Documents and responses are sorted, then sub-sorted, in column order from left to right. Designating a secondary sorting column for a user-sorted column User-sorted columns override the sorting built in to auto-sorted primary and secondary columns. If the view has a user-sorted column and you want to include secondary sorting, you can associate it with a secondary sorting column. On the Sorting tab of the Column Properties box for a user-sorted column, click Secondary sort column and choose the secondary sort column and its sorting order.
Case-sensitive and accent-sensitive sorting rules for Release 5 differ from sorting rules in previous releases in the following ways: Both case-sensitive sorting and accent-sensitive sorting are turned off by default (in previous releases, they were on by default). Case-sensitive sorting sorts lowercase letters before uppercase letters for example, ab sorts before Aa. Accent-sensitive sorting sorts accented characters after non-accented characters. For example, ab sorts before a.
You want the By Priority view to sort documents by the value in the Priority field, but you dont want them to appear in ordinary alphabetical order (High, Low, Medium, Urgent). You want users to see Urgent-priority documents at the top of the view, High-priority documents next, and so on. You create a column that: Is hidden Has no title Is one character wide Uses this formula to determine the order of each priority:
@If(Priority="Urgent";"1";Priority="High";"2"; Priority="Medium";"3";"4")
Is sorted in ascending order You add a column to the right of the hidden column that: Is not hidden Has the title Priority Is 10 characters wide
Collapse all when Displays the top-level database is first category in categorized opened views or the main documents in a hierarchical responses view. Users click the category to see individual documents within the category. Row styles Lines per row (1-9)
Determines how many lines Shrink rows to a column can contain. content and Color: Alternate rows are useful accompaniments to multi-line rows. Determines the color for unread documents. Determines the color that alternates with the background color to highlight every other row. Red is used for unread documents in template designs. Useful for multi-line rows. Not applicable to calendar views. continued
Description Shows the document selection margin. Deselect for cleaner-looking rows.
Comments If you deselect Show selection margin, users can still select documents by pressing and holding SHIFT as they click document names. The selection margin appears temporarily while documents are selected, and hides again when all documents are deselected.
Location
Keeps gaps from appearing below rows that are shorter than the number of lines per row you select. Determines how much More space makes each space there is between rows. row easier to read. Less space condenses the view contents to make it useful for reports or Web users. Shows a green triangle (blue Not applicable to triangle on the Web) next to calendar views. a column that displays categories or response documents. Fills out the last column to avoid empty space in the view. Makes view easier to read. continued
Comments (Optional) Select Resizable to allow users to change the width as needed. With the view in Designer, you can also click the column and drag the column divider line to the width you want.
Location
Text style and color: Column title Text style and color: Column values
Determines the font, size, color, and alignment of an individual column title at the top of the view. Determines the font, size, color, and alignment of values that display in this column. The column title and values do not display to users.
Use Apply to All button to change the text style for all titles in the view. Use Apply to All button to change the text style for all columns that display text in the view. Useful for columns used for sorting that contain values users don't need to see. This is not a security feature. Useful for making columns more readable if they contain several values (usually generated by a multi-value field). Beveled--background is gray. Simple--background matches view color.
Hide column
Multi-value separator
For any documents that display multiple values in the column, separates each value with punctuation or a new line.
Show column Shows a bar at the top of the headings view with column titles (Beveled, Simple) with either a beveled or flat look. Lines per heading (1- 5) Color: Column totals
Determines how many lines Useful for long column a column title can wrap. titles or instructions placed in a column title. Determines the color of the total numbers for any columns that contain totals. Calls attention to totals.
Default views
A default view is the view users see when they open the database for the first time. Each database has a default view, which appears with an * (asterisk) in the Views list. The default view typically has unrestricted access and contains all documents in the database, sorted by category, by date, or by author. In the Designer templates, the default view usually includes all documents in chronological order and shows main documents associated with responses or supporting documents. To specify the default view, use the option Default when database is first opened in the Options tab of the View Properties box.
Such a view requires that: Users have access to response forms, whose types are Response and Response-to-Response. Show response documents in a hierarchy is selected in the Options tab of the View Properties box and the document selection formula uses SELECT @All or contains a formula that allows response documents to be included, such as: SELECT Form = Action Item | @IsResponseDoc The view has a responses-only column. Create the responses column directly to the left of the column under which responses are to be indented. Leave its title blank, make its width 1, and select Show responses only in the Column Info tab of the Column Properties box. Write a column formula that displays information about the response documents shown in the column, such as their authors or creation dates.
to show a response this way: Stephanie Mahar added this comment: Great job! (10/10/97 04:43:15 PM)
If the response uses an Exit form, the response row might look like this: Exit Form, mailed to employee 08/26/97 If the response uses a New Hire Information form, the response row might look like this: New Hire Information, not yet mailed
If the document is a main document, the column displays the contents of the Subject field, the author name, and the number of response and response-to-response documents. If there is one response, the column displays response. Otherwise, it displays responses. Main document rows might look like this: Need Help with Trade Show (Indy Montoya, 1 response) Changing the Product Name (Sandy Braun, 2 responses)
View applet
You can display a view or an embedded view as a view applet. Here is a view applet on the Web followed by an embedded view applet on the Web:
What the view applet does for Web applications With the view applet, Web users can: Resize columns with sliding panes Collapse and expand views without the browser regenerating the page Select multiple documents Scroll vertically to view additional documents in the view Use F9 to refresh the view Use DEL to mark documents for deletion from the database
Font support in the view applet The View applet provides limited support for fonts. Since current versions of the Java Developers Kit (prior to JDK 1.2) provide very limited support for text fonts, mapping between the Designer font set and the font set supported by a specific Web browser is constrained by the JDK supported by a browser. This can sometimes produce inconsistent results across different Web browsers. For best results use one of the following font faces: Courier, Helvetica, or Times Roman. Programming the view applet The View applet is programmable through a number of @commands. These are:
@command ViewCollapse ViewExpand ViewCollapseAll ViewExpandAll ViewRefreshFields Description Collapse the selected document Expand the selected document Collapse all documents Expand all documents Refresh view Upon refresh, the view applet does not delete documents marked for deletion. MoveToTrash EmptyTrash Folder RemoveFromFolder Causes currently selected documents to be marked for deletion Delete documents that are marked for delete Moves or copies the selected documents to a folder Removes the selected document from the current folder
Embedding a view or folder pane lets you combine views and folders with other form elements (such as styled text) and graphics to create a highimpact design. 1. Open a form, subform, or page in Designer, or open a document in Edit mode. 2. Place the cursor where you want the embedded view or folder pane to display. 3. Choose one of the following: Create - Embedded Element - View Create - Embedded Element - Folder Pane 4. (Optional, for views) If you dont want to display the same view in all circumstances, click Choose a View based on a formula. When you click OK to close the dialog box, write a formula in the Programmers pane to display the appropriate view. 5. (Optional) Click the embedded element and choose Element - View Properties (or Element - Folder Pane Properties) to change the alignment or style, or to hide the element under certain conditions. 6. Close and save the form, subform, page, or document. To delete an embedded view or folder pane, click the embedded view or folder pane in the Work pane and choose Edit - Clear. A form can have only one embedded view and one embedded folder pane. Domino disregards the view title and background color of embedded views and uses settings on the Server document to determine the number of lines to display. Domino prevents the view opening if there are create or read access lists on a form in which views are embedded. For compatibility with previous releases, the reserved fields $$ViewBody and $$ViewList still work on forms. An embedded view can be set as an embedded view applet.
Displaying the view navigation bar for embedded views In a Web application, Domino doesnt display the default view navigation bar for embedded views. To give Web users access to navigation functions, use these formulas to add view actions for Next, Prev, Expand, Collapse, and Search:
Action name Next Prev Expand Collapse Search Formula @Command([ViewPageDown]) @Command([ViewPageUp]) @Command([ViewExpandAll]) @Command([ViewCollapseAll]) @Command([ViewShowSearchBar])
Note that these commands do not work if the embedded view is set to display as an applet.
Hiding a view
Designer includes several ways to hide a view from users.
Choosing the option None omits unread marks. Users can still navigate to the next unread document by using SmartIcons.
Description Adjust time to local zone displays the time relative to the time zone of the reader. A document created at 3:00 P.M. in New York that is read by a user in Los Angeles adjusts to Pacific Standard Time; the creation time is displayed as 12:00 P.M. Always show time zone displays the time zone where the document was created. With this option, the creator's time zone is always shown. If a document is created in New York at 3:00 P.M., a user in Los Angeles sees the creation time as 3:00 PM EST. A user in New York also sees the creation time as 3:00 PM EST. Show only if zone not local displays the time zone where the document was created only when the document is read by someone in a different time zone. A document created in New York at 3:00 P.M. displays to all users in the U.S. Eastern standard time zone as 3:00 PM. Users in all other time zones see the creation date as 3:00 PM EST.
If the document-selection formula is time-based, refresh the index as often as new documents are added. For example, if the view selects documents once a day, select Auto, at most once every 24 hours, to refresh the view index once daily.
database. (This option doesnt affect local databases.) Choose this option for databases that users infrequently or unpredictably need. Never Permanently preserves the view index and appends updates to the existing index. Because this option takes up more disk space than the other options, use this only for views that users frequently need, so they dont have to wait for a new view index to be created when they open the database. When the view index is deleted The Updall (Update All) server task, which runs by default on each server at 2 AM, deletes the view index. Domino deletes the index the first time Updall runs after the index becomes eligible for deletion. For example, if you select After each use and the view is used at 10 AM Tuesday, the index is not actually discarded until 2 AM Wednesday. If you choose to delete the index after one day, Domino waits until the index is at least one day (24 hours) old before deleting it. If the view is used at 10 AM Tuesday, it is only 16 hours old at 2 AM Wednesday when Updall runs, so it is not deleted until the next time Updall runs at 2 AM Thursday. For more information, see Administering the Domino System.
Designing folders
Folders are containers used to store related documents or groupings of documents. Folders have the same design elements as views. You can design folders in much the same way as views, using the Create - Design Folder command. The difference between folders and views is that views always have a document selection formula that collects and displays documents automatically. A folder remains empty until users or programs add documents to the folder. Note that Web users cannot drag documents into folders. For more information on folders, see Notes Help.
Navigators
Navigators are graphics that include programmed areas that direct uses to specific parts of a database. They let users find documents or take actions without having to open views. If you are designing a navigator for the Web, consider either embedding a navigator or importing a navigator into a form, subform, page, or document. Navigators usually include hotspots; that is, programmed areas that users click to execute an action. A hotspot can be text, graphics, or a combination of both. If you use navigators in an application, you usually want the navigator to display automatically when the application opens. To use a navigator in a Web application, you must select Web browser compatible as a navigator property. With this setting on, Domino converts a navigator to an HTML imagemap. Navigators on the Web always display as full-screen imagemaps. To control the size and display of a navigator on the Web, you can embed a navigator in a form. If your navigator inherits its design from a template, do not make any changes to the design of your navigator, since any changes you make will be over-written by the template.
Navigator objects
You create a navigator by combining navigator objects. Navigator objects include graphic backgrounds, hotspot rectangles, hotspot polygons, hotspot circles, graphic buttons, buttons, text, rectangles, rounded rectangles, ellipses, polygons, and polylines. To create navigator objects, you can import or paste objects from another application or you can use the drawing tools Designer supplies. The drawing tools include hotspot tools that you use to define a clickable area in a navigator.
229
All navigator objects except polylines behave the same on the Web as they do in Notes. Polyline objects display on the Web, but clicking them has no effect.
Navigator actions
You can add actions to all navigator objects except those pasted or imported as graphic backgrounds. Designer provides the following simple actions that you can attach to navigator objects: Open another navigator. Open a view or folder. Serve as an alias for a folder. Clicking the object displays the contents of the designated folder in the view pane. Open a database, view, or document link. Open a URL. To create more complex flexible actions use @function formulas or a LotusScript program. LotusScript programs can perform tasks that arent possible with @function formulas; for example, manipulating a database ACL. For more information on writing formulas and scripts for buttons and hotspots, see the Programming Guide.
Creating a navigator
If you cant copy and paste a navigator that is similar to the one you need, create a new navigator. 1. Open a database in Designer. 2. Select Navigators in the Design pane. 3. Click the New Navigator button above the Work pane. 4. Choose Design - Navigator Properties. 5. Give the navigator a name that describes its use. 6. To use the navigator in a Web application, check Web browser compatible. 7. (Optional) Choose an initial view or folder to open along with the navigator.
8. (Optional) Select Auto adjust panes at runtime so that users wont have to manually resize a navigator that doesnt fit a window. 9. Click the navigator window. 10. Use the Create menu or the SmartIcons bar to draw objects or paste objects from the clipboard. 11. Click each object and choose Design - Object Properties to assign a name and style. 12. In the Programmers pane, select a Run option and assign actions to each object. Run options specify what happens when users click the object. Select Simple action to choose a predefined automation, such as Open a View. Select Formula to define an action using the formula language. Select Script to define an action using LotusScript. 13. Close and save the navigator. Editing a navigator To edit an existing navigator, open the navigator in Designer. Choose Design - Navigator Properties and make changes as needed. To change any object, click on the object, select Design - Object Properties, and make changes as needed.
To delete a navigator object To delete a navigator object (such as a button or a rectangle), select the object and choose Edit - Clear. To remove a graphic, choose Design - Remove Graphic Background. Tips for drawing new navigator objects To create several identical navigator objects quickly, hold the SHIFT key down while choosing Create. Draw all the objects you need; choose Create - <shape name> to exit creation mode. To draw a square or a circle, hold the SHIFT key down while dragging the shape. To move an object that isnt locked into position, drag the object to a new location. To resize an object, click the object, position the cursor on one of the sizing corners, and drag the object to the size you want. To line up objects at a grid mark, choose Design - Navigator Properties, click the Grid tab, and select Snap to grid. Choose a grid size (1 pixel is the most precise). To freeze an object at its current position and size, click the object, choose Design - Object Properties, and select Lock size and position.
8. (Optional) Change the highlight border width, highlight border color, and highlight background color. 9. (Optional) Click the Styles tab and do one of the following to define the unhighlighted style: Select a border width, border color, and background color. For a button, select a button face color, bevel width, and border color. Select Make Default to apply to all new objects of this type. 10. Close and save the navigator. Tip Choose Design - Preview in Notes or Design - Preview in Web browser to enter testing mode and check the highlight settings.
Automating navigators
After you add objects to a navigator, you automate the objects by attaching actions to them. For example, to program a graphic button so that it opens a particular view when a user clicks it, select Run: Simple Actions and then choose Open a view or folder in the Action field of the Programmers pane. Then select a particular view in the Programmers pane.
To attach an action
1. Open the database in Designer. 2. In the Design pane, click Navigators. 3. In the Work pane, double-click the name of the navigator you want to edit. 4. Select a navigator object. 5. In the Programmers pane, click Run: Simple action(s). 6. Select the simple action to run and supply any required information. 7. Close and save the navigator.
To find out more information, users click a bar that represents an areas sales. Each bar in the first navigator is a hotspot rectangle that takes users to the Weekly Details by Country navigator. When users reach the second navigator, they see another bar chart that displays weekly sales by individual country. Clicking a bar in this chart opens the view for the country (for example, View by country\France). Each bar in the second navigator is a hotspot rectangle whose Open a view or folder action specifies the appropriate country view.
Creating a shortcut navigator with an @function formula This shortcut navigator allows users to click the icon instead of using the Create menu to create a new Action Item document.
The action for the icon is Run a formula with the formula:
@Command([Compose];"";"3. Action Item")
Making a navigator object that runs a LotusScript program When users double-click the navigator object (for example, a button), this script opens the current database:
Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Set db = session.CurrentDatabase Call db.Open("", "") Messagebox(db.Title & " " & db.FileName) If db.IsOpen = True Then msg$ = "open" Else msg$ = "closed" Messagebox("Database is " & msg$) End Sub
Hiding navigators
Designer includes several ways to hide a navigator from users. There may be times when you want to present one navigator to Notes users and another to Web browser users. Hiding a navigator from Notes users Open a database in Designer and click Navigators in the Design pane. Highlight a navigator name in the Work pane and choose Design Design Properties. Click the Design tab and select Hide design element from Notes R4.6 or later clients. Hiding a navigator from Web users Open a database in Designer and click Navigators in the Design pane. Highlight a navigator name in the Work pane and choose Design Design Properties. Click the Design tab and select Hide design element from Web clients.
Showing a view only to users of older Notes releases When you have a navigator tailored to users of older Notes releases, open the database in Designer, click Navigators in the Design pane, highlight a navigator name in the Work pane, and choose Design - Design Properties. Click the Design tab and select Do not show this design element in menus of Notes R4 or later clients. The navigator doesnt appear to anyone using Notes Release 4.0 or higher.
$$ Fields
For compatibility with previous releases, the reserved field $$NavigatorBody still works on forms. It duplicates functionality now provided by embedding.
When you import a navigator, navigator simple actions are converted to equivalent hotspots:
Navigator Simple Action Open another Navigator Open a View or Folder Alias a Folder Open a Link Open URL Hotspot equivalent @Command([OpenNavigator];NavigatorName) @Command([OpenView];ViewOrFolderName) @Command([OpenView];FolderName) Resource link of type link Resource link of type URL
Testing navigators
To test a navigator while you design it, switch to testing mode to see a message describing what happens if the simple action, formula, or script runs. For navigators that perform multiple steps or complex tasks, split the process into several small tasks and create an action for each. Test and fix each small task first. When everything is working correctly, combine the formulas into one, and then test the automation again by creating a sample copy of the database and testing all navigator behavior. To test a navigator, follow these steps: 1. Open the database in Designer. 2. In the Design pane, click Navigators. 3. In the Work pane, double-click the navigator you want to open. 4. Choose Design - Preview in Notes or Design - Preview in Web Browser <Web browser>.
242 Application Development with Domino Designer
5. Highlight and click each object to see if the highlighting and actions are as you expected. You can preview in either Notes or a Browser to see how the action actually performs. 6. If the test produces unexpected results, close the previewed item and use the Windows taskbar to return to Designer. 7. Correct the problems and run the test again. 8. When the test shows no problems, close and save the navigator.
Automation
Automation in an application speeds up repetitive tasks, handles workflow, updates information, performs calculations, runs programs, and checks for errors. You can add automated components to most design elements in a Domino application: a database, a page, a frameset, a view, a form, or a document. The automated components include: Actions Use an action with a form or view to set up a user-activated task. You can make the action available in the Actions menu or as a button in the action bar. In particular, use actions to simulate Notes menu items for Web browser users. Then, those users can complete Notes tasks when accessing Domino databases. Hotspots Use a hotspot in a form or document to set up a user-activated task. The hotspot can be a link to another Web site, database, or element in a database; a button; a pop-up; or an action. Agents Use agents to set up user-activated tasks, or background tasks, in any part of a Domino application. Agents can be simple, such as moving documents to a folder, or complex, using Java programs to run multiple automated tasks at scheduled times. Agents are stored with databases, but you can use them to run automated tasks for views, documents, fields, and databases. Programs that are activated by an event Associate an automated task with an event that occurs when a design element is used. For example, set up an error-checking automated task to verify user input after a user has saved a document.
245
To set up the tasks associated with these automated components, use the following: Simple actions You can add automation to design elements without knowing a programming language. You can select one or more simple actions from a list. Simple actions cant be customized and are not supported in Web applications. Formulas You can write an @function formula that runs by itself or with a simple action. You cannot combine an @function formula with a LotusScript program. LotusScript LotusScript is a complete scripting language that can support most application-wide tasks. JavaScript Use JavaScript with agents and events to efficiently interact with the user for tasks such as form and field validation and simulating dialog boxes. Java You can write Java programs or import Java files into agents.
Actions
Create an unshared action in a view or form to provide one-click shortcuts for routine tasks in a view or in a document created with the form. Actions are part of a view or forms design and are not stored with individual documents. You can also create a shared action in a database that can be used in several forms and views. A shared action is stored as a resource with the database. To build an action, you can use any of the following: Simple actions that you select from a list Formulas LotusScript JavaScript
When to use actions Because actions are available in a view or document, use them for any general-purpose task related to a group of documents. For example, use actions: When Web browsers accessing the database need substitutes for Notes menu choices. To present a shortcut as a clickable button. When the automated task is relevant only to a subset of documents. When users need to see all the available choices in a row at the top of a document. When the automated task isnt limited to a particular section of a form. If formulas are complex and you dont want to save the formula with each document. Examples of actions View actions Let users create, print, delete, or categorize documents. Form actions Process an approval; mail a document; or give Web users, who dont have access to Notes menus, a way to click to edit, save, or close documents. Simulate Notes menus for Web users. Automatically send documents to reviewers. Automatically process employee requests. Notes on actions Some views and forms in databases contain built-in actions, available either in the Actions menu, as buttons, or both. You cant change the built-in actions or properties, but you can customize their appearance. Launch Designer and open the view or form. Click Objects and the built-in actions are displayed in the list.
Hotspots
Hotspots are associated with text or an image in the body of a document and can complete any of these types of automated tasks: Link Open a Web site, a database, or an element in a database (a page, view, frameset, form, document, folder, or navigator). Text pop-up Display information in a pop-up.
Chapter 10: Automation in Applications 247
Button Complete a programmed task, using simple actions you select from a list, formulas, LotusScript or JavaScript. Formula pop-up Complete a programmed task using only formulas, with the results displayed in the pop-up. Action hotspot Complete a programmed task, using simple actions you select from a list, formulas, LotusScript, or JavaScript. When to use hotspots Create a hotspot in a document when the hotspot is specific to the document. Create a hotspot in the a form when every document using that form needs the hotspot. Examples of hotspots Use a document or database link to provide a cross-reference for more information that is stored in a document in other database. Use a URL link to cross-reference a Web site for downloading software. Use a text pop-up to provide help information about what values to specify in a field. Use a button to submit a completed document for processing or add a database to a users workspace
Agents
Agents are stand-alone programs that perform a specific task in one or more databases. Agents are the most flexible type of automation because: They can be run by users in the foreground or run automatically in the background as scheduled agents. They arent associated with a specific design element. They can be run on a specific server, on several servers, on workstations, or the Web. They can call other agents. They can consist of simple actions, formulas, LotusScript, or Java programs.
They can be distributed easily because they can be replicated. They can be personal or shared. A personal agent is created and run by the same user. No one else can run a personal agent. A shared agent is created by one user and can be run by other users. Because agents are so flexible and powerful, you might consider their characteristics first to decide the type of agent you want to build, and then build it. The Agent Manager supports all aspects of building, running, and troubleshooting agents. The Agent Manager checks security, manages agent scheduling, monitors events and starts the appropriate agents when their associated events occur, records information in a log (the Agent Log), and performs database operations to run the automated tasks associated with the agent. Although you dont work directly with the Agent Manager, you use its components for building and troubleshooting an agent. When to use agents Use agents for database-wide and domain-wide automated tasks and for complicated automated tasks. You can use them to easily access, process, and manage data on other servers or in other databases. See Agents to run before Web users access Domino for an example. Notes on agents Some databases and templates have built-in agents. For example, the mail template has several built-in agents that let users manage their messages and customize their mail databases. To see the agents in a database, select the database and choose View Agents.
Events
When users work in Domino design elements, Domino tracks their operations as events (for example, opening a database, opening a view, opening a document). You can attach programming tasks to these events. To build a program for an event, you can use: Formulas LotusScript JavaScript
Types of events
Every design element has events that you can program, but they vary according to the design element. In the Programmers pane, click the Objects tab to review the events you can program.
Database events
Database events pinpoint database-wide activities such as opening and closing a database and deleting and undeleting documents. Examples PostOpen open a specific view to direct users to action items QueryDocumentDelete prevent users from deleting a particular document when the value of a status field on an action item is Open PostDocumentDelete archive a deleted document QueryClose prevent users from closing a database when there are still action items in the action item view assigned to them
View events
View events occur when users work in a specific view or folder. View events include opening or closing a view, adding documents to a calendar view, or adding documents to a folder. Examples QueryOpen prevent users from opening a view in certain circumstances such as from opening a month end view before the twentieth day of the month
250 Application Development with Domino Designer
PostOpen create a new document or open an existing one QueryRecalc inform users before a large view refreshes that it could take a while and ask them if they really want to proceed QueryPaste prevent users from pasting documents into the database PostPaste change the value of StartDateTime and EndDateTime in the document when you paste an appointment on a particular day and time slot. QueryClose prevent users from closing a view such as when there are still action items in the action item view assigned to them In addition to the events available for all views, calendar views have specific events. Examples RegionDoubleClick create a new document when users click an area in a calendar view QueryDragDrop prevent someone from dropping an appointment on an inappropriate day or time, such as a weekend day or a time that is after 5 PM PostDragDrop change the value of StartDateTime and EndDateTime in the document after you drop an appointment on a particular day and time slot
Folder events
In addition to the events available for all views, folders also have QueryAddToFolder. You could program the QueryAddToFolder event to prevent someone from dragging a document from one folder to another. For example, you can prevent documents from moving to the Done folder if their status is still Open.
Form events
Form events occur at the document level when users open or close a document. They are useful for speeding up document display times because they execute only when a specific form event occurs, unlike field recalculations that occur each time a document is saved, opened, or refreshed. Examples Initialize load an additional program before a document displays. QueryClose check for errors and validate fields before closing a document.
Chapter 10: Automation in Applications 251
QuerySave reset a field value when users save documents rather than using conditional formulas in the field itself. For example, to reset the status field if the document is being saved, create a script for a QuerySave event rather than include a formula that uses @If(@IsDocBeingSaved;x;y). With QuerySave, you can also execute processing logic and avoid the unnecessary recalculations inherent in computed fields. For example, you have a form with a hidden computed field called State that determines where documents are in the workflow and where they need to be sent. By replacing the field formula with a LotusScript program that sets a field value during the QuerySave form event, set the field value in the document only when it is saved, not when it is opened or refreshed.
Field events
Field events capture users movements into or away from a field. Examples Entering refresh hide-when formulas Exiting guide users to a certain field Exiting verify that users supplied valid information
Click events
The Click event occurs when users click actions or hotspots, or choose tasks from the Actions menu. Other events for actions, buttons, and hotspots allow you to add programming to other events. After the object is loaded, the initialize event is triggered and then the click event is triggered. Examples Compose a new document Save a form Make a calculation
Agent event
The Initialize event stores all the programming associated with the agent. Always add the programming to the Initialize event for an agent.
Other action procedures To copy: select the action in the Action pane and choose Edit - Copy and Edit - Paste. To delete: select the action in the Action pane and choose Edit - Clear. To change properties: select the action in the Objects list and choose Design - Action Properties. To change automation: select the action in the Objects list and edit the programming tasks in the right pane. Actions menu The Actions menu is a context-sensitive list of any actions and agents available for a particular part of an application, as well as some menu commands included with the Notes software. From an open view, Notes users see only those actions associated with the view, plus any manually run agents. From an open document, Notes users see the actions associated with the form used to create the document, plus any manually run agents. Web users dont see the Actions menu. Calling an agent You can use a form or view action to run an agent. Use the @Command([ToolsRunMacro]) or the OpenAgent URL command to call an agent.
Examples: actions
Simulate Notes menus for Web users Web users dont have access to Notes menu choices when they work in Domino databases. Therefore, you should create menu equivalents for them. Create actions with @command formulas and make them available as buttons in the action bar. Keep in mind that Domino cannot translate commands based on a selected document in a view because there is no notion of a selected document on the Web. For actions such as Create Response Document, you must add a form action to the Main Topic form for opening a Response document. To Web-enable all buttons in a database as well as certain @commands, select the database property Web access: Use JavaScript when generating pages. Without this property set, Domino recognizes only the first button in a document and treats it by default as a Submit button that closes and saves the document.
Be aware that Domino displays all buttons, actions, and hotspots even those that contain @commands and @functions that arent supported for Web applications. Complete these steps to create a button to open a new Main Topic in the current database: 1. Launch Designer and open the view where you want to add the button for Web users. 2. Choose Create - Action. 3. Complete the Action Properties box. At the Action Info tab: Enter the name Create Main Topic. Select Include action in button bar. Select Notes graphic and select a graphic for the button. 4. In the Info List, click Objects and click Create Main Topic. 5. In the Run pull-down list, select Formula. 6. Enter this formula:
@Command([Compose];"Main Topic")
7. Save the view. Examples of other commonly used menu items: Create a document
@Command([Compose]; "formname") @Command([Compose];"":"database"; "formname")
Open a view
@Command([OpenView]; "viewname") @Command([OpenView];"":"database"; "viewname") @Command([OpenView];"By Date")
Sending a document to reviewers You want to simplify the process of distributing proposed concert schedules to a review board. 1. In the Concert Schedule form, create a field of type Names that will specify all the reviewers. 2. In the Concert Schedule form, choose Create - Action and specify the following in the properties box: Name Enter Distribute for Review. Display Select Include action in button bar; deselect Include action in Action menu. Button Graphic Select Notes graphic and pick a graphic from the pull-down list. 3. In the Info List, click Objects and select Distribute for Review (Action). 4. In the Run pull-down list, select Simple action(s). 5. Select the Add Action and Send Document actions 6. Save the form. Approving and denying requests You want to improve a Requisition form to make it easy for managers to approve or deny requests that are mailed to them. You create two form actions: Approve Request and Deny Request. The Approve Request action uses this formula to change the documents status to Approved and routes the document to the next approver:
FIELD Status:="Approved"; @MailSend(NextApprover;"";"";"For your review";"Click Approve Request to approve this requisition or click Deny Request to return the request to " + Initiator;"Initiator":"Body";[sign]);
The Deny Request action changes the documents status to Denied and routes a notification to the initiator.
FIELD Status:="Denied"; @MailSend(Initiator;"";"";"Re: Your request";"Your request was unable to be approved. Contact " + PreviousApprover + "for more information.");
Action bar
The action bar is a horizontal button bar that lies below the SmartIcons bar. If there are built-in actions or you created actions to be displayed as buttons, users see the buttons when they open the view or create a document using the form. You can change the color and style of the action bar, and enable the Domino action bar applet for Web users. 1. Launch Designer and choose Design - Action Bar. The Action Bar Properties box opens. 2. At the Action Bar Info tab: Alignment - lets you choose whether to have the action bar align to the left or right. Background - lets you set the background color for all buttons on the action bar. Bottom Border - in the Width field, you can choose: None does not place a divider line under the action bar. Fit to window places a divider line under the whole action bar. Under buttons only displays a divider line that is only as long as the icon display. Set length displays a divider line that is a specific number of inches. You can also set the Color of the border and choose the Style of the border line. Web Access - select whether to use the Domino applet to provide a better action bar to display to Web users. Select Using Java Applet to enable the applet. With the applet, Web users can: Scroll across the action bar, when needed. For actions that have pull-down list selections for Notes client users, the action selections are displayed as a second row of buttons when the user clicks the main action. The second row of buttons are displayed at 75% the size of the main action buttons. Web users can view all the selections and click one to select it. Select Using HTML to disable the applet.
3. At the Button Background tab, you can customize the following properties for all buttons on the action bar: Button Size - sets the height and width in pixels of all the buttons on the action bar and sets the margin size. Button Border - lets you control when the button border displays. You can choose to display the button border On Mouse Over, Always, or Never. Button Background - lets you either select a color for the button background or use an image for the background. To use an image, click the folder icon and select the name of a shared image resource that you have created and stored in the database as a Resource, or click @ and specify a formula (or set of formulas). Note that using an image is not supported on the Web. 4. At the Button Font tab, you can change the font, size, color, and style of the text in the buttons.
Click the folder icon and select the name of a shared image resource that you have created and stored in the database as a Resource. Click @ and specify a formula (or set of formulas). Select the location and position for the action. (Optional) Click the Action Hide When tab to specify when to hide the action. Click the Advanced tab and specify how Notes workflow proceeds after the user activates the action. 6. In the Info List of the Programmers pane, click Objects and select the shared action you just created. 7. Choose one of the following from the Run pull-down list and add the automated tasks: Simple actions Formula LotusScript JavaScript 8. Save the shared action. Insert a shared action 1. Open the form or view where you want to use the shared action. 2. In the Info List, click Objects and select an action, or select an action in the Action pane. 3. Choose Create - Insert Shared Action. 4. In the Insert Shared Action dialog box, select the shared action and click Insert. The shared action is added to the view or form Objects list. The next time you use the form or view, the shared action is available. Editing shared actions To edit a shared action, launch Designer and open the database with the shared action. Click Resources, click Other, and select Actions. To change its properties, double-click the action in the list and the Action property box appears. To change its automated components, click Objects and select it from the list.
Creating a link
1. Launch Designer and open the design element you want to add the link to (a page, view, frameset, form, folder, or navigator) or edit a document. 2. Select text or an image for the link. 3. Choose Create - Hotspot - Link Hotspot. 4. At the Hotspot Info tab of the HotSpot Resources Link Properties box: At the Type field, choose one of the following: Link Link requires that you paste in a link that youve already copied to the Clipboard. Click the Paste icon to paste in the link. The links you can paste in from the Clipboard include: View, Document, Database, or Anchor. Named Element A named element is a design element that you have already created and named. A named element can be a page, form, frameset, view, folder, or navigator. Enter a value (for example, if you already created a page named PAGE1, enter it into the Value field). Alternately, you can click one of the following icons: Formula (@) icon to use a formula that evaluates to a name. Paste icon to paste in a name which you previously copied to the Clipboard. Folder icon to open the Locate Object dialog box and select a design element from a list of elements. URL Enter the full URL specification (for example, http://www.lotus.com). You can also paste in a URL or use a formula that evaluates to a URL. Frame: Specify the frame in which you want the data to display when the user clicks the link hotspot. Select whether to show a border around the hotspot. (Optional) Click the Paragraph Hide When tab to specify when to hide the link. 5. Save the design element or document.
Other link procedures To change properties: click the link and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the link and choose Hotspot Remove Hotspot.
Example: links
For each concert schedule you send out, you want to provide a cross-reference for more information about the performer. Create a link in the document you create for a specific concert and specify a URL with detailed information about the performer. 1. Edit the document announcing the concert. 2. Select text for the link hotspot. 3. Choose Create - Hotspot - Link Hotspot. 4. At the Hotspot Info tab of the Hotspot Resources Link Properties box: Type: Select URL. Value: Specify the Web address; for example, specify http://www.concertseries.org/performers/luke.html 5. Save the document.
Creating a button
1. Open the design element you want to add the button to (a page, view, frameset, form, folder, or navigator) or edit a document. 2. Click where you want to add the button and choose Create - Hotspot Button. 3. At the Button Info tab of the Button properties box: Button Label: Enter a name for the button. Button Width: Specify a value, in inches, for the width. 4. (Optional) At the Paragraph Hide When tab, specify when to hide the button. 5. In the Info List, click Objects and select the button you just created. 6. Choose one of the following from the Run pull-down list to add the automated tasks: Simple actions Formula
LotusScript JavaScript 7. Save the design element or document. Other button procedures To change properties: click the button and choose Button - Button Properties. To change automation: in the Info List, click Objects, select the button in the Objects list and edit the programming tasks in the script area. To delete: click the button and choose Edit - Clear. Call an agent: use the @Command([ToolsRunMacro]) or the OpenAgent URL.
Example: buttons
Using a button to add a database to a users workspace The Human Resources department sends new employees a mail message that welcomes them to the company and gives them orientation information. You decide to add a button to the Welcome form to make it easy for new users to find Benefits information. New employees see the button when they read their Welcome message. Double-clicking the button adds Server1s Benefits Information database to the users workspace (if it isnt already there) and opens it to the View by Category view. The button uses this formula:
@Command([FileOpenDatabase];"Server1":"BENEFITS.NSF";"View by Category")
5. (Optional) At the Paragraph Hide When tab to specify when to hide the pop-up. 6. Save the form or document. Other text pop-up procedures To change properties: click the pop-up and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the pop-up and choose Hotspot - Remove Hotspot.
Select Pop-up on mouse over. Select Show border around hotspot and Use highlight color. 5. Save the form.
5. (Optional) At the Paragraph Hide When tab, specify when to hide the pop-up. 6. In the Info List, click Objects and select the hotspot you just created. 7. Enter its formula 8. Save the form or document. Other formula pop-up procedures To change properties: click the hotspot and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the hotspot and choose Hotspot - Remove Hotspot. To change the formula: click the Hotspot entry in the Objects list and edit the formula in the script area. Other considerations: Use formulas that display information, such as @Time. Do not use formulas that take action, such as @OpenView.
Filling in fields automatically The following script for a field Entering event fills in the FullName field by concatenating the FirstName field, a space, and the LastName field:
Sub Entering(Source As Field) Dim workspace As New NotesUIWorkspace Set doc = workspace.CurrentDocument firstName = doc.FieldGetText("FirstName") lastName = doc.FieldGetText("LastName") fullName = firstName & " " & lastName Call doc.FieldSetText("FullName", fullName) End Sub
Requiring a field to be filled in The following script for a field Exiting event requires users to fill in a LastName field after they fill in the FirstName field:
Sub Exiting Dim W As New NotesUIWorkspace Dim UIDoc As NotesUIDocument Set UIDoc = W.CurrentDocument If (UIDoc.FieldGetText ("LastName") <> "") Then UIDoc.GotoField "FirstName" Else UIDoc.GotoField "LastName" Messagebox "You must enter the person's last name.", 0, "ERROR" End If End Sub
Building an agent
1. Select the database where you want to create the agent. 2. Choose Create - Agent. 3. In the Name field, enter a name for the agent. 4. (Optional) If the agent searches for text in documents, click Options and specify what to search for. 5. Select Shared Agent if this agent will be used by other users. Once you save the agent, you cannot change this setting. If you dont select Shared Agent, the agent will be a personal agent that only you can run. 6. Select how, when, and where to run the agent: Select how to run the agent from the When should this agent run? list. For the On Schedule More Than Once a Day, On Schedule Hourly, On Schedule Daily, On Schedule Weekly, On Schedule Monthly, and If Documents Have Been Created or Modified options, click Schedule to set up when to run the agent. These options are not supported on the Web. For any scheduled agent, select where to run the agent from the Run on pull-down list. Specifying servers is particularly important when agents run on multiple servers and they are changing documents in databases that are replicated.
7. Select the documents in the database the agent will process from the Which document(s) should it act on? list. These options are not supported on the Web: All unread documents in view All documents in view Selected documents Pasted documents 8. (Optional) To further specify the choice of documents, click Add Search. 9. From the Run pull-down list, choose one of the following to define the agents automated components: Simple actions Formula LotusScript Java Imported Java 10. Press ESC to save the agent. Other agent procedures Copy: choose View - Agents, select the agent and choose Edit - Copy. Delete: choose View - Agents, select the agent, and choose Edit - Clear. Select multiple agents: choose View - Agents, click the first agent, CTRL+click the next agent, and so on. Enable/Disable: If you have Designer access or above, you can disable scheduled agents to prevent servers from running them. This is useful for debugging a problem with an agent. Designers can still run disabled agents by choosing View Agents, selecting an agent, and choosing Actions - Run. After you re-enable them, scheduled agents resume their schedule. To disable individual agents: 1. Select the database and choose View - Agents. 2. Select the enabled agent and choose Actions - Disable. The checkmark disappears next to the agent name.
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.
When to use For processing incoming mail: to respond to it, forward it, or file it. Interactive functions and functions that impede the progress of the mail router are ignored when documents are mailed into the database. For example: @DbColumn @DbCommand @DbLookup @MailSend @Prompt @Command @PostedCommand
For workflow tasks where a task is performed based on new or changed documents. For documents that are pasted into the database routinely and they need to be modified as they are being pasted. Paste-activated agents cannot use @Command or @PostedCommand.
On Schedule More Than Once a Day Optionally, set up which server to run on.
For high-priority databases, such as those critical to a business process and for databases that replicate several times a day, such as workflow applications that route documents for approval. Be aware that if you schedule very frequent runs (for example, every 5 minutes), the servers performance could be affected. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.
For high-priority databases as described for On Schedule More Than Once a Day. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web. continued
Run option On Schedule Daily Optionally, set up which server to run on.
When to use For activities that are important but that will not cause a delay if they are only generated once a day. Examples include mailing newswire articles or generating low-priority assignments. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.
For routine tasks. Examples include generating summary reports and sending reminders. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web. For low-priority maintenance tasks. Examples include archiving documents and distributing company newsletters. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.
On Schedule Never
For agents that you do not want to run in particular circumstances. For example, use this run option for agents that do not run on the Web or for agents that are called by other agents.
Specific server name in Run on list Run only on the single server you select from the list of available servers. Choose when agent is enabled Prompt users to select a server when the agent is enabled. This option is useful for distributing agents in ready-to-use applications.
WebQueryOpen events
A WebQueryOpen event runs the agent before Domino converts a document to HTML and sends it to the browser. Domino ignores any output produced by the agent in this context. Examples for using this agent include performing large computations that arent possible with @commands or collecting statistics about who opened documents and when they did so. Note WebQueryOpen agents run when the user opens a form or document, but do not run when the user saves a document. This means that computed fields set by a WebQueryOpen agent are not saved when the user submits a document. To make sure computed fields are saved, you can either recalculate them in the WebQuerySave agent or set the form property Generate HTML for all fields.
WebQuerySave events
A WebQuerySave event runs the agent after field input validation formulas are run and before the document is actually saved to disk or mailed. The agent can modify the document or use the document data to perform other operations. The document is automatically saved after the agent runs. Do NOT have the agent explicitly save the document (for example, by calling NotesDocument.Save) because an explicit save could cause incorrect results. A WebQuerySave agent can product output to be sent back to the user. For example in a LotusScript agent, you can use the Print command to return raw HTML. If the agent produces output, then the form should not have a $$Return field because Domino will return only the agent output and ignore the field.
Examples for using this agent include: Performing complex field validation. If the document does not pass validation, you can prevent Domino from saving the document by adding a SaveOptions field with a value of 0 to the form. Simulating CGI programs that run on user-supplied data by programming a WebQuerySave event and adding a SaveOptions field with a value of 0 to the form. When the agent runs, you can collect field values from the filled-out form without generating a new Notes document. Collecting statistics based on data submitted by browsers, such as CGI variables, by writing a program that uses CGI variables and attaching it to a WebQuerySave event.
Local or server An agent runs locally when: It runs on a database stored on a workstation. It runs on a database stored on a local server. You specified Local in the Run on list for a scheduled agent. User starts it from the Actions menu, agent list, or the When documents Have Been Pasted trigger. When an agent runs locally, Domino does not check security restrictions, unless you have set the Enforce Local ACL option. An agent runs on the server when it is running in a database stored on a server and it is started by one of the following: Before new mail arrives After new mail arrives If documents have been created or updated On schedule more than once a day On schedule daily On schedule weekly On schedule monthly If the agent is running on a server, Domino checks all security restrictions. Foreground or background An agent runs in the foreground when a user starts it from the Actions menu or selects it from the Agents list. When running in the foreground, Domino does not check security restrictions. An agent runs in the background when it is scheduled or it is triggered by an event (for example, when documents are modified). When running in the background, Domino checks security restrictions. From the Notes client or the Web When a user runs an agent from the Notes client, the agent runs with the rights of the agent creator. Complete these steps to find out who the creator is: 1. Select the agent in the agent list and choose Agent - Agent Properties. 2. Click the Fields tab. 3. Select the $UpdatedBy field and check the user name in the right pane. When a Web user runs an agent, the agent runs using the rights of the agents creator and Domino checks the creators rights to access the database. However, you can set up the agent so that Domino checks the
276 Application Development with Domino Designer
invokers rights to access the database instead of the creators rights. Checking the invokers rights can provide more security. Complete these steps to specify that Domino verify the invokers access to the database: 4. Select the agent in the agent list and choose Agent - Agent Properties. 5. Click the Design tab 6. Select Run Agent as Web user. After selecting Run Agent as Web user, Domino prompts a Web user for their name and password when they attempt to run the agent. Domino uses the login information to check for the invokers rights in the database ACL.
Troubleshooting agents
You can experience problems running agents at several points during agent development, deployment, and implementation. There are several tools to help diagnose the problems in each stage. Simulate an agent run: for all types of agents Before running an agent on a live database, test it by simulating a run. The test also diagnoses whether the agent will run by checking security and schedule settings. Agent Log: for all types of agents The Agent Log displays information about when the agent last ran and whether it ran successfully. Notes server console: for all types of agents There are 3 server console commands available to display information about agent scheduling, status of agent queues and control parameters, and status of agent debugging settings that are in effect.
Chapter 10: Automation in Applications 277
Agent Manager debug information: for all types of agents You can specify that the Agent Manager record debug information about any combination of the following: control parameters, events, loading reports, memory warnings, performance statistics, execution reports, and scheduling. LotusScript debugger: for agents built with LotusScript that run in the foreground Choose File - Tools - Debug LotusScript and run the agent. The LotusScript debugger appears and you can run any debugging command in the agent as you would for any LotusScript program. NotesLog classes: for agents built with LotusScript or Java that run in the background The NotesLog class is added to your agent code and can capture information you want to track. The NotesLog class records the information in the Agent Log.
1. Choose File - Database - New Copy to make a test copy of the database, with documents. For all agents except those that act on mailed documents, the test copy can be local. If the agent works on mailed documents, the test database must be on a server, and a Mail-in Database document must exist in the Address Book. 2. Create test documents: If the agent works on mailed documents, mail a few documents to the test database. If the agent works on pasted documents, paste a few documents into the test database. 3. Run the agent. 4. Use the other debugging tools to catch errors and make corrections. 5. Re-run the agent until it is working correctly. 6. Copy the tested agent to the live database.
Agent Log
Every time an agent runs, it writes a report with the following information: When it ran The number of documents it processed The actions it took on the documents Each new run of the agent writes over the previous log report. Domino stores the Agent Log with the database. To view the most recent Agent Log: 1. Select the database and choose View - Agents. 2. Select the agent whose log you want to check and choose Agent - Log. 3. Review the information in the Log. If you are running agents built with LotusScript or Java and the agents run in the background, you can add the NotesLog class to your agent code to record run-time information in the Agent Log.
Use this command to see if the agent is scheduled to run. If it doesnt appear in the list when it should, then you know to check its schedule. This command does not list agents that are manually run from the Actions menu or Agents list.
tell amgr status
Use this command to see where your agent is running (that is, in which queue) and what parameters are in effect.
tell amgr debug
Use this command to display and change the debugger settings. These settings apply to the Agent Manager debugger that you enable in the NOTES.INI file. Tell amgr schedule Tell amgr schedule lists each agent that is scheduled to run on the current day. It lists only agents that run in the background. Check the list for the following information to make sure the agent is scheduled correctly.
Display First column: ESV Description The Agent Manager queue that the agent current is in. E: Eligible to run S: Scheduled to run V: Waiting to run What to check for If the agent is scheduled, make sure it is listed with an E or S. If it is listed, check that the correct time is listed. If the agent is not listed, check the When should this agent run setting. If the agent runs when new mail arrives or a document is created or updated, it should be listed with a V. If it isnt listed, check the When should this agent run setting. Second column: The event that activates the agent. If the agent has an incorrect SMU event or isnt listed when its S: Daily, weekly, monthly, or supposed to be, it means that more than once a day schedule you selected an incorrect M: New mail has arrived When should this agent run U: One or more documents have setting. been created or updated continued
Description If the agent is scheduled to run daily, weekly, monthly or more than once a day, the time of day the agent will run is listed. If the agent is scheduled to run daily, weekly, monthly, or more than once a day and the time it is supposed to run hasnt gone by, then Today is listed. The agent name that is scheduled to run.
What to check for Check and make sure the agent is listed.
Today
Agent Name
Database Name The name of the database that the agent works in.
Tell amgr status Tell amgr status lists the number of agents in queues and other run-time statistics. Even though agent names are not listed, you can check the queue information to determine if the queues are processing the number of agents you would expect. You can also check the run-time statistics to how the Agent Manager is set up. For example, Agent Manager status information includes: The number of agents in queues waiting for events, such as New Mail and Document Update The number of agents in queues waiting for a scheduled time to elapse, such as the Scheduled Task queue The time period, such as Daytime or Weekend The maximum amount of time that a LotusScript/Java agent is allowed to run Tell amgr debug Tell amgr debug lists the Agent Manager debugger settings you specified with the Debug_AMgr statement in NOTES.INI. Use this command to make sure the debugger settings are correct and to change them using the same options that are available for the Debug_AMgr statement, except *. For example, to add options for the Agent Manager that you have already set up to display agent debugging information (-e option):
tell amgr debug -e, -l, -m, -p
where option can be one or more of the following: c list agent control parameters e list Agent Manager event information l (lowercase L) list agent loading information m list agent memory warnings p list agent performance statistics r list agent run-time reports s list Agent Manager scheduling information v (verbose) list more information about agent loading, scheduling, and queues * list all of the information for all options After you specify Debug_AMgr in NOTES.INI and you run an agent on a server, check the Notes console and Notes Log for the debugging information. Optionally, you can redirect the debug information to be
recorded in a separate file on the server. When you redirect the debugging information to a separate file, performance can be affected. To redirect information, edit notes.ini and add the following statement:
DEBUG_OUTFILE=<file-name>
If you run an agent on a database stored on your local workstation, you must redirect the output because the Notes console is only on the server. Log_AgentManager To specify that the Agent Manager record less debugging information than with Debug_AMgr, edit NOTES.INI and add the following statement:
Log_AgentManager=option
where option can be one of the following (but not more than one): 0 do not list debugging information 1 list partial and complete information about successful agent runs 2 list complete information about successful agent runs
NotesLog Class
Use the NotesLog class in LotusScript and in Java agents that run in the background. Add the NotesLog class to your agent code to record run-time information. It is particularly helpful for capturing variable values, error handling, and verifying code logic. By default, the NotesLog class records information to the Agent Log. When you set up items you want recorded, make sure you dont exceed the Agent Log limit. To use NotesLog, follow this LotusScript example that tracks the documents an agent is processing by capturing the documents Subject. The information is recorded in the Agent Log.
Dim agentLog As new NotesLog("Agent log") Call agentLog.OpenAgentLog Set s=New NotesSession Set db = s.CurrentDatabase Set collection = db.UnprocessedDocuments Set note = collection.GetFirstDocument count = collection.Count Do While (count >0) Subject = note.Subject Call agentLog.LogAction("Processing:"+Subject(0)) Set note = collection.GetNextDocument(note) count = count-1 Loop Call agentLog.Close
Agent Log limit The Agent Log can hold only 64KB of information. When the information written to it exceeds this limit, the following message is displayed and the agent stops running: Error executing agent <agent-name> in <database-name>. Memory allocation request exceeded 65,000 bytes. Make sure that the information you want recorded to the Agent Log does not exceed this limit. If it does, rework the NotesLog class code to record less information per run.
AgentRunner
AgentRunner is a Java application program for debugging Domino agents in a Java IDE. There are two versions of AgentRunner for different package classes: lotus.domino.AgentRunner for lotus.domino (Notes/Domino, Release 5.0) lotus.notes.AgentRunner for lotus.notes (Notes/Domino Release 4.6.x) Also included is a set of debug classes that access Notes context information while running in a Java IDE. To use AgentRunner: 1. Create agent code to extend DebugAgentBase. 2. Run the agent to generate an AgentContext document in the AGENTRUNNER.NSF. 3. Run AgentRunner that runs your agent code outside Notes. The AgentRunner code accesses the AgentContext document to make the program behave as though it were running as an agent. This allows you to build and run without having to switch between the IDE and Notes, and to use IDE run-time tools such as the debugger. Create a project for your agent In Java IDE: 1. Add the fully-qualified file specification for NOTES.JAR (for example, for JDK or Cafe) to your Java IDEs CLASSPATH or Import (for example, for VisualAge) the JAR file to your project. 2. Create an agent (see the Domino Designer Programming Guide) that extends DebugAgentBase, instead of AgentBase. Note To select the correct version of DebugAgentBase:
For Notes, Release 4.6-style agents use the import lotus.notes.*; format. (Recommended) For Notes, Release 5 use import lotus.domino.*; 3. Build the project as an application. It does not matter if the agent has a main() method, but if your IDE requires one, add a dummy one. Notes will not use it. 4. If required (for example, for VisualAge), export the .CLASS files. Generate an AgentContext document In Notes: 1. Build a Java agent in a Notes database and import the .CLASS files from your project. Ensure that the base class is the class that extends DebugAgentBase. 2. Run the agent to generate an AgentContext document in AGENTRUNNER.NSF. Note When the agent runs in Notes, a call to getSession() from an agent class that extends DebugAgentBase returns NULL after generating an AgentContext document. Therefore, any use of the returned session results in a thrown exception. Because the purpose of running the agent is only to generate the context document (and not to run any of the agent code), you can ignore the exception. 3. Open AGENTRUNNER.NSF and examine the most recent AgentContext document. Note the name of the server, the file path of the database, and the name of the agent. Local is the name of the server for a local database. 4. Edit the AgentContext document and change the Agent Runs On and Search Criteria fields to generate the UnprocessedDocuments collection that you would like to use for debugging. You must supply this information because it cannot be determined from running the agent. Note the Agent Runs On and Search Criteria that you specified in the agent that you ran to generate this document will produce the Selected document list. 5. Save and close the document. You can generate another AgentContext document later if you want to change the run-time environment. You can edit fields other than Agent Runs On and Search Criteria to change the run-time environment, but it is not recommended.
Run AgentRunner to debug your agent In Java IDE: 1. Specify <Agent> [<Database> [<Server>]] arguments, as displayed in the AgentContexts view of AGENTRUNNER.NSF, to the AgentRunner program to select the AgentContext document that you want to use for debugging your agent code. If running from a command line, enter:
java lotus.domino.AgentRunner <Agent> [<Database> [<Server>]]
To run an agent that uses the lotus.notes package (from Notes, Release 4.6.x) from a command line, enter:
java lotus.notes.AgentRunner <Agent> [<Database> [<Server>]]
2. Set a breakpoint on the first executable line of code in the NotesMain() method of your agent. 3. Build the project. 4. Run or debug the project. If you are debugging and no breakpoints are set, you should step into NotesMain() to access your code. 5. In certain IDEs (like Symantecs Visual Cafe), you cant specify that a projects main() entrypoint be in a class in the JAR or ZIP file. For these IDEs, you must create a dummy main application with the only purpose to call the main() method in AgentRunner. For example:
import lotus.domino.*; public class Main { public static void main (String[] args) { try { AgentRunner.main(args); } catch (Exception e) { e.printStackTrace(); } } }
Mark Document Unread Marks selected documents as unread. Use this action for flagging a document that users want to read again. Modify Field Replaces or appends a single field value with a new text value you specify. This action replaces only text values for documents in Edit mode. To replace a value with something other than text, use an @function formula or LotusScript program. This action can modify the value of a hidden field, if you can specify the fields name. The Append Value option does not work for rich text, number, or time fields or for fields that are not available within documents already saved in the database. Also, Append Value is not available if a database does not contain any documents (for example, a database template). To include Append Value in databases without documents: 1. Create a placeholder document containing the field. 2. Create the agent using the field from the placeholder document. 3. Delete the document. Optionally, you can use a formula instead of a simple action. To specify a value: 4. Select the field to be modified from the Field pull-down list. 5. In the Value text box, enter the new value. 6. Select Replace value or Append value. Modify Fields by Form Replaces several field values on a form with new text values you specify. This action replaces only text values. To replace a value with something other than text, use an @function formula or LotusScript program. This action marks processed documents as read. To specify: 1. Select the form. 2. Enter the new value in the fields.
Move to Folder Moves the highlighted document in a view or folder to a different folder. This action removes the document from the source folder and adds it to the specified folder. The document is not deleted from the database. Remove from Folder Removes selected documents from a folder you specify but does not delete the documents from the database. If a document is included in several folders, this action removes the document from the specified folder, but does not remove the document from other folders. If a document is included in only one folder, this action removes the document from the folder and changes its category to Uncategorized. Reply to Sender Sends a reply to a mail memo automatically. Replies are not sent to a mail memo that was generated by an agent. The Body field accepts only plain text. It does not accept styled text, graphics, or attachments To specify: 1. Select Reply to sender only or Reply to all. 2. In the Body field, enter the reply text. 3. (Optional) Click Include copy of document to append the original message to your reply. 4. Select Reply only once per person if a person is included in multiple mailing groups. Run Agent Allows you to chain agents together with other agents or combine LotusScript programs, @function formulas, and Java in one agent. The agent to be run must already exist in the database. The documents that additional agents process are determined by the first agent. All subsequent agents use the same documents, regardless of their own settings. The first agent completes its search and actions first and then passes that information to the second agent. For example, Agent A searches for all documents with the word green, replaces green with yellow, and then runs Agent B. Agent B launches its own search queries and actions only on the documents that Agent A processed.
Send Document Mails the current document to the recipients designated in the documents SendTo field. This action works like the @MailSend function. To predict the recipient, the document must have a SendTo field. If it doesnt, Notes uses the contents of the internal $UpdatedBy field as the recipient. If the document also contains the CopyTo or BlindCopyTo fields, it is routed to those recipients at the same time. If the document contains the DeliveryPriority, DeliveryReport, or ReturnReceipt fields, they control the delivery priority, generation of a delivery report, and generation of a return receipt. If the document doesnt contain these fields, they default to normal priority, no delivery report, and no return receipt, respectively. Send Mail Message Mails the selected document as a whole document or as a link. The Body field accepts only plain text. It does not accept styled text, graphics, or attachments. To specify: 1. Specify recipients in the To field. 2. (Optional) Click More to specify more addresses using text or formulas for the To:, cc:, bcc:, and Subject: fields. 3. Enter a subject. 4. In the Body field, enter the message text. 5. (Optional) Click Include copy of document to append the document to the message. 6. Select Reply only once per person if a person is included in multiple mailing groups. Send Newsletter Summary Searches a database for documents matching conditions you specify, then sends a summary document with links to the individual documents. The summary information includes items such as a one-line description of the Date, Author, and Title columns. The Gather at least option does not apply to sending a document summary from a view or folder with an action because the action can act on only the highlighted document, and Gather at least acts on multiple documents.
To specify: 1. Specify recipients in the To field. 2. (Optional) Click More to specify more addresses using text or formulas for the To:, cc:, bcc:, and Subject: fields. 3. Enter a subject. 4. In the Body field, enter the message text. 5. Select Include summary for each document using view to send a text summary of each document. Deselect it to send only document links. 6. Choose a view. @Function Formula Adds a customized @function formula.
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 an action, a button, a manually-run agent, or a WebQuerySave event that uses @Command([ToolsRunMacro]). If it is attached to a manually-run agent, it must also be a shared agent. It cannot be attached to a WebQueryOpen event.
Note Your ability to use the LotusScript NotesDatabase Create and CreateReplica methods is controlled by the "Create New Databases" and "Create Replica Databases" fields in the Server document in the Domino Directory.
then any formula involving the following features is disabled: @Command @PostedCommand @DbCommand, @DbColumn, @DbLookup (only if it refers to a non-Notes database) @MailSend Dynamic Data Exchange (DDE) including all @DDE functions Object Linking and Embedding (OLE) Launching attached files The user doesnt see a message, but the formula wont run.
Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer
onClick Works in
Notes browser
Notes browser
Notes browser
Notes browser
Notes browser
Netscape, Notes Netscape, Netscape, Netscape, Netscape, Internet client, Internet Internet Internet Internet Explorer Netscape, Explorer Explorer Explorer Explorer Internet Explorer Notes Notes browser, browser Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client
Doesnt work in
Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape continued
JavaScript Object
Button
Action Hotspot
Form Action
View Action
Internet Internet Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Internet Internet Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client continued
JavaScript Object
Button
Action Hotspot
Form Action
View Action
Internet Netscape, Internet Internet Internet Internet Explorer Internet Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape
Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client
Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client
Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client
Create the Java program 1. After you select Java from the Run pull-down list, Designer sets up: Base Class file with the name of the agent and the .java extension. A Classes list with the required NotesMain() method. Stub code for the Base Class and the NotesMain() method in the right-hand pane of the Programmers pane. 2. Complete the code in the NotesMain() method. 3. Click New Class to add classes. 4. Click Edit Project to associate Java files with the Base Class. 5. (Optional) Click Export to store the Java file independently of the agent on your computer. 6. Save the agent.
Naming tips
Choose short names for form and view actions that you design to appear as action bar buttons. Choices on the Actions menu appear in alphabetical order. To force names to appear in a different order, number or letter them. Use consistent names across databases to enable users to recognize identical agents and actions.
Naming techniques
Alias names An alias is an internal name for an agent. Using an alias, you can change or translate the name that users see without disabling formulas that reference the original name. Aliases follow the same naming rules as regular names. Alias names dont work with form and view actions.
To create an alias name, add the alias name and a | (vertical bar) symbol to the left of the original name. Always keep the original name as the rightmost name.
Archive Documents | Agent1
Shortcut keys A shortcut key is an underlined letter in a choice on the Actions menu. Windows, OS/2, and UNIX users type only the shortcut letter to select the menu item. To specify a shortcut, type an underscore before the letter you want to assign as the shortcut. For example, S is the shortcut for this Save action:
_Save
Notes ignores the underline when it displays the name of an action on the action bar. Cascading names If you dont want to overwhelm users with long lists or if you have related actions or agents that should be grouped together, group them so that related menu choices appear under one main menu choice. You can create only one level of cascading names. Enter the name you want to appear on the Actions menu followed by a \ (backslash), followed by the action or agent name. For example:
Mail Tools\Add Sender to Address Book Mail Tools\Choose Letterhead
Actions that also display in the action bar show only the name after the backslash. The Calendar Profile agent in the Combined Mail (4.6) template contains a name that has a shortcut key, a cascading name, and an alias:
_Calendar Tools\Calendar Profile . . . | Calendar Profile
303
A Java applet usually consists of a collection of files, with one file that contains the main class, or the starting point for the applet. There can also be image files, archive files, and Java source files. You can store Java applet files as follows: When you import an applet, the files are attached as hidden files to the form, document, or page where you include the Java applet. When you link to an applet, files are stored on the Web and a URL reference to those files is stored in the form, document, or page where you include the Java applet. When you set up shared applet resources, the files are stored in the database where you include the Java applets that use those files.
Importing an applet
Before you import a Java applet, you must enable Java applets on your workstation and make sure all the related files are available on your workstation. 1. Launch Designer and open a page or form, or click in the rich text field of a document. 2. Choose Create - Java Applet. 3. In the Create Java Applet dialog box: Select Import an applet from the file system or use an applet resource. In Base Directory, enter the path for the applet files. In Base Class Name, enter the name of the main class. To avoid typing the path and class name, click the folder icon to browse for the main class file for the applet. Clicking the main class file inserts the class and the path in the correct fields. 4. Click Locate to see all related files for the applet. 5. Select the related applet files and click Add/Replace File. If you are inserting an applet that is packaged as a .JAR file, select the .JAR file, and click Add/Replace File to include the .JAR file. 6. Click OK twice. 7. (Optional) Set applet parameters, attributes, and properties.
For example, the main class name for the following Java applet is ArcTest.class.
<applet code=ArcTest.class width=400 height=400></applet>
For most applets, you must select all class and resource files. Select the source files only if you plan to send the applet to another user who wants to export them and change the applet. If you are inserting an applet that is packaged as a .JAR file, you can enter the path and the main class name as described above. Note that browsing for the .JAR file inserts the filename with a .CLASS extension in the Class Name field. In some cases, the file name and the main class name are the same; in other cases, they are different and you must edit what appears in the Class Name field to be the correct main class name. If you have more than one applet in a form, document, or page, Notes stores only one copy of common files.
For the URL, specify the name of the URL where the applet resides, not the document that references the applet. For example, use
http://java.sun.com:80/applets/Bubbles
instead of
http://java.sun.com:80/applets/Bubbles/index.html
6. Enter the corresponding value in the Parameter Value window. For example, enter black for the example HTML tag in Step 5.
To set all applet parameters 1. Use any text editor or Web browser and open the HTML file associated with the Java applet. 2. In the HTML file, select all of the parameters and copy them to the Clipboard. For example, copy all of the following text:
<param name=bgcolor value="black"> <param name=fgcolor1 value="red"> <param name=fgcolor2 value="magenta">
3. Select the Java applet and if the Programmers pane is not displayed, choose Java Applet - Java Applet Parameters. 4. Click Applet Parameters. 5. Click Paste to add the parameters and their values. Details To change a parameter value, click its name. Then change its value in the Parameter value window. The parameter value is a formula; therefore, you must enclose text values in double quotes. In addition to text strings, a parameter value can be an @function or a field name. If you are running an applet through a browser, you can add JavaScript to a form or document to interact with the applet by calling its public methods or setting/getting its public properties.
Alternate HTML are attributes usually used by browsers that do not support Java. Domino uses the Alternate HTML attributes to generate HTML code that is placed in the <applet> tag. To set Alternate HTML attributes, use the Programmers pane and click Alternate HTML. Properties specify how the applet appears in the page, form, or document where you have imported or linked it. You can also use Java applet properties to hide the applet under specific conditions. To set properties, use the Java Applet Properties box.
Use the Text to display when applet is not running property in the Java tab of the Java Applets Properties box to specify text that a browser displays when it supports Java but cannot display the Java applet.
Setting properties
Use the Java Applet Properties box to set some applet properties (for example, height, width, and display) and application properties (for example, alignment and whether to hide the applet). 1. Select the Java applet and choose Java Applet - Java Applet Properties. 2. Edit the properties. For example, enter the following in the Text to display when applet is not running field:
This Java Applet is not currently available.
Java applet properties The properties you can set for a Java Applet include the following: Base class The name of the main class file. DocBase Provided for information only. You cannot edit it. CodeBase CodeBase is the path storing the class files, relative to the base class file. If you linked to an applet on the Web, the URL of the directory containing the applet is displayed, and you can edit the URL name. Otherwise, the field is provided for information only. Size The Height and Width fields set the height and width of the applet display area in the Domino application where the applet is running. If the applet is too large to run in the default size, you must reset these settings, using the height and width settings from the HTML file. To determine the applet size, use any text editor or Web browser to view the HTML file. Check the width and height values specified in the <applet> tag. Enter these values in the Width and Height fields. You can also specify a size for the applet as a percentage of its parent window. Text to display when applet is not running Domino displays the text you specify when it cant run the applet. Enter a simple text string, such as This applet is not working at this time. Applet uses Notes CORBA classes Select this to let Web users access the applet. If you dont select this setting and a Web user tries to run the applet, an error is generated.
Applet uses CORBA SSL security If you select Applet uses Notes CORBA classes, this setting becomes available. Folder tab If you import an applet, the folder tab displays all applet files. Otherwise, the page is blank. Hiding an applet under certain conditions You can hide an applet so it appears only under certain conditions in the form or page. Click Paragraph Hide When tab in the Java Applet Properties box and choose one of the following options: Hide paragraph from You can hide the applet according to how a user is accessing it: from Notes or from a Web browser. Hide paragraph when document is You can hide the applet according to how the document is being used. For example, you might hide the applet when the document is open for editing. Hide paragraph if formula is true You can customize the conditions for hiding the applet by writing a hide-when formula that specifies the criteria for hiding the applet. If you want to hide an applet based on the browser accessing it, complete these steps: 1. Create a field named HTTP_USER_AGENT in the form where you imported or linked the applet, or in the form used by the document where you imported or linked the applet. 2. For the field type, select Text and Computed for display. Optionally, you can hide the field. 3. Enter the following formula for its value:
HTTP_USER_AGENT
When a user accesses a document that uses this form, the Web server fills in the field with a string describing the browser type and version. The format of the string differs according to the browser. Some examples:
Mozilla/3.0Gold (WinNT; I) Mozilla/2.0 (compatible; MSIE 3.02; Update a; Windows 95)
4. In the Java Applet Properties box, enter a formula that uses this field to hide the applet for a particular browser. Use the @contains(HTTP_USER_AGENT; string) formula. For example, use the following formula to hide the applet from Internet Explorer:
@Contains(HTTP_USER_AGENT; "MSIE")
6. Select Shared Resources in the Browse list and select the shared resources that this applet uses. Click Add/Replace File. 7. Click OK twice.
When a user runs the applet, Domino checks for execution rights of the person or group that signed the applet. If an applet is signed by a person or group without the correct authorization, Domino alerts the user of the illegal operation. The user can stop the operation and not run the applet, trust the signer of the applet one time, or automatically add the signer to the execution control list.
3. If you want the applet to load data as soon as it has completed initialization, click Add and set up the following parameter: In the Parameter Name field, enter ReadExternalData and click OK. In the Parameter value window, enter the value for ReadExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
4. If you want the applet to load data at some other point after initialization, click Add and set up the following parameter: In the Parameter Name field, enter ExternalData and click OK. In the Parameter value window, enter the value for ExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
Notes appends the value with the entire URL of the data file. 5. If you want the applet to save data at the end of the session, click Add and set up the following parameter: In the Parameter Name field, enter SaveExternalData and click OK. In the Parameter value window, enter the value for SaveExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example,
mydata
If the file attachment does not exist, Notes creates it and stores the data in it. Example HTML code to set up parameters:
<PARAM NAME="readexternaldata" VALUE="mydata"> <PARAM NAME="writeexternaldata" VALUE="mydata">
Serialization There are two parameters available to direct Notes to save and reuse serialized data: Object The applet uses this parameter, a standard HTML parameter, to load (using Java VM and VM) previously saved applet data in the serialized object. Object must exist before the applet attempts to load it, or the operation fails. WriteObject After a Notes save event, the applet uses this parameter, a Notes extension, to save the data. The data is saved as a serialized object in a hidden attachment to the document. The user cannot see the attachment. 1. Select the Java applet and choose Java Applet - Java Applet Parameters. 2. Click Applet Parameters in the Programmers pane, and then click Add. 3. To load the previously saved data, enter the following in the Parameter Name field and click OK:
Object
4. In the Parameter value window, enter the value for Object. Its value is the name of a file that contains the previously saved state information from the WriteObject parameter. This file is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
5. To save the applet data, click Add, enter the following in the Parameter Name field, and click OK:
WriteObject
6. In the Parameter value window, enter the value for WriteObject. Its value is the name of the file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
Details Although you can set up an applet for both externalization and serialization, Notes cannot support both. An error is not reported, but one applet cannot do both. In the Java applet itself, you must write methods to support the Java Externalize interface. If the applet does not have these methods, you can still run the applet. However, the data cannot be saved, even if you set up the parameters. If you save data, keep these points in mind: If the applet is imported in a subform, the data from the subform has precedence over the data in the form. Therefore, modifying an applet in a subform modifies all of the forms that include that subform. Data from an applet contained in a document takes precedence over the data stored in a form or subform. If you imported the applet in a document and you are saving data, the data file will be copied if you export the applet. If you imported the applet in a form, the data file will not be copied if you export the applet from a document you created with the form.
Check that you entered the correct name for the applet files. Java is case-sensitive, so the file names must match exactly. Make sure you correctly specify the parameters required by the applet. Choose File - Tools - Show Debug Java Console and view the messages reported by the Java applet. Check for missing parameters and add in parameters that are required.
The drawbacks of specifying a full URL for an applet resource file are that it may be slow to access this file through the Internet and not all Notes clients are set up to directly access the Internet. Also, this course of action assumes that the location of this file will not change. If these are not concerns, this is a reliable way to access resource files. Using getDocumentBase The least reliable means of specifying resource files is the getDocumentBase method. The getDocumentBase method of specifying resource files returns the base URL (that is, the full document URL minus the document file name) of the document in which the applet is located. For example, if an applet is running in a document at:
http://www.someplace.com/test/example.html
Some applets use this method to specify a URL for resource files, for example, getImage(getDocumentBase(), image.gif). Using the above URL as an example, the applet would be looking for the image file at the URL
http://www.someplace.com/test/image.gif
Note, however, that the Domino URL for a document does not simply refer to a file; instead, it is a command for the Domino server to generate the HTML representing a document. If you use the getDocumentBase method as a Domino URL, you get unexpected results. For example, suppose you linked an applet with the following Domino URL:
http://www.someplace.com/database.nsf/MasterView/862..12E?Open Document
In this case, using the getDocumentBase method in conjunction with the getImage call returns:
http://www.someplace.com/database.nsf/MasterView/image.gif
The applet cannot find the file because the document ID is gone and the image is an attachment to a document, requiring a $File qualifier as part of its name. Because the documents ID has been removed (and since the image is in an attachment in the document and thus needs $FILE to qualify the file name), the requested image cannot be found by the applet.
Using getCodeBase The most reliable means of specifying a resource file for an applet is the getCodeBase method. The getCodeBase method returns the base URL from which the applet was loaded. The codebase for an applet can be specified by the CODEBASE attribute in the APPLET tag. When Domino generates the HTML for an applet which has been inserted into a Notes document, it generates a full URL for the CODEBASE attribute. For example, given the example above, the getCodeBase method returns:
http://www.someplace.com/database.nsf/MasterView/ 862..12E/$FILE
When used in conjunction with resource calls, such as getImage calls, getCodeBase correctly specifies the resource file. For example:
getImage(getCodeBase(), "image.gif")
This results in a URL that allows the applet to successfully find the file. Modifying parameter values to locate resource files Some applets include parameters that refer to resource files or to directories containing resource files. For example, an applet may include a parameter specifying a file for use as a background image or a directory for audio files. You may need to edit the applet so that these parameters are relative to the codebase, rather than to the document base. If you are not building the applet yourself, for example, if you are linking to an applet on the Internet, or if you obtained a set of .class files without the source code, you might need to edit a parameter value after inserting the applet into a form or document. In that case, prepend the string $notes_codebase to the parameter value. For example, instead of using images/image.gif, use $notes_codebase/images/image.gif as the parameter value. Domino converts any occurrences of the $notes_codebase string in a parameter into the codebase for the applet. The parameter value $notes_codebase/images/image.gif is therefore converted by Domino to:
http://www.someplace.com/database.nsf/MasterView/ 862..12E/$FILE/images/image.gif
Since this effectively means that you are providing a full URL when specifying the parameter value, the getDocumentBase method in the applet is overridden, and the applet will be able to find the resource file.
Add custom controls to a form If you use Notes with Windows NT or Windows 95/98 and have OLE custom controls installed, you can create custom control objects in documents or on forms. An OLE custom control, also known as OCX or as ActiveX, is a small, self-contained software module with its own data. Lotus ComponentsTM, which are examples of controls, allow you to use other Lotus products, such as a Lotus spreadsheet or chart, while continuing to work in a Notes database. For information on creating and using the Lotus Components, see the online Help that comes with the Lotus Components software or go to the Lotus Web site at http://www.lotus.com. Your organization may create OLE custom controls from various manufacturers and use the controls in Notes. Some OLE custom controls may not provide online Help for their application. Set up forms to exchange field information with other Notes documents You can create forms in Designer that automatically share information with documents created in other OLE-registered applications. Then, when users modify the contents of a field in a Notes document, the changes are automatically made to the corresponding fields in the other applications document. Data exchange can occur in both directions: users can edit fields in Notes or the other application, and the modifications are automatically exchanged. OLE-registered applications must support NotesFX in order to use field exchange in Notes. This feature is not available for Web applications. Publish an action This is the most powerful of the OLE-based tools because it is the most flexible. You can automate complicated or repetitive tasks that involve multiple operations across multiple applications. You design an action using formulas or scripts, and then publish it. The action appears on the Action menu in any Notes/FX 2.0-enabled application. This feature is not available for Web applications. Embed JavaBeans JavaBeans are self-contained objects, similar to ActiveX controls, that can be used with other beans to create applications. Like ActiveX controls, you can embed JavaBeans into Notes documents and rich text fields, forms, subforms, and pages, and then attach scripts and events to them. You must install the Java Runtime Environment (JRE) before you can embed JavaBeans in a Notes document or in a Designer form.
4. If you are using in-place edit, click outside the OLE application to return the focus to Designer. If Designer originally opened the application, exit the application. 5. Save and close the form. For more information on creating objects, see Notes Client Help. OLE and LotusScript To build on the power of OLE, use LotusScript to create or enhance workflow applications. You can use LotusScript to create, manage, and update objects within Notes documents. For more information on using LotusScript with OLE objects, see the Programming Guide.
Use the Applet menu choice to: Copy and cut the entire object. Use the Edit menu to copy and cut selected text in the object. Access Notes properties for the control, including the name of the control. Access the controls own properties. Set the controls mode. Freeze and unfreeze the controls events. If a control is active when you embed it in a form, a list of events appears in the Info List of the Programmers pane. You can attach scripts to these events. For information on attaching scripts to a custom control, see the Programming Guide.
When you design a form that autolaunches an embedded object, the object must be the first OLE object in the form. To autolaunch other objects embedded in the form, you must write a script. Users can launch embedded objects manually, except in documents that open as modal dialog boxes. If you create an object in a rich text field on a form, when users create a document, the object launches. If you dont create the object in a rich text field, when users create a document, Notes launches the first object that appears in the form. When users subsequently open the document for reading or editing, the first object in the document launches. The following are ways to launch OLE objects: Launch an object automatically The object can be a spreadsheet, a word-processing document, a graphic presentation, a database, or a multimedia object. You can autolaunch objects created in any registered OLE application. Launch a new object automatically A new object is blank until users add data. You can autolaunch a new object in any registered OLE application. Launch an object in-place or out-of-place The object launches in-place if it launches within the Notes document. The object launches out-of-place if it launches in the application that created it. Define the conditions under which objects are launched The object launches only when it is created or when it is opened in Read or Edit mode. Use the form open in a modal dialog box to create documents The object launches into a modal dialog box that the designer can customize to allow specific actions users can take with the object. Hide the Notes document You can hide the Notes document when the object is launched or when the launched object is closed. Hide the original embedded object in documents You can hide the original embedded object and display only the most recent, updated version of the object in a document.
Nested objects If the OLE server application is also a client application, an object in a Notes document may have other objects within it. In this case, when an object is updated, the object in the Notes document reflects the changes even if they were made in an other application. When an object that contains other objects is autolaunched, only the application that created the object embedded in the Notes document is launched. Examples: Designing a form that launches an object automatically You need a Spring product line database that sales representatives use to create custom presentations from a standard set of slides. Create a Sales Presentation form and embed a Freelance Presentation file containing the standard slide presentation. Specify the Freelance Presentation object to autolaunch only when a document containing it is created. When you use the Sales Presentation form to create a document, Freelance Graphics launches and you save the object without modifying it. Then use the name Standard Presentation to save the Notes document. You now have a document stored in the database and accessible by sales representatives all over the world, containing standard slides for a sales presentation. Sales representatives who want to modify the presentation use the Sales Presentation form to create a new document. The Freelance Graphics object launches automatically, and the sales representatives can customize the slide presentation. They then save the object, and specify a new name when they save the Notes document containing it. Their custom version of the slide presentation is now in the database, where other sales representatives can access it.
7. Select Rich Text in the Type box. 8. In the Form Properties box, click the Launch tab. 9. Select the name of the rich text field in the Create object in field box. 10. Close and save the form. When a document autolaunches a new object, the application initially displays an empty object. The user adds the appropriate data, and then closes and saves the object. The new object is embedded in the rich text field you specify in the Create object in field box. To display the object in the first rich text field in the document, you specify First Rich Text Field. Then when a user reads or edits the document, the object in the first rich text field launches automatically. If the document was opened in edit mode, this allows the user to enter data or make changes. Nested objects If the OLE server application is also a client application, an object in a Notes document may have other objects within it. In this case, when an object is updated, the object in the Notes document reflects the changes even if they were made in another application. When an object that contains other objects is autolaunched, only the application that created the object embedded in the Notes document is launched.
You can design a form to hide the Notes document during any of these activities: Users create a document (Opening Create). Users open a document to edit it (Opening Edit). Users open a document to read it (Opening Read). Users close a document after creating it (Closing Create). This option is available only if Opening Create is selected. Users close a document after editing it (Closing Edit). This option is available only if Opening Edit is selected. Users close a document after reading it (Closing Read). This option is available only if Opening Read is selected. Mixing Hide/Show options You can design a form that hides the Notes document in some circumstances and shows it in others. Use this type of form when document creators, editors, and readers play different roles in maintaining the information in the Notes database. Hide Notes documents when: The main focus of the document is the object, and users dont need to fill in anything else. The form contains only one object. Users arent familiar with Notes and want to work in a familiar application. The Notes database is functioning solely as a container system for other application files. All users have access to and can launch the other application and always work in that application. Show Notes documents when: Readers need to see more than the data object itself. The form contains multiple objects. Revising the data in the object is optional; therefore, you dont need to launch every time the Notes document opens. Users who create and edit documents need to fill in other fields on the form. Some users have operating systems, such as OS/2, that dont support OLE objects, but they still need to read the information or edit other fields in the Notes document.
Examples You create a report-tracking database that allows users to use 1-2-3 to create and update their own expense reports. When users create or update expense reports, they dont need to see the Notes document; instead, they want to autolaunch the expense report object in 1-2-3. To design a form that mirrors your users workflow, create an Expense Report form, embed a worksheet object in the form, and set the form properties to automatically launch the worksheet. In the Hide when box, you select Opening Create, Closing Create, Opening Edit, and Closing Edit. When users choose Create - Expense Report, Notes automatically starts 1-2-3 and launches the embedded worksheet object. Users enter information directly into the 1-2-3 worksheet object and never see the Notes document. When users complete the expense reports and quit 1-2-3, the worksheet object embedded in the form updates, users are returned to the view level in Notes. If users want to edit their expense reports, they open the document in edit mode, and 1-2-3 autolaunches. When they close 1-2-3, users are returned to the view level of Notes. Information from the expense report worksheet appears in the Notes document or in the Notes view. The Notes database contains all of the expense reports.
Publishing actions
When you publish an action, you make it available on the Action menu in any open OLE server application. For example, you might automate a document review process so that a Notes user opens a document that autolaunches a Word Pro file. After editing the file, the user clicks the Send to Next Reviewer menu choice in Word Pro, which routes the document containing the Word Pro document to the next user. By publishing actions, you seamlessly coordinate tasks between applications. From a designers point of view, publishing actions expands the scope of what you can do with a flow of work and enhances your ability to control that flow. Teamed with autolaunching, publishing actions allows you to focus or limit user-access to commands, thereby controlling the flow of work. By simplifying and automating multi-step tasks, you improve the security of your system and reduce the chance of user error. Actions allow you to integrate file creation and storage in other desktop products with the document sharing, storage, security, and management tools of Notes. Actions can incorporate functions, @commands, and LotusScript. Notes also supplies a number of simple actions, such as Move to Folder, which allow you to incorporate useful actions in your form design without programming in LotusScript. For information on actions, see Overview of Automation.
Examples A Word Pro document needs to be routed for approval. The Notes form you create has an embedded Word Pro document set to autolaunch when edited and an action called Send to Next Reviewer. When a user opens the Notes document in Edit mode, the Word Pro document automatically launches. When reviewing the Word Pro document, the user selects the Send to Next Reviewer action from the Action menu in Word Pro. This action sends the Notes document to the next reviewer and closes the object. To provide other routing options, you can add the actions Ready for Next Reviewer, Return to Previous Reviewer, and Archive Document to the Notes form.
Two-way fields These fields provide information for exchange in two directions that is, from Notes to the OLE application and from the OLE application to Notes. When you change the contents of the field in either application, both fields update. Fields defined as two-way exist by default in many OLE server application files; therefore you create corresponding fields in your Notes form. For example, the Document Description field in a Word Pro document corresponds to the Subject field in a Notes document. After you set up field exchange, changes to one field automatically appear in the other field. The fields must have the same name. User-defined fields These fields exchange data in two directions, but you must create these pairs of fields, since they do not exist by default in the OLE server application file. User-defined fields usually exchange working data, such as text or numbers. You create and name these fields in the OLE server application file and in the Notes form. For more information about fields in OLE server applications that exchange data with Notes, see the documentation for the OLE server application.
Setting up field exchange 1. Open the other application file. 2. Write down the name of each field you want to exchange and close the application. 3. In Designer, open the form you want to prepare for Notes/FX field exchange. 4. Embed the object containing the fields you want to exchange. 5. Choose Create - Field. 6. Give the field the same name as the corresponding field in the other application. 7. Close and save the form. Examples: Exchanging data The following table lists one-way and two-way fields found in most Lotus applications. For a complete list, see the documentation for the application.
Field name LastRevisionDate NumberOfEdits EditingTime SizeInPages SizeInK DocumentClass Subject Categories Data type Time Number Number Number Number Text Text Text (allow multi-values) Contents Date and time the file was last revised Total number of revisions to a file Total time the file was open Number of pages in the file Size of the embedded object in kilobytes OLE class name of the application embedded in Notes Description of the document Keywords that Notes uses to categorize documents
Exchanging data for an expense form You create a form to file and distribute trip reports. The reports contain descriptions of the important business aspects of the trip, as well as the total expenses. You record expenses in a Lotus 1-2-3 expense report template. You want the total expenses of the trip to appear automatically in the Notes document.
In the 1-2-3 template, create an expense report. In one cell enter Total_Exp. Now create a range name for this cell and name it Total_Exp. Because this is a custom Notes/FX field, you need to tell 1-2-3 to use this range name for Notes/FX. Select File - Workbook Properties and then select the Notes/FX Fields tab. Select the New Field button and then select the range name Total_Exp. Select OK twice. The row below the cell entitled Total_Exp will hold the actual data that is exchanged between Notes and 1-2-3. Save and close this 1-2-3 Workbook. In Designer, create a form called Trip Report and embed the recently created 1-2-3 expense report. The Trip Report form contains text fields for entering information about the trip. At the bottom of the form, use the text The total expenses for the trip were: to label a field area and create a numeric field named Total_Exp which corresponds with the name of the field in the 1-2-3 expense report template.
When users use the form Trip Report to create reports, the total expenses are automatically inserted in the document.
Security in an application
Designer offers a multi-layered approach to security. You can secure fields, sections, forms, views, databases, servers, and domains. Securing servers and controlling access to a domain is the responsibility of the server administrator. As a database designer, you can control who has access to an application you create, right down to the contents of a single field. You can also control access to application-specific features, such as the database design and agents that run on a database. The features you use determine how secure your application is. The database access control list and encryption features provide true security. Creating form access lists and hiding design elements let you hinder access but are not true security features. To restrict or limit access to parts of a database, use these features: The database access control list (ACL) specifies who can or cannot access the database. For users who can access a database, access levels and roles determine the specific actions they can perform for example, creating or deleting documents. Note that, if the Web user is being authenticated with Basic authentication (that is, name and password), the Advanced section of the ACL lets you specify a maximum access setting for Web users. Even if you explicitly give Web users higher access, they never have an access level greater than what you specify as the Maximum Internet name & password access.
347
If the Web user is being authenticated using SSL Client certificates, then the Maximum Internet name & password access field does NOT apply to them. These users have the full access granted to them in the ACL. In other words, if the access list says that they have Manager access, they truly have Manager access to the database and not the access specified in the Maximum Internet name & password access field. The Secure Sockets Layer (SSL) is a security protocol that protects data by encrypting it as it passes between servers and Web clients. The SSL must be set up at the server as well as set for a database. Form access lists, in conjunction with the database ACL, control who can read or edit all documents created from a form. Document access fields (Readers and Authors fields), in conjunction with the database ACL, control who can read or modify specific documents. Encryption allows you to secure information for Notes clients at the field level. You can encrypt the contents of any field so that only readers who have the encryption key can access the message or field. Database managers can encrypt an entire database. Encryption is not supported in Web applications. Electronic signatures confirm that documents or document sections mailed from one user to another are not tampered with before reaching their destination. To restrict access to parts of the design, use these features: Restrict who can create agents and where the agents can run. Most users can create private agents to run on local databases; some users can also create shared agents that run on servers for use by other users. Secure the design of a database to prevent users from changing design elements. For information on restricting agents, see the topic Agents. For information on securing a database using the access control list, see Managing Domino Databases. For information on setting up the SSL, see Administering the Domino System.
8. Click the left column next to each designers name to select it, and click Add. 9. Click OK when you have added all the designers. 10. For each designers name in the People, Servers, Groups list, highlight the name, select Designer as the Access level, and select all Create and Delete options. 11. To remove an entry, highlight the name and click Remove. 12. To change an entrys access level, highlight the name and select a new access level. 13. Click OK. To preview in the Web browser, you need to set up an Anonymous user with Author access and make sure that create documents is selected. For more information on restricting access using the ACL, see Controlling and monitoring access to databases in Managing Domino Databases.
Depending on which of these types of access the server allows for the SSL port and what the database ACL allows, the user may access this database anonymously, may be authenticated with name and password authentication, or may use a Client certificate. For more information, see Administering the Domino System.
To create a read access list 1. Open the view or folder. 2. Choose Design - View Properties or Design - Folder Properties. 3. Click the Security tab. 4. Deselect All readers and above. 5. Click each user, group, server, or access role you want to include. A checkmark appears next to each selected name. 6. Click the Person icon to add person or group names from a Personal Address Book or from the Domino Directory. 7. To remove a name from the list, click the name again to remove the checkmark. 8. Check Available to Public Access Users if you want this view or folder available to users with public access read or write privileges in the access control list for this database. 9. Save the view or folder. Do not create a read access list for the default view of a database. Servers that need to replicate a database need access to views that are read-restricted so that view design changes can replicate. Example: Restricting access to a view To improve his Technical Services departments reputation, Rajeev Jain has designed a Tech Services Review form, which is included in the companys custom Mail template. Each quarter, Rajeev sends a company-wide memo asking people to complete a Tech Services Review form and mail it to a Service Request Tracking database. In that database, the reviews are displayed in the Tech Service Performance view. Rajeev wants only his technicians and his own managers to have access to this view. He defines a read access list for the Tech Service Performance view. Then, since there is no group in the Domino Directory for the people he wants to include in the access list, Rajeev defines an access role in the database ACL called [TS Managers], and adds that role to the views read access list. The access role is stored within the Service Request Tracking database; it does not get added to the Domino Directory. For more information on restricting access to a database, see Controlling and monitoring access to databases in Managing Domino Databases.
Restricting access in this way is not a true security measure because a user might create a copy of the form and remove the restriction, but it is a useful tool for limiting easy access. For example, you might use a form access list to restrict access to documents containing personnel information. In addition to restricting who can read or edit documents created from a form, you might want to restrict actions users can take with documents. For example, you might want to allow users to view a company phone list, but prevent them from printing, copying, or forwarding the list. Restricting access to a form Using a form access list, you restrict access to all or part of a form by setting security parameters that work with the database ACL. The database ACL predominates only users with access to the database have access to forms within a database. Form security is a lower level of access control than is the database access control list. You can create form access lists that specify who can create, edit, print, forward, or copy information. Limiting who can create documents from a form also shortens the Create menu by removing restricted forms from the menu. Authorized readers The following people can read a document that has restricted read access: Users assigned read access in the form access list Users listed in the forms Readers field Readers field names are added to a documents read access list. Users listed in the forms Authors field Creating fields for Readers and Authors is described later in this chapter. Replicating restricted documents Adding names to a read access list or to a Readers field limits access to the users, groups, and servers named in that list or field. Servers that need to replicate this database must be included in the list or field to have read access. Otherwise, documents that are read-restricted wont replicate.
6. Deselect All readers and above in the Default read access for documents created with this form section. 7. Click each user, group, server, and access role you want to include. 8. (Optional) Check Disable printing/forwarding/copying to clipboard if you want to disable these features. 9. (Optional) Check Available to Public Access users if you want documents in this view or folder available to users with public access read or write privileges in the access control list for this database.
Any users who have Editor (or higher) access to the database can edit a document if: They are listed in the forms read access list, Readers field, or Authors field. The form has no read access list restrictions, no Readers field, and no Authors field. For information on updating Readers fields, see Updating Reader and Author fields in Managing Domino Databases.
1. Open the form. 2. Create a field, or click an existing field. Then choose Design - Field Properties. 3. At the Field Info tab, select Readers or Authors as the type. Select Editable to allow authors and editors to modify the list (Be sure to include yourself in the default value formulas which you create in the Script area of the Programmers pane so there is at least one value). Select Computed to write a formula that computes the reader or author names. 4. To create editable or computed field values, click the Programmers pane, select a formula type, and write the formula; click the green check mark to save the formula. Note Include server names in the formula if the database will replicate. 5. On the Control tab, select a Choices option other than None to generate a list of readers or authors from which users can select. 6. (Optional) On the Field Info tab, select Allow multi-values to allow more than one name to be stored in the field. 7. (Optional) On the Control tab, select Allow values not in list to let users enter additional names. This property is applicable only to Address and Access Control List choices. 8. Close and save the form. To ensure that the database will replicate correctly, include the names of replicating servers in the reader names list. Choices for generating a list of readers or authors Unless None is selected as the lookup option for a Readers or Authors field, users either press CTRL+ENTER or, if specified for the field, the entry helper button to see a list of possible entries. If the Readers field is located inside a layout region, leave None selected; other lookup options do not apply. On the Control tab of the Field Properties box, choose one of these options for generating a readers or authors list: None If you select None, you rely on a formula or on authors to create the list of names. Select Look up names as each character is entered to speed up typing in editable fields. Designer fills in the first name that matches the characters the user types.
Use Address dialog for choices This option displays the Names dialog box so users can select names from a Personal Address Book or from the Domino Directory. Select Look up names as each character is entered to help users fill in a name quickly and Designer looks up a match. Use access control list for choices This option brings up a list of people, servers, groups, and roles in the access control list. Use View dialog for choices This option brings up a dialog box containing entries from a column in a Designer database view. Select the database to look up, select a view, and select a column number. Writing formulas for Readers and Authors fields When you write a formula for a Readers or Authors field, enclose user names and group names in quotation marks.
Marketing"
Select Allow multi-values for a field that stores a text list with multiple names. Concatenate the names in the formula with a colon.
"Mary Sen":"Marketing":"Joyce O'Connor"
Role names that qualify access levels are surrounded by quotation marks and square brackets.
"[Scheduling Committee]"
Examples: Restricting who can read or edit specific documents Adding a Readers field to a form You want to be sure that employees can read only their own Employee Information documents. Create a computed-when-composed Readers field named AuthorizedReader that uses this formula:
@UserName
To add additional authorized readers, create a read access list in the Document Properties box for individual documents.
Adding an Authors field to a form You want to use an Authors field on a Slide Show form to let the Production group edit documents, but you also want to save and display the original authors name for each document, so the creators name is easily found even after the document is edited. You create two fields. To display the creators name, create a computed-when-composed field called CreatedBy with the formula:
@Name([CN];@UserName)
To allow the Production group to edit Slide Show documents, create a computed Authors field and use the formula:
"Production"
Allowing authors to add other names You want to let authors and editors customize the Authors list. Create an editable Authors field that uses View access control list dialog to present choices, and select Allow multi-values for the field.
Creating pages, forms, outlines, views, and agents for public access
A public access list, like Readers and Authors fields, works with the database access control list to control users access to specific design elements. Users with No Access or Depositor access in the ACL cannot access the design elements of a database. To give them the ability to view specific pages, documents, forms, outlines, views, and folders make the design element available to pubic access users. Users who have at least Reader access in the database ACL will see in the elements properties box that the element has been designated as available for public access. To create public documents, you must create a public access form with a $PublicAccess field and create a public folder or view to display the documents. Public documents are useful for calendar applications where one user might delegate to another user the ability to read or create appointments on his or her behalf. Creating agents enabled for public access gives users with No Access or Depositor the ability to view and use any manually run agents. For more information on the ACL, see Controlling and monitoring access to databases in Managing Domino Databases. To create a page or form for public access 1. Open the page or form. 2. Choose Design - <design element> Properties. 3. Click the Security tab. 4. Select Available to Public Access Users. 5. On a form, create a field. 6. In the Name field, enter $PublicAccess. 7. In the Type field, select Text and Computed when composed.
360 Application Development with Domino Designer
8. In the Programmers pane at the bottom of the form, enter 1 as the default value for the field. Click the green check mark to accept the value. 9. To hide this field from users, select the Hide When tab and specify hide-when conditions. To create a view for public access 1. Open the view. 2. Choose Design - View Properties. 3. Click the Security tab. 4. Check Available to public access users if you want documents in this view or folder available to users with public access read or write privileges in the access control list for this database. To create an outline for public access 1. Open the outline 2. Choose Design - Outline Properties. 3. Check Available to public access users. To create an agent for Public Access 1. Open the agent in Designer. 2. Click Options. 3. Select Available to Public Access Users.
Encrypting documents
To use encryption in a document, you create fields that are capable of being encrypted and then you or users encrypt the fields with one or more encryption keys. To encrypt a document, perform some or all of these steps: 1. (Optional) Create an encryption key to use secret encryption. To do this, see the topic Creating a secret encryption key. 2. Enable encryption for a field. A document cannot be encrypted unless it contains at least one field that has been designated as encryptable. 3. Choose a method for assigning encryption keys to documents: Encrypt all documents automatically Create a field that generates a list of encryption keys Allow authors to encrypt documents with their own encryption keys A document can be encrypted when it is first saved, or it can be encrypted when saved after a subsequent editing session. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases. Example: how decrypting a document works Mary encrypts a document using the encryption key in her User ID to encrypt field data. David opens the encrypted document to read it. Designer compares the list of encryption keys used to encrypt the document with the encryption keys in Davids User ID. If David doesnt have any of the same keys, the encrypted fields appear to be blank. If David has some of the keys used to encrypt the document, that encryption key is used to decrypt the document. Examples: Making fields for encrypting documents For an Employee Information database, the Salary History form has a create access list that allows only members of the Financials group to create Salary History documents. The database managers want to allow only four people in the Financials group to see salary information and to edit Salary History documents. The database manager can create an encryption key and distribute it to the select group or identify the four people and encrypt the information using their public encryption keys.
In the first instance, the database manager creates an encryption key called Salary and sends it to the four people in the Financials group, and to the database designer. The database designer enables encryption for the CurrentSalary field and associates the Salary encryption key with the form. This allows the four people in the Financials group who have the Salary encryption key to create, read, and edit encrypted salary history documents, including the data in the CurrentSalary field. In the second case, the manager provides the names of the four people to the database designer, who chooses their names from the Public Encryption key list associated with the CurrentSalary field. Then the people from named in the list can create, read, and edit encrypted salary history documents, including the data in the CurrentSalary field. Users who dont have the Salary encryption key and are not in the Public Key list can read everything in the salary history documents, except the data in the CurrentSalary field, but they cant edit and save existing encrypted documents.
When you design a form, you can use the public key for encryption or create a new encryption key. If you create a new encryption key, Designer automatically stores it in your User ID. If someone sends you an encryption key, Designer stores the new key in your User ID, along with any other keys. North American and International encryption keys Designer uses two schemes for creating encryption keys. One scheme is for North American (United States and Canada) use only, and the other is for use anywhere in the world. If you are designing a database for users in the United States and Canada and in other countries, create domestic and international versions of the encryption key. If a document is encrypted with a North American encryption key, people using Designer outside of the United States and Canada cannot decrypt the document because they cant add a North American encryption key to their international IDs. Because of legal restrictions, you cannot mail an encryption key with the North American encryption scheme outside the United States and Canada. When American and Canadian users receive keys encrypted with the international scheme, they cannot change the key to the North American encryption scheme. Enabling encryption for a field You can enable encryption of a field whenever the document containing the field is saved. Forms can contain more than one encryption-enabled field. 1. Open the form. 2. Create a field or click an existing field. Then choose Design - Field Properties. The field can be any data type. 3. Click the Advanced tab. 4. Select Security options: Enable encryption for this field.
To encrypt all documents created with a form, you enable encryption for one or more of the forms fields (in the Field Properties box) and assign one or more existing encryption keys to the form (in the Form Properties box). If you use secret rather than public encryption keys, the database manager is in charge of distributing the encryption keys to all users who need them. Whenever someone saves a new document composed with that form, all the encryptable fields in that document are encrypted using the key(s) you assigned, unless the author or editor changes the encryption keys associated with the document or disables encryption. Documents created before you add the encryption keys remain unencrypted; however, you can manually encrypt them. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases.
If the SecretEncryptionKeys field is empty (null), the document is not encrypted. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases. Examples: Creating a field that generates a list of encryption keys Editable choice list field that lists one key This example gives users two choices. If the user selects Encrypt, the document is encrypted with the ConfidentialKey encryption key. If the user selects Dont encrypt (represented by a null value ), the document is not encrypted.
Encrypt | ConfidentialKey Don't encrypt | ""
Editable choice list field that lists multiple keys A choice list formula lets users choose the encryption key that is appropriate for the document.
Encrypt for Financials group | FinancialsKey Encrypt for Managers group | ManagersKey Encrypt for Human Resources group | HRKey Don't encrypt | ""
Editable text field You can create a SecretEncryptionKeys field that is an editable text field with a default value formula that designates a commonly used key. Users can remove the value to skip encryption or change the value to use another key.
"ConfidentialKey"
Computed text field This formula encrypts documents with the ConfidentialKey encryption key if the Status field contains the word Confidential:
@If(Status="Confidential";"ConfidentialKey";"");
Allowing the author to choose the encryption key If you dont have access to the encryption key or you want authors to choose from the encryption keys they possess, enable encryption for the fields, but do not associate any encryption keys with the form. Then when users save a document created with the form, they choose whether to encrypt the document when saving it (in the Document Properties box) and choose which encryption key to use.
5. Select one of the Computed types to use a formula to define the section editors. 6. (Optional for an editable field; Required for a computed field) In the Properties box, write a formula to define who can edit the field and click the green check mark. To collapse an access-controlled section 1. Click the section marker and choose Section - Section Properties. 2. Click the Expand/Collapse tab and select options for showing the section expanded or collapsed, depending on whether a document is being previewed, printed, or opened. 3. On the same tab, click the For Editors drop-down list and select For Non-editors. A list of options appears for displaying the section to users who can read but not edit the section. 4. Select Hide title when expanded if users dont need to see the section title when the fields are displayed. 5. Close and save the form. Examples: Restricting access to a section Computing an editors list from the access control list The status section of a Business Card Request form has an access-controlled section whose formula allows only administrators (an access role in the access control list) to change the status of a request. The formula for the computed field is:
"[Business Card Administrators]"
Allowing the author to name section editors An editable section of a Status Report form has an access-controlled section whose default value formula always allows the author to edit the status report.
"@UserName"
The author can choose Section - Define Editors to name additional editors for a particular status report.
For documents with several sign-enabled, access-controlled sections, Designer stores signatures within each section, so it is possible to maintain multiple signatures for a document. If a user with editor access changes one or more sign-enabled sections, Designer replaces all original section signatures with the newer signature when resaving the document. Designer preserves the existing signatures for sections for which the user has no access. If there are several sign-enabled fields within a section, data from all the sign-enabled fields in that section is used to generate a signature. A change in any fields in the document after saving causes verification to fail when a reader opens the document.
Completing an application
As you prepare to deploy an application, consider these finishing touches: Creating an icon for the application. Creating database help using the standard About this Database and Using this Database pages, or with a designated home page that describes the application or site. You may also want to: Provide context-sensitive help for an application Provide customized SmartIcons sets for a Notes application, to give users one-click buttons for frequent tasks Then, before handing over the application to the database manager: Test the design Make a master design copy to manage future design changes For more information on putting a database into production, see Managing Domino Databases.
The date the database was implemented. Guidelines for its use. Network requirements if users must be connected to the network to perform certain tasks for example, if the application uses lookups that require a network connection. The About document can contain rich text, so you can also use document, view, and database links, buttons, attachments, graphics, or multimedia files. The Using This Database document Create a Using This Database document to provide users with instructions on using various forms, views, and navigators in the database. To display this document, users choose Help - Using This Database. The Using document, like the About document, can contain rich text, so you can also add document or database links, buttons, attachments, graphics, or multimedia files. A Using This Database document should include: A quick overview of the application. The purpose of each view and its organizations. The purpose of each form and how to fill it out. The purpose of each agent, when to run it, and the anticipated results. The overall work process being automated if the application automates workflow, including what happens at each stage. When users fill out documents, they should understand what happens after the documents are saved, and what other users are expected to do. To create an About or Using document 1. In Designer, open the database youre designing. 2. In the Design pane, click Resources - Other. 3. Double-click About Database Document or Using Database Document. 4. Write or edit the information. You can also create links, buttons, hotspots, and attachments. You can apply text styles, as you would for any Notes form. 5. Save the document.
To automatically display the About This Database document 1. Choose File - Database - Properties and click the Launch tab. 2. Do any of the following: Select On Database Open: Open About database document to always open the About document first. Select Show About database document if modified if you edit the About document and want to show it to users again. Select Show About database document when database is opened for first time. Select On Web Open: Open About database document. You can use the About document as a springboard to a file in another database or another products file. To do so, use the Database Properties Launch options for Launch first attachment in About database document or Launch first doclink in About database document. To view the About or Using documents Do one of the following: Choose File - Database - Open, highlight a database title, and select About. This displays the About document. Open a database on the Bookmark pane and choose Help - About This Database or Using This Database.
@Command([OpenPage]). A user clicks the Help button to see the associated help document or page. Because the onHelpRequest event accepts a formula, you can use the formula language in other ways to provide help. For example, you can use an @If formula with @IsDocBeingEdited to provide different help for a form depending on whether a document is being read or edited, or depending on other conditions specific to your application. You can present a dialog box to allow users to select among several help documents or pages. You can place help text directly onto a form or page, set the text with a hide-when formula, and use a formula on the onHelpRequest event to reveal the text (by changing the value of a document field) when a user requests help. Tip To open documents in response to help requests, there must be a view containing those documents sorted by a key field that you can use as parameters for @Command([OpenHelpDocument]). You can use @Command([OpenPage]) without requiring a specific view or key field. For syntax and usage information on using @Command([OpenHelp Document]) or @Command([OpenPage]) in a formula, see the Programming Guide.
To write pop-up text for a field 1. Open the form in Designer. 2. Highlight the field label that is, static text that the user sees, not the rectangular field definition. 3. Choose Create - Hotspot - Text Pop-up. 4. In the Hotspot Properties box, write the pop-up text and click the green check mark. 5. Close and save the form or subform. Examples For a text field named Supervisor:
Enter the name of the person to whom you report.
documents from a Help database in a window that users can set to stay on top of other windows as they work, choose File - Database - Properties Design for your database. Then, turn on List in Database Catalog and enter the category NotesHelp.
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
Has a read-access list been defined for the form? If one is needed, define a read access list by assigning names to a Read access control list on the Security tab of the Form Properties box. Has a create access list been defined for the form? If one is needed, define a create access list by assigning names to a Compose access control list on the Security tab in the Form Properties box.
In time-date fields, is the time displaying correctly? If not, make sure you selected the appropriate time zone option in the Field Properties box. Are fields aligned properly with a variety of window sizes and on different monitors? If not, check the tab settings for the form. Are encrypted fields accessible to users who have the encryption key and inaccessible to all other users? Make sure that only authorized users have the encryption key. If unauthorized users have the encryption key, change the encryption key and redistribute it only to authorized users.
Are response documents indented? If not and you want to indent responses, select Show response documents in a hierarchy on the Options tab of the View Properties box and create a column for responses. Do response documents correspond to the correct main documents? If not, check the view selection formula; also be sure that the responses-only column is placed directly to the left of the column that displays the main document information. If the view uses categories, do the categories appear correctly? If not, create a sorted, categorized column and use the name of the appropriate keywords field as its formula. If the form uses a formula, do selected documents use the correct form? If not, check the form formula. Check cross-platform compatibility. Are all fonts used in this view available (or approximated) on all platforms? Are column widths sufficient for all platforms? Did you use platform-specific terms where appropriate? Make the application layout as generic as possible to suit all platforms. If needed, does the view have a read access list? To create a read access list, select the Security tab in the View Properties box. Checking columns Is the information in each column correct? If not, check the formulas in the column definitions. Is the column returning values of the appropriate data type? If not, check the field formula. Columns display only simple text; therefore, you may need to use @TEXT in the formula to display values from numbers or time fields. Is each column displaying all the information that is contained in it? If not, you may need to adjust the column width and/or the font used to display the column. If you are using a date format in a column, have you accommodated 4-digit years so that you avoid problems with the year 2000 and beyond.
Are the contents of columns aligned properly? For example, numbers should be right-justified; text should be left-justified or centered. Check the justification for each column. Are documents in the right order? If not, make sure that you sort on the correct columns, and that you chose the correct sort order (ascending or descending). Are documents supposed to be numbered? If so, create a new view that has a column in the left-most position that sorts in ascending order and uses @DocNumber for its formula.
The following access levels are recommended for the access control list of a template used for design maintenance:
Default Local Domain Servers Other Domain Servers Your User Name Database Manager [Anonymous] [Default] [LocalDomainServers] [OtherDomainServers] Reader Reader No Access Manager Manager No Access or whatever the actual database should have No Access or whatever the actual database should have Manager or whatever the actual database should have No Access or whatever the actual database should have
The items within the square brackets are needed only if the template is going to be used for creating new databases. The brackets are required for these entries. For more information about rolling out an application, see Managing Domino Databases.
To pilot test an application 1. Choose File - Database - New Copy to make a local backup copy of your application. Use this backup copy if you need to backtrack from changes made during the pilot test. 2. Write an About This Database document to explain that the application is in the testing phase. Give users your name, e-mail address, and phone number, so they can contact you with questions, comments, and suggestions. 3. Add a Comment form to make it easy for testers to give you feedback. Include the comment form in at least one view. (Make sure that the comment form is marked in the form design to be included on the Create menu, or that a button or action is available to the user to compose the form.) 4. Choose File - Database - Access Control to add testers to the access control list. Be sure to retain Manager access for yourself. 5. Ask your Notes administrator for write access to a server for the pilot test. Tell the administrator which users need access to that server during the pilot test. 6. Choose File - Database - New Copy to copy the application to the server. Test the application on a single server. Do not create replicas yet. 7. If the database will involve replication later on, either to mobile laptops or between servers, confirm that the replication formulas are working and that servers can handle the volume of replication. For example, an annual review system places a demand on the server during the review writing time, but not at other times. If users will be replicating, then the pilot needs to confirm that replication instructions are appropriate for the levels of user expertise. While the initial part of the pilot test may be limited to a single server, if the intended implementation involves multiple servers, then the pilot needs to address some of these issues as well. See Managing Domino Databases for additional help on replication. 8. Keep track of questions that people ask about the function or use of the database. Their questions may include the Using This Database document or to the design of the database. For more information on copying a new database to a server, see Managing Domino Databases.
Renaming a database
If you want to change the title of a database as it appears in the Bookmark bar, you can edit the title. 1. Open the database. 2. Choose File - Database - Properties. 3. Enter a new database title. A database name or title is not the same as the database file name. The file name associated with a database is permanent. The only way to change the file name is to make a copy or a replica of the database and give the new database a different file name.
Design synopsis
The Design Synopsis dialog box lets you generate a detailed report on a particular database. Design Synopsis lets you: Gather information on a database Select the design elements you want in your report Filter the contents of the report so that you do not automatically get a lengthy report Choose to have the report appear on the screen or have it written to a specified database
5. Click the Content tab. Then do the following: Check the details you want on each design element. For example, for Forms, you can check Form Alias and Last Modification. Those details appear for each selected form in the database. Check the appropriate boxes so that your report will include information on subcomponents (such as formulas), LotusScript code, Java code, HTML code, or JavaScript code. 6. Click the Output tab. Then do the following: Choose to have blank lines or page breaks as report separators. Check the Write Output to Database box if you want to write the report to a database. If you check this box, a new dialog box appears letting you specify the database where you want the output written. 7. Click OK to generate the report. Unless you chose to have the report written to a database, the generated report is displayed in a new window. You can print it or save it in a file.
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.
Adding a field
If you create a new field, create an agent that inserts the new field into existing documents using the formula:
FIELD New field name := value;
where New field name is the name of the field and value is the value you want the field in these documents to have. The value can be the field default value; a formula that calculates the value; or a null value () that inserts the field into the documents, but doesnt give them any initial value.
After you run the agent, compact the database to reduce the actual file size of the database.
Renaming a field
If you rename a field, existing documents continue to refer to the old field name. To update documents to refer to the new name, create an agent that uses the formula:
FIELD New field name := Old field name; FIELD Old field name := @DeleteField;
where New field name is the new name for the field, and Old field name is the original name for the field.
This formula removes all internal fields attached to the documents where Old form name is the name of the form used to create the documents. The last line creates a FORM field where New form name is the form that will display the documents in the future. After you run the agent, compact the database to reduce the actual file size of the database.
Templates
A template is a skeleton that contains design elements, but no documents. When you use a template to create a database, the database receives the design elements from the template. You can use the Designer templates as is or customize them. Or, you can create a template by creating a database with the .NTF file extension and the Database is a template property. This property enables the master template to distribute design changes automatically to databases created from it. Databases that inherit their designs from master templates receive the latest changes through a nightly server task. If, for some reason, you do not want to automatically inherit designs via the nightly server task, you have two options: (1) do not put the template on a server that runs the nightly update task or (2) do not set the Database is a template property. You can then distribute changes to the database design by using the Replace Design command, specifying the server where the template is located and selecting the template. Make sure to set the database properties so that the database does not automatically inherit the design via the nightly server task.
You can use letters, numbers, and underscores in the name. Choose a concise, descriptive name that is easy to remember and type. Choose a name that indicates the application type or design elements represented in the template. For example, StdR5Disc represents a standard Notes template containing the design for a Discussion (R5) database. The master template name, the title, and the categories assigned to the database cannot add up to more than 99 characters.
Creating templates
Using a template, you can establish design standards for use throughout your company. In large companies, a central development group usually designs and manages templates to provide consistent designs and speed up distribution of new databases. Use a template to standardize similar types of applications for example, all discussion databases or to store individual design elements, such as fields, forms, views, folders, navigators, and agents that you can use in a variety of applications. To customize a Designer template, use File - Database - New Copy to copy the original template and inherit the original design. Give it a different file name in the Copy Database dialog box to prevent future releases from writing over your customized template. Heres a list of changes you might make when you customize a Designer template: Leave the original Designer template properties alone so that existing databases that inherit their design will continue to be synchronized to the template. Change the newly copied template file name in the Copy Database dialog box (File - Database - New Copy) to a name that indicates its intended use. Change the newly copied template name (File - Database -Properties) to a new name, indicative of the new template purpose. If existing databases that inherited the original Designer template design need to inherit the design from the newly created template, edit the database properties of those databases to reflect the name of the newly copied template.
A spinoff template Most users mail databases inherit their design from the standard Notes mail template, but the Eastern region employees need a Reply to Customer form in their mail databases. Make a copy of the Notes mail template to use as a base for the Eastern mail template. You inherit the design from the Notes mail template, but after creating the Reply to Customer form, you click Prohibit design refresh or replace to modify in the Design Document Properties box so the form wont be deleted when the server resynchronizes the design of mail databases. The Eastern regions template inherits its design from the Domino mail template and also serves as a template itself. MAIL50.NTF (StdR5Mail) |-SLEE.NSF Sam Lees mail inherits from StdR5Mail |-EASTMAIL.NTF (StdEastMail) Eastern mail template inherits from StdR5Mail |- SBRAUN.NSF Sandy Brauns mail inherits from StdEastMail A designers notebook You create a new template called DesignNotebook to store centralized information, such as employee names and product numbers, as well as generic design elements, such as Main Document forms and All by Category views. Developers and experienced users browse through the Design Notebook when they create a new database and copy and inherit elements to speed up their design work. DESIGN.NTF (DesignNotebook) |- Suggestion Box: Inherit the All by Category view from DesignNotebook |- Employees Directory: Inherit the Employee Information form and EmployeeID field from DesignNotebook |- Product Catalog: Inherit the Product ID Update agent from DesignNotebook
To create a design library template 1. Create a new blank database with the file extension .NSF. 2. Copy the individual design elements into the template. 3. On the Design tab of the Database Properties box, select Database is a template and enter a template name. 4. On the Design tab of the Database Properties boxes of the databases that will inherit these design items, select Inherit design from template and enter the template name.
To link an existing design element to a template If you link an existing design element to a template, the design is replaced when the servers Design task runs or when you manually refresh the design. Thereafter, the design element remains synchronized with the template. 1. Select the master template and choose File - Database - Properties. 2. Click the Design tab. 3. Highlight the name in the Database is a template box and press CTRL+C to copy it. 4. In Designer, open the database containing a design element you want to link. 5. In the Design pane, select the type of design element youre designing. 6. Select the name of the design element in the Work pane. 7. Do one of the following: For an agent, choose Agent - Agent Properties. For other design elements, choose Design - Design Properties. 8. Click the Design tab of the Design or Agent Properties box. 9. Click Inherit from the design template and press CTRL+V to paste the name.
organizations, using a template or a master template is a matter of preference. This figure below summarizes the steps you take to make and distribute design changes:
Replication is the process by which database replicas on multiple servers synchronize their data and their designs automatically. Its important to understand which design changes replicate and which dont and how the database access control list and other replication settings affect the distribution of design changes.
Refreshing a design
Refreshing a design updates a database whose design is linked to a template. Design elements that prohibit design replace or refresh are not included in the updates.
Replacing a design
The Replace Design command makes a database identical to a template and is the only way to distribute design changes if the database doesnt inherit its changes from a template. If you have at least Designer access in the database ACL, you can replace the design of a database with the design from a template.
When you hide a database design, users cannot: View the settings for design elements (View - Design disappears from the View menu) Modify, add, or delete fields, forms, navigators, pages, or subforms Modify or delete existing views View, delete, or modify existing agents or add shared agents View or change formulas, LotusScript programs, or formulas associated with simple actions Change the Database Open properties Display a synopsis of the design Reveal the design of the database by making a copy or replica of it To hide the design of a database This procedure assumes youre hiding the design of a database that inherits from a template. Thoroughly review, debug, and pilot test the template before proceeding. 1. Create a new database based on the template. 2. After the database is created, select the new database and choose File Database - Replace Design. 3. Select the template and select Hide formulas and LotusScript and Inherit future design changes. 4. Click Replace and Yes to confirm.
Workflow Overview
Workflow applications let you automate tasks. These tasks most often involve automatically sending mail messages or automatically routing documents, such as tracking orders and reviewing project plans. Any project requires that one person or a number of people complete a series of tasks; workflow applications guide the project through these tasks automatically. Workflow applications reduce overhead and errors, speed processes, and track the status of a project. For example, a workflow application might automatically send a document in a publishing company from writer to editor to proofreader to production. At each stage, an individual is responsible for specific tasks related to that document. Once the task is complete, the workflow application ensures that the individuals responsible for the next task are notified and receive the data they need to execute their stage of the process. Examples of Workflow Applications The Document Library R5 template (doclbw50.ntf) and the Teamroom R5 template (teamrm50.ntf) are examples of applications that include workflow. For both templates, the document you want reviewed is kept in a central database and is not mailed to reviewers. Reviewers receive mail notifying them of the need to review. Included in the mail may be a doclink to the document. The Document Library template uses a review cycle so that you can route a document link to a series of recipients. It allows serial and parallel reviews. With parallel reviews, every reviewer receives e-mail notification at the same time. With serial reviews, you do not want all reviewers commenting on the document at the same time. Reviewers receive e-mail notification at different times. The Teamroom template features parallel review processing. It also allows the automatic mailing and archiving of newsletters and memos. See the Domino Designer Templates Guide for additional information on these templates.
413
Planning workflow
Before you select the type of mailing features that suit a workflow application, you should carefully plan the actual workflow. One way to implement a workflow application is to collect information from the databases of an application into a central, shared database and then distribute the information through e-mail to the appropriate individual users. Another way to implement a workflow application is to send documents automatically from one user to another for their review. Users working in a shared database can create and edit documents directly in the database. Remote users must dial into the server database regularly to contribute. Designers can implement automatic e-mail notifications to alert users to documents in the database that need their attention. To automate the process, you can build e-mail notifications into forms or agents. To make it easier for users, the notifications often include document links. For the convenience of remote users, you might include a copy of the document within the e-mail notification instead of a link to the document. If users work in individual mail databases, they can create and respond to documents and then route them to each other or to a central mail-in database. Automated, easy-to-use forms that are stored in documents are typical of such applications. Of course, if you are sending individual mail messages, you are increasing disk space because the form is stored with the document. The following table summarizes the advantages and disadvantages of these two approaches.
Method Central Shared Database Central shared database; e-mail notices that link to documents Alerts users to work that needs their attention or items of interest in a central database; places least burden on network resources and conserves server disk space; users get to see each others review comments. Requires network access or remote access through a modem Advantages Disadvantages
continued
Advantages
Disadvantages
Easier for remote users because they only need to access mail instead of accessing a remote database.
Workflow process may take longer since work is done sequentially; requires more server disk space than a central database because forms must be stored with documents; replication times may be longer because of document size.
Sending documents
It makes sense to build in features for mailing documents in the following situations: Users work on documents sequentially from their individual mail databases You want to send documents to a mail-in database The form must have a SendTo field that specifies the recipients, unless you use a formula or program that includes the SendTo information. Use any of these methods: Add a MailOptions field with a value of 1 to force the document to be mailed when it is saved. Select the form property On Close: Present mail send dialog to let users decide if they want to mail the document. Create an agent, event, form or view action, hotspot, or button that uses: The simple action Send Document The formula functions @Command([@MailSend]) for optional mailing or @MailSend for automatic mailing A LotusScript program that uses the Send method of the NotesDocument class or the NotesUIDocument class A Java program that uses the Send method of the lotus.notes.Document class In addition, all forms and views contain the default action Send Document that you can display in the Actions menu or the action bar.
1, 0
The name(s) of a person, Required for all forms that mail group, or mail-in database. documents. 1, 0 Use 1 to an add electronic signature to fields. (Only applicable if a form also contains sign-enabled fields.)
If you write a LotusScript program that uses the Send method of the NotesDocument class or a formula that uses @MailSend, you can include many of the above mailing options in the script or formula. For more information on using LotusScript, see the Programming Guide.
418 Application Development with Domino Designer
Interactions with the Mail Send dialog box The MailOptions field with a value of 1 overrides the users choices in the Mail Send dialog box if the form is set to enable optional mailing. With a MailOptions field set to 1, users can click Yes to save the document, No to close without saving, or Cancel to return to the document. The Sign, Encrypt, and SaveOptions fields with values of 1 override the property On Close: Present mail send dialog in the Form Properties box, but they do not actually change what is displayed to users in the Mail Send dialog box. Interactions with the Document Save dialog box The values in SaveOptions, Sign, and Encrypt fields override the users settings in the Document Save dialog box. MailFormat A computed MailFormat field can have one of the following values: Encapsulated (E) The document is encapsulated in a database, which is attached to the cc:Mail memo. The cc:Mail recipient must have the Notes client installed on the workstation. This preserves the document exactly as it looks in Notes. To read the document, the cc:Mail user double-clicks the icon representing the attached database; this launches Notes and opens the database. Use this format only if information will be lost if the document were to be converted to Text or Memo format. The Encapsulated format creates larger documents, so it uses more server disk space. To ensure that the document is displayed correctly when a cc:Mail recipient starts Notes, assign the form property Store form in document in the Form Properties box. Text (Text) The contents of the document are rendered as text and pasted into the body of the cc:Mail memo. The cc:Mail recipient can read the document without using Notes. Since the document is rendered as text, you do not need to store the form in the document. Both (B) The document is both rendered as text and encapsulated in a database. This ensures that cc:Mail recipients can read the document even if they do not use Notes. Mail (M) The Body field of the document is rendered as text and pasted into the cc:Mail memo. Use this format only with documents that were created using a form that contains a field named Body.
Since the document is rendered as text, you do not need to store the form in the document. MailOptions The MailOptions field with a value of 1 overrides the property On Close: Present mail send dialog in the Form Properties box. With a MailOptions field set to 1, users can click Yes to save the document, No to close without saving, or Cancel to return to the document. To add the mail signing and encryption options, create editable keywords fields named Sign and Encrypt. SendTo The Allow multi-values and Allow values not in list are useful for SendTo fields. Examples: Fields that control mailing options An editable SendTo field with a default value You want to give users the name of the mail-in Employee Survey database, and the option of mailing surveys to other people. Create an editable SendTo field, select Allow multi-values, and write a default value formula that includes the mail-in database name, enclosed in quotation marks. A hidden SendTo field with a single recipient Sandy Brown needs to receive all documents saved in the Marketing Statistics database. Add a hidden Names field called SendTo to the Statistics form. The field formula contains the recipients name and domain enclosed in quotation marks. The recipients domain is required if the recipient isnt in the same Notes domain from which the document is sent.
"Sandy Brown @ Marketing"
A formula that calculates recipients and sends a document Approvers want to receive new travel requests from employees by e-mail. On the Travel Request form of the Employee Expenses database, create hidden text fields called SendTo, Subject, and Remark. The field formula below calculates the names of approvers and sends the original document as a link when the document is saved for the first time.
REM "Send mail to approvers the first time the doc is saved"; REM; SendTo :=@Unique(@Trim(ApproverName_1 : ApproverName_2 : ApproverName_3)); Subject := "Travel Request for " + TravelerName + "requires your approval"; Remark := "A Travel Request has been entered for " + TravelerName + ". Your approval is required. Please double-click the following link and approve or reject the request."; 420 Application Development with Domino Designer
REM; @If(@IsNewDoc & @IsDocBeingSaved; @MailSend(SendTo; ""; ""; Subject; Remark; "";[IncludeDoclink]); "")
Then click OK. 5. Select All new and modified documents since last run and click Add Search. 6. Select Condition: By Form Used, select Action Item, and click OK. 7. Click Add Search and select Condition By Field and select Status, contains, Open. Click OK. 8. Click Simple action(s) and Add Action. 9. Select Send Mail Message and click More. 10. In the To box, click Formula and enter the formula:
AssignedTo
11. In the Subject box, click Formula, type this formula and click OK:
ActionItem + ", due " + @Text(DueDate)
13. Select Include copy of document and click OK. 14. Close and save the agent.
All Personnel is a group in the Domino Directory. 8. In the Subject box, type:
Important Announcements
10. Select Include summary for each document in view, select the All By Date view, and click OK. 11. Close and save the agent.
LotusScript and Java classes LotusScript and Java include classes for enterprise data access. Use these classes to customize applications to incorporate information from relational databases, transaction systems, and ERP applications according to your business needs. The Domino Server includes the Lotus Domino Connector LotusScript extension, permitting programmatic access to Domino Connectors from LotusScript. For more information about the Domino Connector LSX, see the LotusScript Extension for Domino Connectors Reference Guide. The Domino driver for JDBC, providing standard JDBC access to data in Domino databases, is also available from the Lotus Web site at http://www.lotus.com. Using this driver, you can write Java applets and applications that use JDBC to access information in Domino databases. JDBC classes now ship with Domino in the java.sql classes. These classes may be used when writing Java agents to access relational data via standard JDBC drivers. For more information on LotusScript and Java classes, see the Programming Guide. Domino Connectors Domino Connectors are modules which provide native connectivity to external sources such as relational databases, ERP, or transaction systems. You can access these connectors through the forms-based development tool in DECS, or through the Domino object classes using LotusScript or Java languages. For more information on Domino Connectors, see the Domino Connectors Setup Guide. Lotus Enterprise Integrator Lotus Enterprise Integrator, previously called Lotus NotesPump, which is available separately, extends DECS functionality beyond real-time data sources to include support for high volume data transfer and synchronization. Lotus Enterprise Integrator provides visual tools to manage integration between data sources without programming, including the capability to initiate event-driven or scheduled high volume data transfers between Domino applications and relational databases and other enterprise applications. Lotus Enterprise Integrator also supports programmatic data transfers via LotusScript and Java Classes. For more information on Lotus Enterprise Integrator, see the Lotus Web site at http://www.eicentral.lotus.com.
Domino Version
DECS - Domino Forms-based development tool. Provides R4.6.2 Enterprise Connection live access to enterprise data and or higher Services applications, including relational databases, transaction systems, and Enterprise Resource Planning (ERP) systems. LS:DO - LotusScript Data Object LotusScript access to any ODBC-compliant R4.0 data sources. or higher
JDBC - Java Database Access from Java agents to R4.6 Connectivity relational data via Standard JDBC classes. A or higher JDBC to ODBC bridge also shipped as a part of Domino. Lotus Domino Connector LotusScript Classes Lotus Domino Connectors Unified object model with a consistent R4.6.2 interface to programmatically access or higher enterprise data and applications. These classes can be used with LotusScript or Java. Modules which provide native connectivity R4.6.2 to enterprise data sources. These connectors or higher can be accessed through Domino Enterprise Connection Services or programmatically through Domino classes. Connectors to DB2, Oracle, Sybase, Text & File based systems, EDA/SQL, and ODBC are provided with the Domino server. Premium connectors to ERP applications, Transaction Monitors, and Directory systems will be available separately. Note that the NotesSQL driver for ODBC access to Domino data is available for free from the Lotus Web site at http://www.lotus.com. LSX - LotusScript extensions Create custom objects that work natively with Domino applications as well as Java and OLE. Some examples of LSXs are MQSeries, SAP, DB2, and Rich text. The DB2 LSX will ship for Domino Release 5. These are classes for programming directly to the DB2 client access library. Lotus Enterprise Integrator (Lotus Notes Pump) Data distribution server that provides support for event-driven or scheduled high-volume transfer and data source synchronization. R4.0 or higher R4.0 or higher
continued
Domino Version
Provide developers with tools and R4.6.2 information to build additional Domino or higher Connectors and classes available in Java or LotusScript.
Note On 32-bit platforms, such as Windows 95, avoid having the 32-bit and 16-bit versions of drivers and driver managers installed with a 32-bit or 16-bit version of Domino installed. The two different types of software do not mix. When using 32-bit Notes clients or servers, use a 32-bit driver manager and 32-bit drivers. When using a 16-bit Notes client or Domino server, use a 16-bit driver manager and 16-bit drivers to use ODBC to make successful connections. Some Lotus applications include ODBC drivers that are licensed specifically for use with that application. Domino cannot use these drivers. If you try to use these drivers, a message appears stating that you must have a license. You may be given a phone number or other information. For more information about ODBC, see the Microsoft ODBC 2.0 Programmers Reference and SDK Guide published by Microsoft Press.
431
incorporate Suns upgrades, so you should check the QMR Release Notes to verify the supported JDK and JSDK versions.
The following settings control the Domino Servlet Managers runtime support of the Java Servlet API HttpSession interface. A servlet that does not use this interface is not affected by these settings. Note The HttpSession interface support is completely separate from the HTTP session authentication feature in Domino.
Setting Options Session state tracking Enabled: (default) The servlet manager periodically checks the user activity of all HttpSession instances. Sessions that have been idle for a given period of time are automatically terminated. The servlet manager calls the instances HttpSession.invalidate() method to inform the servlet that the session is being terminated. Disabled: Sessions will not be checked for inactivity. Idle session timeout Maximum active sessions Session persistence The number of minutes of user inactivity to wait before terminating a session. The default is 30 minutes. The number of simultaneous active sessions allowed. The default is 1,000 sessions. When this limit is reached, the sessions that have been idle the longest are terminated. Enabled: When the HTTP task exits, the servlet manager saves session data to a disk file called sessdata.ser in the Domino data directory. The session data will be reloaded when the HTTP task is restarted. Objects that the servlet has bound to sessions will also be saved if the objects implement the java.io.Serializable interface. Disabled: (default) All session data is discarded when the HTTP task exits.
Directives are case-sensitive. The servlets.properties file can also contain blank lines and comment lines starting with the # character. The servlets.properties file is optional. The default properties for servlets are: no alias, no initialization arguments, no extension mapping, and load servlets on demand.
Servlet aliases
The alias directive has this syntax:
servlet.<alias-name>.code=<class-name>
For example:
servlet.SQLQuery.code=sql.database.query.Servlet
A servlet alias is a convenient name by which to reference the servlet in a URL, instead of using its class name. An alias is especially useful if the servlet is in a package. The above example allows the servlet to be invoked by a URL like http://acme.com/servlet/SQLQuery?month=june rather than http://acme.com/servlet/sql.database.query.Servlet?month=june. You can assign more than one alias to a servlet. The servlet manager will create a new instance of the servlet on receiving the first URL that refers to each alias. The servlet manager will call the servlets init() method when a new instance is created. Since the alias name can be used in other directives in the properties file, the instances can be given different properties. For example, you could specify a separate initialization argument directive for each alias. Also, because the servlet classes are only loaded once even if multiple instances are created, the instances of the servlet can share data by using static class variables.
As a security feature, if you give a servlet an alias, the servlet cannot be directly referenced in a URL by its class name. This allows you to hide the actual name of a servlet.
Initialization arguments
You can specify initial data for a servlet in the properties file. The servlet can access the data by using the method ServletConfig.getInitParameter. The initialization directive has this syntax:
servlet.<alias or class name>.initArgs=<name1=value1>,<name2=value2>,...
You can assign more than one extension to a servlet, separating each from the next by a space. All extensions must also be included in the Servlet file extensions setting in the Server record. For example, to cause Domino to call the SQLQuery servlet whenever a URL specifies the extension sql or sq, add sql,sq to the server setting and add this directive to the properties file:
servlet.SQLQuery.extension=sql sq
This allows a user to invoke the servlet with a URL like this:
http://acme.com/query.sql?month=june
Load on startup
By default, the servlet manager loads a servlets class files into memory the first time a URL is received that refers to the servlet. However, you can specify that one or more servlets should be loaded immediately when the servlet manager is started. This prevents users from experiencing delays when servlets are first requested from URLs. The startup directive has this syntax:
servlets.startup=<alias or class> <alias or class> ...
Note that servlets is plural and that the servlet names must be separated by spaces.
If you have given a servlet one or more aliases, you can include the aliases in the startup directive. This will cause the servlet manager to load the servlet classes and then create an instance for each alias. After the servlet manager loads a servlets classes, they stay in memory until the Domino HTTP task is stopped by the console command tell http quit or restarted by the console command tell http restart. Before unloading a servlet, the servlet manager calls the destroy() method for each instance of the servlet, to give it a chance to clean up resources. A class that has been loaded by the JVM class loader remains loaded until the HTTP task is stopped. The tell http restart command will not unload the class. Example properties file Here is an example of a servlets.properties file:
# Properties for the sql servlet servlet.SQLQuery.code=sql.database.query.Servlet servlet.SQLQuery.initArgs=cache=30 servlet.SQLQuery.extension=sql # Properties for the mail servlet servlet.MailServlet.initArgs=mime=enabled,smime=disabled # Both servlets should be loaded at startup servlets.startup=SQLQuery MailServlet # end of file Example: Java servlet
This example servlet returns an HTML page that displays all the HTTP headers that the browser sent with the servlet request.
import import import import java.util.*; java.io.*; javax.servlet.*; javax.servlet.http.*;
public class ExampleServlet extends HttpServlet { public void doGet (HttpServletRequest request, HttpServletResponse 3response) throws IOException { response.setContentType("text/html"); ServletOutputStream out = response.getOutputStream(); out.println("<HTML><B>Headers sent with the request:</B><BR>"); for (Enumeration headers = request.getHeaderNames(); Chapter 17: Including Java Servlets in Web Applications 439
headers.hasMoreElements();) { String headerName = (String) headers.nextElement(); out.println("<BR>" + headerName + ": " + request.getHeader(headerName)); } } // end of method } // end of class
After you compile this code, copy the ExampleServlet.class file to your server domino\servlet directory. It does not need any special properties, so you do not need to create a servlets.properties file. Run the servlet from a browser by entering this URL, using the name of your server:
http://www.yourserver.com/servlet/ExampleServlet
The information in the page returned by the servlet depends on the browser. Here is the HTML page returned for a Netscape browser:
<HTML><B>Headers received with the request:</B><BR> <BR>ACCEPT-LANGUAGE: en <BR>CONNECTION: Keep-Alive <BR>ACCEPT: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */* <BR>USER-AGENT: Mozilla/4.05 [en] (Win95; U ;Nav) <BR>ACCEPT-CHARSET: iso-8859-1,*,utf-8 <BR>HOST: test1
doclbw50.ntf StdR50WebDocLib
441
Database title
Description Special version of the Document Library template dedicated to this application suite. Automatically loads and sizes the OLE object to the window; and stores and supports review cycles of documents created with suite products.
journal4.ntf StdR4Journal
Electronic diary where users can write and organize private ideas and documents. Includes instructions for customizing the design. A sample showing how to register Web users for Domino-based applications. Users can create accounts for themselves with no manual intervention. Model of team collaborative operations. Maintains several document communication types to represent meetings, discussions, and action items. Features parallel review processing, archiving, and newsletters.
TeamRoom (R5.0)
teamrm50.ntf StdR50TeamRoom
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).
Structured text
*To import a Microsoft Excel file, use Excel to save the file as a 1-2-3 worksheet and then import it. **You cannot import a .wrk or .wr1 file to a view, but you may export to either format. If you import a multiple-worksheet file, only the worksheet that was most recently viewed will be imported. If you import a specific range from a multiple-worksheet file, only the information from the most recently viewed worksheet will be imported.
443
Importing options
Formatting options
You have three choices for generating the column titles and widths when you import a file. Choose View Defined if the column names and column widths in the source worksheet are identical to the names and widths of the columns in the view. Choose WKS Title Defined if youve set up the worksheet so that the cells in the first row of the worksheet match the column headers and fields in the view. The cells in the first row must be labels. Choose Format File Defined if you are using a column descriptor file (.col) that contains column style instructions.
Guidelines
Notes uses a character translation file (.cls) to translate foreign symbols and characters. The .cls file must be in the Notes program directory.
Importing worksheets
Before you import a worksheet, you must create a form and a view to hold the imported data. When you import a worksheet into the view, each worksheet row becomes an individual document, and each worksheet column becomes a field. The original cell contents become the field contents. You can import data into either main documents or response documents. Notes doesnt wrap lines of an imported worksheet. If a worksheet has more columns than a window can display, use the horizontal scroll bars to see the full width of the worksheet. Notes can handle a worksheet whose maximum text width is 22.75 inches; additional text is not displayed in the columns.
444 Application Development with Domino Designer
import the ASCII file, select the Use format file option in the Tabular Text Import dialog box.
Using a column descriptor file (.col) to map a source file to a Notes view
To import many files that have an identical structure into a view, create a column format descriptor (.col) file. A .col file is like a map that defines which data from the source file goes into which Notes field. A .col file is for use only with tabular text files and worksheet files. A .col file is an ASCII text file that contains a series of column definition statements, followed by a section containing formulas that control the contents of fields in the Notes view. You write one statement for each column in the source file. This statement describes how to format and map the columns in the source file to columns in the Notes view. For best results, use exactly the same field names in the .col file and in the Notes view.
create a new Notes field called Phone, and refer to the field in the view youre using.
The data in the source column must fit the datatype you specify. If Notes encounters data that doesnt match the datatype you specify, Notes imports the data as the type it most resembles.
Guidelines
The formulas that you write in a .col file describe how to modify the incoming values for display in the view. These formulas, which follow the same rules as view selection formulas, may perform such operations as: Use @If formulas to test incoming values and display a specific value in the view, depending on the result of the formula Use text manipulation functions to modify the appearance of the incoming value; for example, to concatenate values or trim excess space characters from incoming values Enter default values in fields
Where: fieldname is the name of the field in the view. columnletter is the letter of the source column in the worksheet that maps to that field name. Only columns specified by the WKSCOL keyword will be imported. RANGE This keyword specifies the worksheet range to be imported. The syntax for a statement using this keyword is: RANGE rangename Where: rangename is the name of the range in the worksheet. The range must be a valid range name in the imported file. If you use a RANGE statement, the first WKSCOL statement in the .col file must refer to the first column in the range. For example, if the range starts at column D, the first WKSCOL statement in the .col file must be: Fieldname: WKSCOL D Note that a RANGE statement in a .col file overrides any range name entered in the Worksheet Import Settings box.
If there is no delimiter at the end of the record (row), you identify the end of the last field as a null ().
or
LastName: Start 01 WIDTH 12
The first column position is always 01, not 0. The following lines of a .col file give two sets of instructions:
LastName: START 1 WIDTH 12 FirstName: TYPE TEXT START 13 END 20
The first line puts the contents of the first field, LastName, at position 1 and allows 12 characters for it. The second line specifies that the data type of the FirstName field is text, begins the contents of the field at position 13, and allows 8 characters for it.
The keywords may appear together or alone on a line in the file. These settings in a .col file override values in the Tabular Text Import dialog box.
Appendix B: Importing to and Exporting from Views 451
In this example, columns D, E, H, I, and J in the worksheet are not imported into the view.
Exporting views
You can export a view to a worksheet, a tabular text file, or a structured text file.
Exporting to a worksheet
When you export a view to a worksheet, each document becomes a row in the worksheet. Each field becomes a column in the worksheet. The original field contents become cell contents. Column titles become labels in the worksheet.
When you export a view to a new worksheet file, Notes exports the file in 1-2-3 .wk1 format. Although you can specify any extension with the file name, its best to keep the extension .wl1. When you open the exported file in a newer release of 1-2-3, 1-2-3 automatically converts the file to its new format and adds the appropriate extension. If you change the exported file to .wk2, .wk3, or .wk4 before opening it in a release of 1-2-3 that uses that extension, then open the file in 1-2-3 and attempt to add and save attributes, the new copy of the file will be in conflict with the original, and you wont be able to save your changes. To export to a Microsoft Excel file, export the view as a 1-2-3 worksheet, and then save the file in 1-2-3 as a Microsoft Excel file.
5. Do one of the following: To replace an existing file, select a directory and file name from the list. To create a new file, enter a new file name. To append to an existing tabular text file, select a directory and file name from the list. 6. Click Export. 7. If you selected an existing file, do one of the following: To replace the file, click Replace. To append to an existing file, click Append. 8. Click All documents unless you selected specific documents in Step 2. 9. (Optional, for 1-2-3 worksheet or tabular text formats) Select Include View titles to export the views column headings to a worksheet or tabular text file. 10. (Optional, for structured text format) Change the inter-document delimiter and word-wrap settings if you are exporting to a structured text file. 11. Click OK. Note In step 10, choose Form Feed to use a form-feed to separate records in the file, or choose Character Code to separate the records in the file with the ASCII code for a delimiter other than the default, ASCII 12 (form-feed), such as: 32 44 45 58 59 124 Space , : ; |
The word wrap option represents the number of characters at which each line wraps. The default is 75 characters.
The Address Book provider searches the Domino Directory for recipients names according to the order specified in the profile. Any Simple or Extended MAPI client can use the Address Book provider to access a Domino mail file and Domino Directory.
Mail The Domino MAPI service providers may only be used to access mail files that use the Domino Release 5.0 mail template (mail50.ntf). If you are upgrading from Release 4.x to Release 5.0, you must upgrade your mail file to use the mail template provided in Release 5.0. To use the service providers, both the client and the server must be running Release 5.0. The Profile Setup Wizard automatically installs all three service providers. When you create a Microsoft Exchange Profile, the wizard uses information stored in the current Location document in Domino. You make modifications to the Office (Network) Location document to configure the location for server-based mail. To use workstation-based mail, you modify the Travel or Island (Disconnected) Location document appropriately. Note that the Location type in the document must be either Local Area Network or No Connection. The Mail section of the location document must specify information about the mail file location, the name of the mail file, and the domain. Note During logon to the service providers, the settings for MDB_NO_DIALOG and AB_NO_DIALOG flags are ignored. As a result, the user is always prompted for a password. Address Book template To access Domino Directories through the Address Book Provider, you must apply the Domino Release 5.0 Domino Directory template (pubnames.ntf) to the design. If you are using workstation-based mail, apply the Personal Address Book template (pernames.ntf) to the design of the Personal Address Books.
CLASS IABLogon
CLASS IMAPIFolder
CLASS IMAPIProp
Supported methods Abort Advise CreateBookmark FindRow FreeBookmark GetLastError GetRowCount GetStatus QueryColumns QueryPosition QuerySortOrder Restrict (supported for Address Book Provider, but not for Message Store Provider) SeekRow SeekRowApprox SetColumns Unadvise CreateAttach DeleteAttach GetAttachmentTable GetRecipientTable ModifyRecipients OpenAttach SetReadFlag SubmitMessage Note Message object based on Notes note, not MAPI-supplied IMSG.DLL OLE Docfile representation. AbortSubmit Advise CompareEntryIDs FinishedMsg GetOutgoingQueue GetReceiveFolder NotifyNewMail OpenEntry SetLockState SetReceiveFolder StoreLogoff Unadvise continued
CLASS IMessage
CLASS IMsgStore
Supported methods Advise CompareEntryIDs GetLastError Logoff OpenEntry Unadvise CompareStoreIDs Logon Shutdown SpoolerLogon AddressTypes EndMessage FlushQueues Idle (supported, but not used for tightly-coupled message store) OpenStatusEntry Poll (supported, but not used for tightly-coupled message store) RegisterOptions StartMessage (supported, but not used for tightly-coupled message store) SubmitMessage TransportNotify Shutdown TransportLogon All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class
CLASS IMSProvider
CLASS IXPLogon
CLASS IXPProvider CLASS IMailUser CLASS IAttach CLASS IMAPIAdviseSink CLASS IMAPIProfile CLASS IMAPIContainer CLASS IMAPIStatus CLASS IPropData CLASS ITableData
@DDEExecute @DDEInitiate @DDEPoke @DDETerminate @DocMark @DeleteDocument @DocChildren @DocDescendants @DocLevel @DocNumber @DocParentNumber @DocSiblings @IsCategory @IsExpandable @Responses continued Not available except in column formulas.
463
@Function @DialogBox @PickList @Prompt @IsModalHelp @GetPortsList @Environment @SetEnvironment ENVIRONMENT keyword @MailSend @Domain @MailDbName @MailEncryptSavedPreference @MailEncryptSendPreference @MailSavePreference @MailSignPreference @IsAgentEnabled @IsDocBeingMailed @URLGetHeader @URLHistory @UserPrivileges @Platform for users platform.
Comments
Use predefined field names to gather information about the Web users environment by requesting Common Gateway Interface (CGI) environment variables.
Returns servers platform only. Use @ClientType to distinguish between Web and Domino users.
Domino actions and agent properties that are not supported on the Web
Avoid using the following actions and agent features in a Web application.
Feature Agents Manually From Actions Menu Web users do not have an Actions menu. Run agents with actions or buttons that use @Command([ToolsRunMacro]) or through the WebQuerySave and WebQueryOpen form events. The concepts of pasted documents and selected documents dont apply to Web applications. continued Comments
If Documents Have Been Pasted and the document selection option Selected documents
Comments Web users do not have an Actions menu. Use the option Include action in button bar instead. Use supported @commands to create the equivalent actions.
Default form and view actions that use system commands (such as *Edit Document, *Categorize) Programs for actions and agents Simple actions LotusScript for forms, actions, and buttons Alias a folder simple action
Supported for agents only. Dragging and dropping to folders is not available on the Web.
Feature Advanced properties Help description Enable encryption for this field Sign if mailed or saved in section Names fields Control properties Choices (for Names fields)
Comments
Use Address dialog for choices, Use Access Control List for choices, and Use View dialog for choices are not supported. Web user access to databases is based on the authenticated name. For some browsers, the order of the data returned from multiple selections in a checkbox may be different from the selection order. The data itself remains the same, but the order returned is different.
Comments
On Create: Inherit entire selected Inheritance from selected documents is document into rich text field as supported on the Web, but only if the field is Link and as Collapsible rich text of type text, the document resides in the same This applies to rich text fields only. database, and the database property, Web Access: Use JavaScript when generating On Create may be used for text pages is selected. fields on the Web. Inherit entire selected document into rich text field as rich text is supported. On Open: Show context pane Security properties Default encryption keys Disable printing/ forwarding/copying to clipboard Form elements Layout regions Pop-up hotspots ActiveX components, OLE, and OCX objects Not supported on Macintosh, UNIX, and OS/2 platforms. Supported for display on Windows NT and Windows 95 platforms, but users cant save changes made to objects. If the top left cell of a table has a border, the entire table is displayed with a border; otherwise, there is no border because of limitations with HTML. Use tables to align form components instead. Not applicable to Web.
Feature First-line indent or outdent in a paragraph Full justification paragraph alignment Images Ordered lists
Comments
Avoid this feature if editing a document with both the Notes client and the editor applet. Avoid this feature if the list will be edited in the Notes client and the editor applet. Ordered lists are supported if they are edited with the editor applet only. There are limitations for pasting text in the editor applet. See Designing Fields for information about using the editor applet for editing rich text fields on the Web.
Pasting text
Tabs Tables Unordered lists Avoid this feature if editing a document with both the Notes client and the editor applet. Avoid this feature if the list will be edited in the Notes client. Unordered lists are supported if they are edited with the editor applet only.
Domino horizontal rule properties that are not supported on the Web
Avoid using the following horizontal rule feature in a Web application.
Feature Horizontal Rule Info properties Color Gradient is not supported on the Web. Comments
Minimum height Row spacing Table Width Cell Borders properties Color Cell Border Style Cell Border Thickness Table/Cell Background properties Style Cell image Table Borders properties Border style Border color Border effects Thickness Table Margins properties Left Right Table wrap Compatibility Table Rows properties Show only one row at a time Switch rows every n milliseconds and transitions are not supported. Determined by individual cell borders. The table color is used. Width is not supported. Solid is the only color option supported on the Web. Gradients will appear as the first color. Cells are the same color as the table. The style options, Ridge and Groove, are not supported on the Web. Border thickness settings greater than 1 are not supported. Same as window is ignored in a Web application.
Formatting aids, such as tabs, HTML doesnt support these formatting indents, outdents, and extra spaces styles. Use tables to align form components. Use the text style Pass-Thru HTML to use HTML formatting styles. Text effects properties Shadow, Emboss, and Extrude text styles
Feature On Open: Go To... options On Refresh options Style properties Unread rows Alternate rows Show selection margin Beveled headings Advanced properties Refresh index options Discard index options Columns Basics properties Show twistie when row is expandable
Comments
View properties that are not supported by the Domino view applet
Avoid using the following Domino view applet features in a Web application.
Feature Pass-Thru HTML Horizontal scrollbars View View Info properties Calendar views Options properties On open: Go to last opened document On Refresh Style properties Unread rows color Alternate rows color continued 472 Application Development with Domino Designer None of these options are supported. Calendar views are not supported. The HTML Calendar view will be generated even if view applet is selected. Comments
Feature Beveled headings Lines per heading Shrink rows to content Row spacing Advanced properties Refresh index Discard index Unread marks For ODBC Access Active Link Unvisited Link Visited Link Restrict initial index build to designer or manager Column Font properties Title properties Font Advanced properties Show values in this column as links
Comments
Special identifiers used in Domino URL commands include: $defaultView, $defaultForm, $defaultNav, $searchForm, $file, $icon, $help, $about, and $first. DominoObject can be any of the following: for a database, the database name or replica ID; for other objects, the DominoObjects name, universal ID, NoteID, or special identifier. For example, to specify a view in a URL, you can use any of the following: the view name, view universal ID, view NoteID, or $defaultView. A Notes database should be specified by placing a double underscore before the replica ID and adding an .nsf suffix to the end. For example: __852562F3007ABFD6.nsf A DominoObjects name and universal ID are identical in all replicas of a database, but the DominoObjects NoteID will probably change in database replicas. Therefore, it is best to use the DominoObject name or universal ID in URLs. One name or alias can refer to two objects for example, two forms with the same name when one is hidden from Notes users and one is hidden from Web users. Action can be explicit or implicit. Examples of explicit actions include ?OpenServer, ?OpenDatabase, ?OpenView, ?OpenDocument, ?OpenForm, and ?EditDocument. Examples of implicit actions include ?Open, ?Edit, and ?Delete. If you do not specify an action, Domino defaults to the ?Open action. An action may also be preceded by an exclamation point (!). For example, ?OpenDocument could also be written as !OpenDocument. When Domino is running as an extension to Microsoft Internet Information Server, a database is required in the URL syntax for server commands such as ?OpenServer, ?Login, ?Logout, and ?Redirect. You may use the name of a database that does not exist in order to supply the correct sytnax without opening a database. For example: http://www.mercury.com/dummy.nsf?Login To require user authentication, append the Login argument to any Domino URL. Because URLs cannot contain spaces, use the + (plus sign) as a separator. For example: http://www.mercury.com/discussion.nsf/By+Author Where a name or argument contains a symbol that is not part of the URL syntax and would conflict with URL syntax, such as plus signs (+), slashes (\ or /), or ampersands (&), use %xx (where xx is the hex ascii value) as a separator. For example: http://www.mer%+maid.com/leads.nsf/By+Salesperson?Open View&ExpandView
Separate arguments with & (ampersand). For example: http://www.mercury.com/leads.nsf/By+Salesperson?Open View&ExpandView Separate hierarchical names with / (slash). For example, to open a view named Docs\By Author in a database named Discussion, enter: http://www.mercury.com/discussion.nsf/Docs/By+Author If you are generating your own URLs for any part of an application, use simple aliases whenever possible to avoid URLs with unsupported characters. Domino will convert URLs containing unsupported non-ascii characters to base32 encoding. URL commands may also refer to databases with .nsf4 or .box suffixes. They may also refer to template files (.ntf), but they may only be opened in preview mode. Selecting Web access: Use JavaScript when generating pages in Database properties will enable you to compute URLs attached to buttons and hotspots on the Click event. If this option is not selected, URLs attached to buttons and hotspots will be computed when the page is generated. This can be useful if youre using editable fields on a form.
OpenServer
Syntax http://Host/?OpenServer http://Host/Dummy.nsf?OpenServer
Redirect
Syntax http://Server/Dummy.nsf?Redirect&Name=notesserver&Id=To=encodedurl Where: http://Server refers to the Web server which is generating the URL. Name=notesserver specifies a Domino server name in its common or abbreviated form. This is optional when the By Database setting on the server is on. ID=repid indicates the replica ID of the database to be located. This is an optional argument. To=encodedurl specifies the rest of the URL. Example http://mercury.com/dummy.nsf?Redirect&Name=Mister%2FHankey&Id =0525666D0060ABBF&To=%FAView%3FOpenView
OpenDatabase
Syntax http://Host/DatabaseFileName?OpenDatabase http://Host/__DatabaseReplicaID.nsf?OpenDatabase Examples http://www.mercury.com/leads.nsf?OpenDatabase http://www.mercury.com/sales/discussion.nsf?OpenDatabase http://www.mercury.com/__852562F3007ABFD6.nsf/OpenDatabase
OpenView
Syntax http://Host/Database/ViewName?OpenView http://Host/Database/ViewUniversalID?OpenView http://Host/Database/ViewNoteID?OpenView http://Host/Database/$defaultview?OpenView
Examples http://www.mercury.com/leads.nsf/By+Salesperson?OpenView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F300702264?OpenView http://www.mercury.com/leads.nsf/$defaultview?OpenView Optional arguments for OpenView Append optional arguments to refine the URL. Combine any of the following arguments for the desired result. Collapse = n Where: n is the row number to display in collapsed format in a hierarchical view. Do not combine this argument with the ExpandView or CollapseView arguments. CollapseView Displays the view in collapsed format Count = n Where: n is the number of rows to display Expand = n Where: n is the row number to display in expanded format in a hierarchical view. Do not combine this argument with the ExpandView or CollapseView arguments. ExpandView Displays the view in expanded format Start = n Where: n is the row number to start with when displaying the view. The row number in a hierarchical view can include sub indexes (for example, Start=3.5.1 means the view will start at the third main topic, sub-topic 5, document 1).
StartKey = string Where: string is a key to a document in the view. The view displays at that document. Examples http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&CollapseView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&ExpandView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&Start=3&Count=15 http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&StartKey=F
OpenAbout
Use the OpenAbout command to access the About This Database document. Syntax http://Host/Database/$about?OpenAbout Example http://www.mercury.com/leads.nsf/$about?OpenAbout
OpenHelp
Use the OpenHelp command to access the Using This Database document. Syntax http://Host/Database/$help?OpenHelp Example http://www.mercury.com/leads.nsf/$help?OpenHelp
OpenIcon
Use the OpenIcon command to access the database icon. Syntax http://Host/Database/$icon?OpenIcon Example http://www.mercury.com/leads.nsf/$icon?OpenIcon
OpenAgent
Syntax http://Host/Database/AgentName?OpenAgent Examples http://www.mercury.com/sales/leads.nsf/ Process+New+Leads?OpenAgent Note Agents may only be referred to by name. The use of UNID and NoteID are not supported when referring to an agent.
OpenForm
Syntax http://Host/Database/FormName?OpenForm http://Host/Database/FormUniversalID?OpenForm http://Host/Database/FormNoteID?OpenForm http://Host/Database/$defaultform?OpenForm Examples http://www.mercury.com/products.nsf/Product?OpenForm http://www.mercury.com/products.nsf/ 625E6111C597A11B852563DD00724CC2?OpenForm http://www.mercury.com/products.nsf/$defaultform?OpenForm Optional argument for OpenForm ParentUNID = UniqueIDNumber Where: UniqueIDNumber is document ID of the parent document, which is used in response forms or when the form property Formulas inherit values from selected document is selected. Syntax http://Host/Database/FormUniversalID?OpenForm&ParentUNID Example http://www.mercury.com/products.nsf/ 40aa91d55cle4c8285256363004dc9e0?Open Form&ParentUNID=6bc72a92613fd6bf852563de001f1a25
OpenNavigator
Syntax http://Host/Database/NavigatorName?OpenNavigator http://Host/Database/NavigatorUniversalID?OpenNavigator http://Host/Database/NavigatorNoteID?OpenNavigator http://Host/Database/$defaultNav?OpenNavigator $defaultNav opens the folders pane in a database.
ReadForm
Use the ReadForm command to display a form without showing its editable fields. ReadForm is useful for displaying a form as a simple Web page. Syntax http://Host/Database/FormName?ReadForm http://Host/Database/FormUniversalID?ReadForm http://Host/Database/FormNoteID?ReadForm http://Host/Database/$defaultform?ReadForm Examples http://www.mercury.com/home.nsf/Welcome?ReadForm http://www.mercury.com/products.nsf/ 625E6111C597A11B852563DD00724CC2?ReadForm http://www.mercury.com/products.nsf/$defaultform?ReadForm
URL commands for creating, deleting, editing, opening, and saving documents
The following commands manipulate documents in a database. Hidden design elements are hidden from the server, too; you cant use Domino URL commands to access documents in hidden views.
CreateDocument
The CreateDocument command is used as the POST action of an HTML form. When the user submits a form, Domino obtains the data entered in the form and creates a document. Syntax http://Host/Database/Form?CreateDocument http://Host/Database/NoteID?CreateDocument http://Host/Database/FormName?CreateDocument
Where: FormName is the name of the form being accessed. Examples http://www.mercury.com/products.nsf/ b9815a87b36a85d9852563df004a9533?CreateDocument http://www.mercury.com/products.nsf/basketballs?CreateDocument
DeleteDocument
Syntax http://Host/Database/View/Document?DeleteDocument Example http://www.mercury.com/products.nsf/By+Part+Number/ PC156?DeleteDocument
EditDocument
Syntax http://Host/Database/View/Document?EditDocument Example http://www.mercury.com/products.nsf/By+Part+Number/ PC156?EditDocument
OpenDocument
Syntax http://Host/Database/View/Document?OpenDocument Where: Document is any of the following: DocumentKey the contents of the first sorted column in the specified view. DocumentUniversalID DocumentNoteID $first the first document in the view Examples http://www.mercury.com/products.nsf/By+Part+Number/ PC156?OpenDocument http://www.mercury.com/leads.nsf/By+Rep/ 35AE8FBFA573336A852563D100741784?OpenDocument
SaveDocument
The SaveDocument command is used as the POST action of a document being edited. Domino updates the document with the new data entered in the form. Syntax http://Host/Database/View/Document?SaveDocument Example http://www.mercury.com/products.nsf/ a0cefa69d38ad9ed8525631b006582d0/ 4c95c7c6700160e2852563df0078cfeb?SaveDocument
Note that View can be a view Note ID, UNID, or view name. In addition, the implicit form of any of these commands will work when appropriate. For example, you can omit the OpenDocument argument in a URL command and the document will still open because the command is automatically interpreted as OpenDocument. (EditDocument and DeleteDocument must be explicit commands.) Examples http://www.mercury.com/register.nsf/Registered+Users/J ay+Street?OpenDocument http://www.mercury.com/register.nsf/0/ 466c5172561e1c5c852566c2005f6bbb?OpenDocument
ViewUNID can indicate a ViewID or a ViewName. DocumentUNID can be a Note ID or a DocumentKey. This allows you to create URL links to attachments by supplying a view name and document key. By default, the browser uses the name specified in the URL to save the file.
OpenPage
Syntax http://Host/Database/PageName?OpenPage http://Host/Database/PageUNID?OpenPage http://Host/Database/PageNoteID?OpenPage
Examples http://www.mercury.com/discussion.nsf/products?OpenPage http://www.mercury.com/discussion.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage Optional arguments for OpenPage and OpenDocument The following arguments will manipulate outline controls on pages and documents. The arguments for OpenPage and OpenDocument commands use the same syntax regardless of the command. CollapseOutline=n Where n = the triangle at the top level of the outline. It is possible to expand triangles in hierarchical order. For example, &CollapseOutline=2.1.3 will collapse the second triangle at the top level of the outline, the first triangle at the second level, and the third triangle at the third level. Syntax http://Host/Database/PageName?OpenPage&CollapseOutline=n http://Host/Database/PageUNID?OpenPage&CollapseOutline=n http://Host/Database/PageNoteID?OpenPage&CollapseOutline=n Examples http://www.mercury.com/sales.nsf/products?OpenPage&Collapse Outline=1 http://www.mercury.com/sales.nsf/products?OpenDocument&Collapse Outline=1 http://www.mercury.com/sales.nsf/products?OpenPage&Collapse Outline=1.2.3 http://www.mercury.com/sales.nsf/products?OpenDocument&Collapse Outline=1.2.3 ExpandOutline=n Where n = the triangle at the first level of the outline. It is possible to expand a triangle in hierarchical order. For example, &ExpandOutline=2.1.3 will expand the second triangle at the top level of the outline, the first triangle at the second level, and the third triangle at the third level. Syntax http://Host/Database/PageName?OpenPage&ExpandOutline=n http://Host/Database/PageUNID?OpenPage&ExpandOutline=n http://Host/Database/PageNoteID?OpenPage&ExpandOutline=n
Appendix E: Programming a Web Site 487
Examples http://www.mercury.com/sales.nsf/products?OpenPage&Expand Outline=5 http://www.mercury.com/sales.nsf/products?OpenDocument&Expand Outline=5 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage&ExpandOutline=5.1.2 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenDocument&ExpandOutline= 5.1.2 StartOutline=n Where n = the triangle at the top level of the outline. It is possible to expand a triangle in hierarchical order. For example, &StartOutline=2.1.3 will start the display with the third triangle at the third level of the outline. Syntax http://Host/Database/PageName?OpenPage&StartOutline=n http://Host/Database/PageUNID?OpenPage&StartOutline=n http://Host/Database/PageNoteID?OpenPage&StartOutline=n Examples http://www.mercury.com/sales.nsf/products?OpenPage&StartOutline=1 http://www.mercury.com/sales.nsf/products?OpenDocument&Start Outline=1 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage&StartOutline=5.1.2 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenDocument&Start Outline=5.1.2
URL commands for opening attachments, image files, and OLE objects
The following commands open files and objects within a document.
OpenElement
Use the ?OpenElement command to access attachments, image files, and OLE objects. Using OpenElement with attachments Syntax http://Host/Database/View/Document/$File/Filename?OpenElement Example http:/ /www.mercury.com/lproducts.nsf/By+Part+Number/SN156/$File/ spec.txt?OpenElement Note If more than one attached file has the same name, the URL includes both the internal file name as well as the external name. Since the internal file name is not easily determined, make sure all attached files have unique names. Because some browsers require that the URL end with the attached file name, Domino treats all file attachment OpenElement commands as implicit commands. For example: http://Host/Database/View/Document/$File/InternalFileName/ Filename?OpenElement Using OpenElement with image files Syntax http://Host/Database/View/Document/FieldName/FieldOffset?OpenElement http://Host/Database/View/Document/FieldName/FieldOffset?Open Element&FieldElemFormat=ImageFormat Optional argument for OpenElement FieldElemFormat = ImageFormat Where: ImageFormat is either gif or jpeg. If you do not specify FieldElemFormat, Domino assumes the image file format is gif.
Using OpenElement with OLE Objects Syntax http://Host/Database/View/Document/FieldName/FieldOffset/$OLEOBJINFO/ FieldOffset/obj.ods?OpenElement Note The current URL syntax for referencing images and objects in Notes documents specifically the FieldOffset makes it impractical to create these URLs manually. As an alternative, you may paste the actual bitmap or object in place of the reference, create URL references to files stored in the file system, or attach the files to the documents.
SearchDomain
Use SearchDomain URLs for text searches across a domain. The search input form is opened with the OpenForm command by name or universal ID. For search results, the results template is specified as part of the URL. If no template is found, then the default template form, $$SearchDomainTemplate, is substituted. If $$SearchDomainTemplate is not found, an error will be returned. If no results are returned, the value of the $$ViewBody field remains the same. Syntax http://Host/Database/[templateForm]?SearchDomain[ArgumentList] Where: templateForm is an optional argument that calls the search results form. ArgumentList is a list of optional arguments. Example http://www.mercury.com/mersrch.nsf/MercuryResults?SearchDomain
Redirect
The server will provide a direct or redirect URL command as needed for links displayed on the results form if the capability has been enabled. The domain URL locates information on the server where the links are generated. The redirect command locates the correct server and redirects a link to that server by constructing the appropriate URL. The redirect command can improve performance by resolving individual links when they are selected instead of resolving all of the links returned at once. See Domino 5 Administration Help for information about enabling a redirect URL command on a server.
SearchSite
Use SearchSite URLs for text searches in multiple databases. Because the URL requires the name of a search site database, be sure to create one before using a SearchSite URL. Syntax http://Host/Database/[$SearchForm]?SearchSite[ArgumentList] Where: $SearchForm and ArgumentList are optional arguments. Example http://www.mercury.com/mercsrch.nsf/$SearchForm?SearchSite
SearchView
Use SearchView URLs to limit a search to documents displayed in one database view. This URL is useful for views that display all documents (so you can have a full-database search) or for views in which you can predict what users need to see, such as all documents whose status is Completed. Syntax http://Host/Database/View/[$SearchForm]?SearchView[ArgumentList] Where: $SearchForm and ArgumentList are optional arguments. The special identifier $SearchForm indicates that Domino will present a search view form for search input. If this identifier is provided, the ArgumentList is ignored. If this identifier is absent, a default form will be generated on the fly based on the contents of the search.htm file located on the server. The default form generated by the server does not support paged results.
Example http://www.mercury.com/products.nsf/By+Product+Number/$Search Form?SearchView Optional arguments for SearchSite and SearchView $SearchForm The special identifier $SearchForm indicates that Domino will present a search site form for search input. If this identifier is provided, ArgumentList is ignored. The ArgumentList must contain the Query argument; in addition, it may contain any or all of the other arguments in any order. Query = the search string Count=[n] Where n is the number of results to display on each page until the SearchMax has been reached. For example Count=10 will display 10 results per page. SearchEntry = the name of the form to use for the results of a domain search. The default argument is ResultEntry, which supports all of the pre-defined results fields specified in the ArgumentList. This argument is valid for SearchDomain only and should not be used for SearchSite or SearchView. SearchFuzzy=[TRUE,FALSE] Where True = use fuzzy search. The default is FALSE. SearchOrder=[1,2,3] Where 1 = Sort by relevance, 2 = Sort by date ascending, 3 =Sort by date descending. The default is 1. SearchMax=[n] Where n is the maximum number of entries returned. The default value is determined by the server. SearchWV=[TRUE, FALSE] Where TRUE = include word variants in the search. The default value is TRUE. Start=[n] Where n is the number corresponding to the document that appears first in your list of results. For example, Start=10 begins your list of results with the 10th document found in the search. Start=0 means that paged results will not be returned.
492 Application Development with Domino Designer
Using Next and Previous buttons or hotspots with Start and Count parameters
If you are using Start and Count parameters you can include Next and Previous buttons or hotspots to enable users to navigate between pages of results. Both parameters must be used if you are using navigational buttons. 1. Open your customized results form and place buttons or hotspots labeled Next and Previous where you want them to appear on the form. 2. For the button or hotpsot labeled Next, write a formula that will advance the user forward one page. 3. For the button or hotspot labeled Previous, write a formula that will take the user back one page. Example of a formula for a Next button or hotspot @If(Hits >= Count; @URLOpen(/ + @Subset(@DbName; -1) + / + SearchView + ?SearchView&Query= + @ReplaceSubstring(Query; ; +) + &Start= + @Text(Start+Hits) + &Count= + @Text(Count) + &SearchOrder=+@Text(SearchOrder) +&SearchWV=+@If(SearchVw = 0;FALSE;TRUE)+&SearchThesaurus=+@If(SearchThesaurus = 0;FALSE;TRUE) + &SearchMax= + @Text(SearchMax)); ) Example of a formula for a Previous button or hotspot @If(Start > Count; @URLOpen(/ + @Subset(@DbName; -1) + / +SearchView + ?SearchView&Query= + @ReplaceSubstring(Query; ; +) + &Start= + @Text(Start-Count) + &Count= + @Text(Count) + &SearchOrder=+@Text(SearchOrder) +&SearchWV=+@If(SearchVw = 0;FALSE;TRUE)+&SearchThesaurus=+@If(SearchThesaurus = 0;FALSE;TRUE) + &SearchMax= + @Text(SearchMax)); ) Tip To avoid syntax errors, use @ReplaceSubstring(Query; +) to replace all of the spaces in your query with plus signs (+).
Syntax http://Host/Database/MessageForm?RequestCert&Command=Server Request&TranslateForm=TranslationFormName Where: ResultForm is a form in the specified database that displays information about the processed request in the users browser after a successful submission. TranslationFormName represents a form in the database that contains fields to hold certificate information. Example http://www.mercury.com/certs.nsf/CertificateProcessed?Request Cert&Command=ServerRequest&TranslateForm=Certificate Optional and required fields The ServerRequest command requires a translation form with a field named Certificate. Domino saves information about the server request in the document if the form contains fields with these names: CommonName Org OrgUnit Locality State Country
JavaScript
JavaScript allows you to create interactive applications that can run interchangeably on your companys intranet or on the Internet. In JavaScript, most of the information processing is done on the client side. This increases the efficiency of your applications by reducing the amount of traffic between the client and the server. JavaScript may be entered into the JS Header object on the Objects tab in the Programmers pane, as passthru HTML, or into a $$HTMLHead field. See Adding Automation to Applications for information about using JavaScript in Domino.
Perl Scripts
Domino supports programs written in Perl. Perl programs have file names that end with .pl. Place Perl programs in the cgi-bin directory. By default, Domino looks in directories that are included in the servers PATH statement for a Perl interpreter named perl.exe. To override this default, define an environment variable (PERLBIN) that gives the name or absolute path of the Perl interpreter. For example, c:\perl5\bin\perl.exe.
CGI variables
When a Web user saves a document or opens an existing document, the Domino Web server uses CGI variables to collect information about the user, including the users name, the browser, and the users Internet Protocol (IP) address. To capture this information in a Web application: Create a field with the name of a CGI variable. Create an agent whose script contains a CGI variable as a DocumentContext property.
Note If the agent runs with the WebQueryOpen or WebQuerySave form events, the document returned by DocumentContext does not automatically contain CGI variables. You must add fields with CGI variable names directly to the form to capture session information. Example: Using the DocumentContext property in Web agent scripts This script uses the Print statement and the CGI variable remote_user to display User = and the Web users name. The script sets the DocumentContext before executing the rest of the script. The variable assumes a text list.
Dim session As New NotesSession Dim doc As NotesDocument Set doc = session.DocumentContext Print "User = " + doc.remote_user(0)
Content_Length Content_Type
Path_Info_Decoded
Path_Translated
Query_String Query_String_Decoded
Returns The IP address of the remote host making the request. The name of the host making the request. This variable will be set to the remote user name retrieved from the server. Use this variable only for logging. Authentication method that returns the authenticated user name. Supported only for agents. Contains the data sent with an HTTP POST request. The data is usually URLencoded, consisting of name=value pairs concatenated by ampersands. For example, FirstName=John&LastName=Doe The method used to make the request. For HTTP, this is GET, HEAD, POST, and so on. A virtual path to the script being executed, used for self-referencing URLs. The servers host name, DNS alias, or IP address as it would appear in self-referencing URLs. The name and revision of the information protocol accompanying this request. The port to which the request was sent. The name and version of the information server software running the CGI program. The version of the CGI spec with which the server complies.
Remote_User Request_Content
*If your Domino server is configured to allow search engines to search your Web site, Domino will generate URLs with an ! (exclamation point) instead of a ? (question mark). If this is the case the Query_String CGI variable includes the information that follows the exclamation point. Domino always recognizes both the question mark and the exclamation point, but only generates URLs with the exclamation point if your site is accessible to Web search engines. Generating URLs with an exclamation point makes them more searchable.
Index
Symbols
$$fields $$Return, 112 $$ViewBody, 490 listed, 161, 394 @commands for application automation, 294 Programmers pane and, 5 referencing, 146 Web use of, 23, 497 @Db commands @DbColumn, 140, 430 @DbCommand, 430 @DbLookup, 140, 430 described, 425 $fields $Anonymous, 359 $HLFormula field, 144 $PublicAccess, 360 $title, 83 $UpdatedBy, 359 $VersionOpt, 162 listed, 161 @functions @DialogBox, 108 @PickList, 110 @Prompt, 109 for date and time calculations, 133 for external data access, 140 Programmer's pane and, 5 referencing, 146 using, 211 Web, 463, 497
A
About This Database document creating, 377 inheriting from template, 399 launching, 26 OpenAbout command, 480 Access database, 48, 349 defined, 347 documents, 351 folders, 351 forms, 353, 354 outlines, 46 restricting through outline settings, 48 sections, 369 views, 351 Access Control List. See ACL Access levels list of recommended, 389 Access list, 355 Accessibility for users with disabilities, 35 Accessing data. See Data access ACL access levels, 389 agent security and, 275 CGI and, 498 copying from template, 19 database, 349 URL commands and, 494 using to enter names, 137, 139 Web previewing and, 38 Action bar described, 257 Action bar applet, 22, 257 Action buttons and screen readers, 36 creating, 253 Action hotspots creating, 265 defined, 248 deleting, 265 editing, 265 hiding, 265
Numbers
1-2-3 files importing into views, 445
Actions adding, 220 built-in, 247 changing automation for, 254 copying, 254 creating, 253 creating hotspots for, 265 deleting, 254 described, 13, 246 displaying as buttons, 253 editing, 259 examples, 247 inserting, 258 menu, 254 naming, 300 navigator, 230 OLE and, 340 publishing, 326 shared, 31, 258 simple, 246 URL commands and, 476 using to simulate Notes menus, 254 Web, 464 Actions field, 394 Actions menu described, 254 ActiveX defined, 326 Address Book provider Domino Directory and, 455 Address lookups in multiple Domino Directories, 455 Agent Log described, 279 size limit, 284 Agent Manager described, 249 recording less information, 283 setting up debugging, 278 AgentRunner described, 284 Agents, types of built-in, 249 embedded, 277
Index 503
foreground or background, 276 local or server, 276 LotusScript and Java, 274 public access, 360 Agents, uses for adding fields with, 395 editing documents with, 395 hiding design with, 409 mail responses, creating, 422 mailing with, 422 removing field data with, 395 removing stored forms with, 396 renaming fields, 396 resaving documents with, 395 Agents, working with Agent Manager debugging, 282 automated components of, 268 calling, 254, 262, 277 chaining together, 289 compared to servlets and CGI programs, 432 copying, 268 creating, 267 debugger settings, 280 debugging, 277 deleting, 268 described, 13, 248 disabling, 268 enabling, 272 examples, 272 finding creator of, 276 invoking, 433 naming, 300 properties of, 432 renaming, 391 replication conflicts and, 271 run-time statistics, 281 run options, 269 running, 254 running on the Web, 500 scheduling, 267 security, 273, 434 simulating a run, 277 specifying servers for, 267 uses for, 432 viewing, 249 viewing the log, 279 Web and, 464 Aliases action names, 300 agent names, 300 choice list, 140
converting to full names, 141 form names, 87 servlet names, 437 view names, 181 All by Category view, 186 Alternate HTML, 309 Alternate text tag for images and Java applets, 35 Annotating applications, 381 documents, 95 fields, 380 Anonymous forms, 90 Anonymous field, 359 AppletBase extending, 315 Applets action bar, 257 adding to a page or form, 70 BeanMachine and, 304 described, 431 editor, 126 Java, 303 listed, 22 outline, 51 servlets and, 431 view, 216 Applications annotating, 381 automating, 245, 340 completing, 375 deploying, 383 documenting, 377 mail-enabled, 414 master design copies, 383 overview of Domino, 1 previewing, 37 security for, 347 setting launch properties for, 25 testing, 389 Asterisks as passwords, 142 Attaching signatures, 368 Attachment fields Web and, 25 Attachments creating, 71, 102 displaying information about, 197 on pages and forms, 71
opening with URL commands, 487 Attributes HTML, 156 Authentication certificates and, 350 URL commands and, 494 Authors anonymous, 90 displaying names, 197 Authors field creating, 351 described, 356 restricting read-access with, 356 Autolaunching defined, 331 examples, 334 objects, 74, 325 Automating applications, 340 described, 13, 245 formulas for, 294 hiding components, 302 JavaScript and, 295 navigators, 234 replies, 422 security features and, 294 using LotusScript, 291 Averages calculating, 206
B
Background processing on Web pages, 498 Backgrounds for pages and forms, 68 Base class property for Java applets, 310 Billing forms for, 111 reserved fields for, 160 Bitmap graphics. See Graphics Blank databases, 20 BMP files. See Graphics Body field, 160, 394 Borders for frames, 170 Browsers proxy settings for, 39 setting up for previewing, 39 using Print statement to instruct, 291
Button bar, 257 Buttons creating, 261 customizing, 258 defined, 248 deleting, 261 editing, 261 examples of, 262
C
CAB files, 306 Calculating cell values, 206 field values, 128, 196 values for computed fields, 146 Calendar controls adding to a page or form, 72 creating, 134 Web use of, 465 Calendar views creating, 177, 465 defined, 173 using with the group scheduler, 102 Cascading action names, 301 agent names, 301 form names, 87 view names, 183 Cascading Style Sheet. See CSS Catalog database, 349 Categories adding to views, 185, 187 columns, 187 field for creating, 161, 187 formulas for, 187 naming, 187 subcategories, 188 Categorized view aliases and, 141 Categorizing by users, 185, 188 documents, 186 Category fields, 187 cc:ing. See Forwarding, Routing cc:Mail mailing to, 419 Certificates, SSL, 494 CGI defined, 498
CGI programs compared to servlets and agents, 432 invoking, 433 properties of, 432 security for, 434 uses for, 432 CGI variables agents and, 500 fields and, 499 table of, 500 user profiles and, 499 Character translation file, 444 Checkbox fields aliases in, 140 creating, 137 in Web applications, 465 Choice list fields aliases in, 140 creating, 137 refreshing, 151 views and, 110 Choices displaying in lists, 110, 137 refreshing, 152 Class name, 305 Classes CSS, 28 Notes, 314 CLS files, 444 CodeBase property for Java applets, 310 COL files creating, 448 defined, 448 for importing a tabular text file, 450 formulas and, 449, 452 guidelines, 449 keywords, 449 Collapsing columns, 197 sections, 369 views, 207 Color palettes changing, 21 for choosing colors, 64 using to blend colors, 31 Colors blending with user's system, 33 for columns, 207
for frame borders, 171 for navigators, 233 for outline entries, 50 for rows, 207 for unread marks, 222 for views, 207 for Web applications, 21 palettes for, 64 Column descriptor file. See COL files Column width, 450 Columns adding to views, 180 calculating values in, 206 categorized, 185 collapsing, 197 copying, 179 date, 223 deleting, 179 entering names from, 139 expanding, 197 formatting, 223 hiding, 207 HTML and, 205 icons in, 200 linking to documents, Web, 205 mapping to fields in views, 448 numbers, 224 programming, 194 referred to in formulas, 211 response, 214 specifying data type in views, 449 styling, 207 switching to a view, 205 testing, 387 time, 223 titles for, 184 views and, 10, 173 width, 207, 451 Combobox fields aliases in, 140 creating, 137 Common Gateway Interface. See CGI Common name displaying, 136 Compatibility with previous releases, 304 See also Release 4; Upgrading Components sizing, 330 using, 326
Index 505
ComposedDate field, 160 Compression. See Zip files Computed fields CGI programs and, 499 defined, 146 examples, 150 order of evaluation, 85 Computed for display fields, 147 Computed text, 58 Computed when composed fields, 147 Conflict documents, 90 See also Replication conflicts Console commands, 280 Controls calendar, 72, 102, 139 date/time, 133 embedded, 102 Cookies, 75 Copy Java applet, 313 CORBA properties for Java applets, 310 CORBA SSL security for Java applets, 311 Count parameter Domino URL commands and, 490 search results and, 494 Create menu documents and, 87 CreateDocument command, 483 CSS class and objects, 28 described, 28 passing information, 162 styles applied to objects, 28 Currency fields for, 128 formatting in columns, 224 formatting in Number fields, 128 Custom controls adding to forms, 328 described, 326 read-mode and, 331 running, 331 sizing, 330 updating, 331 Customizing databases, 17 sorting order for columns, 204 templates, 398 window titles, 95
D
Data access with @DbColumn and @DbLookup, 140 with Domino Connectors, 426 with Lotus Enterprise Integrator, 426 with ODBC, 428, 429 with servlets, 431 Data entry fields for, 146 Data types. See Field types Database icons creating, 376 replacing, 406 Database management shared resources and, 30 stored forms and, 82 Database synopsis, 391 Databases See also Applications access control lists, 349 access to, 349 agent access, 275 blank, 20 connecting to, 425 copying, 18 creating, 16, 402 creating a test copy, 278 default views, 210 defined, 2 documenting, 377 external, 428 hiding, 411 icons, 481 launch properties, 25 launching into framesets, 172 linking, 402 mail features and, 417 naming, 18 ODBC and, 428 previewing, 27 properties, changing, 23 renaming, 391 replacing design of, 406 response forms, 92 restricting creation of new, 275 SSL protected, 350 summary, 391 titles for, 17 unlinking, 409 URL commands and, 477
Datalens ODBC and, 429 Date/Time controls, 133 Date/Time fields described, 129 examples, 135 Date picker adding to a page or form, 72 in Web applications, 465 Date separator, 130 Dates calculating by formula, 133 columns for, 223 displaying, 223 entering, 129, 133 formatting, 130, 132, 223 stored as seconds, 136 Debug_AMgr statement, 282 DEBUG_OUTFILE statement, 283 Debugging agents, 277 Java applets, 320 NotesLog class, 283 Decimal places in Number fields, 129 Decimal symbol, 129 Decrypting documents, 363 DECS described, 425 Default active field, 153 encryption, 365 field values for editable fields, 148 headers and footers, 92 views, 210 DeleteDocument command, 483 Deploying applications, 383 Design action buttons, 4 Design bookmarks icons, 4 Design changes making, 403 preventing in image resources, 32 templates and, 17 Design elements automating, 266 copying, 18 hiding, 411 linking, 402 listed, 2 named, 260 previewing, 37
protecting, 408 templates and, 402 updating, 404 Design list, 4 Design pane, 4 Design synopsis creating, 391 described, 14 Designer starting, 3 work area overview, 4 Designs changing, 407 default, 181 hiding, 18, 409 linking, 402 maintaining, 388 preventing changes, 383 refreshing, 404 replacing, 406 replication and, 407 synopsis of, 391 templates and, 397, 409 testing, 385 unlinking, 409 updating, 404 Details. See Expanding Dialog boxes creating, 108 designing, 109 displaying, 337 Dialog forms, 108 Dialog list fields, 137 Discussion template, 16, 441 DocBase property for Java applets, 310 Doclinks. See Links Document Library template, 442 Document Object Model, 5 Document Save dialog box overriding options, 419 Document selection formula, 189 DocumentContext property in Web agent scripts, 500 Documenting applications, 377 fields, 380 Documents About This Database, 377 accessing, 351, 356 agent access, 275 agents and, 395 annotating context of, 95 anonymous, 90
calculating age of, 135 categorizing in views, 186 conflict, 90 copying, 287 copying from templates, 19 creating, 87, 483 decrypting, 363 deleting, 287, 483 displaying in views, 189, 194, 196, 197 editing, 395 footers, 92 form redesign and, 393 forms and, 81 headers, 92 help, 381 hiding, 337 launching, 378 launching as dialog boxes, 337 launching into framesets, 172 linking in workflow applications, 415 mailing, 290, 417 marking read or unread, 287 modifying, 156, 380, 395, 483 moving, 289 opening by key, 485 previewing, 27 profile documents, 106 public, 360 reassigning to forms, 396 removing form from, 396 resaving, 395 response, 92 security for, 351, 355, 356, 361, 368 sending summary, 290 sorting in views, 201 storing forms with, 162 tracking, 111 unread, 222 updating, 393 URL commands and, 484, 485 Using This Database, 377 version tracking, 93 viewing deleted, 178 views and, 186, 189, 194, 195, 197, 201 Web, 87 Domains searching, 490 Domino-generated fields. See Reserved fields
Domino Connectors described, 426 Domino Directory accessing, 455, 457 Address book provider and, 455 using to enter names, 139 Domino Directory Server document servlet manager settings, 435 Domino Global Workbench, 27 Domino Java Virtual Machine (JVM), 435 Domino Servlet Manager, 434 Domino URL commands authentication and, 494 count parameter, 493 implicit and explicit, 486 maximum size, 475 opening documents by key, 485 server commands, 477 ServerRequest, 496 start parameters, 493 syntax, 475 DominoObject in URL commands, 476 Duration controls creating, 135 in Web applications, 465 setting separator for, 155
E
ECL setting up for secure Java applet access, 314 Edit mode for forms and documents, 90 hidden data in, 29 Editable fields defined, 146 EditDocument command, 483 Editing documents, 395 fields, 360 forms, 393 images with the editor applet, 467 navigators, 230 restricting, 356 URL commands and, 484 window titles, 95 Editor applet described, 22 using, 126
Index 507
Editors anonymous, 90 sections and, 369 tracking, 359 E-mail. See Mail Embedded controls date picker, 72 file upload control, 102 forms and, 102 group scheduler, 102, 465 Embedded elements group scheduler, 102 keyboard accessibility and, 36 pages and, 71 reserved fields for, 160 Embedding defined, 327 folders, 219 navigators, 215, 240 objects, 325 outlines, 45, 46 views, 215, 218 Enabling editor applet, 127 encryption, 365 Notes/FX, 343 Encapsulated documents, 419 Encryption default, 365 defined, 361 enabling, 365 examples, 143, 363 fields, 363, 365 Encryption keys creating, 364 defined, 361 examples, 367 fields for, 160, 366 listing, 366 password fields and, 143 secret, 161 Entry helper button, 138 ERP systems connecting to, 425 Error executing agent error message, 284 Events agent, 252 calendar view, 251 click, 252 database, 250 described, 249 examples, 266 field, 252
folder, 251 form, 251 page, 75 programming, 250 view, 250 Examples access, 358 actions, 256 agents, 422 autolaunching, 334 automating navigators, 236 buttons, 262 choice list field generation, 140 columns, programming, 195 computed fields, 150 customizing window titles, 96 Date/Time fields, 135 default value formulas, 149 displaying documents in a view, 190 encryption, 363 encryption keys, 367 events, 266 exchanging data, 344 fields, 344 fields that control mailing options, 420 hiding, 339 hotspots, formula pop-up, 264 hotspots, text pop-up, 263 inheriting information, 158 input translation formula, 150 Java servlet, 439 links, 261 password fields, 142 restricting access, 352 routing review requests, 413 security, 358 servlet, 439 servlets.properties file, 439 templates, 399 Excel files importing and exporting to, 443 Exchanging field data, 342 Execution Control List. See ECL Expanding columns, 197 sections, 369 views, 207, 479 Exponential notation, 129 Exporting from views, 452 Java applets, 314
External database access with Domino Connectors, 425 with Lotus Enterprise Integrator, 425 with ODBC, 428, 429 ExternalData parameter in Java applets, 317 Externalization for Java applets, 317
F
Field-exchange. See Notes/FX, Notes Flow Field data deleting from documents, 122 reassigning, 123 shared fields and, 124 Field formulas creating, 146 described, 148 Field help writing, 380 Field label defined, 124 Field names described, 124 requirements for, 124 Field types defined, 121 list of, 125 listed for choice list fields, 138 Field values calculating, 146, 196 default for editable fields, 148 displaying, 194, 394 Fields, types of Authors, 351, 356 Category, 187 checkbox, 138 choice list fields, 138 combobox, 138 computed, 85, 146 computed for display, 147 computed when composed, 147 Date/Time, 129 dialog list, 138 editable, 146 embedded elements, 160 for data entry, 146 Formula fields, 144 hidden, 90 HTML, 157 listbox, 138 mail-enabling, 160
Names, 136 Numbers, 128 Password fields, 142 Radio button, 138 Readers, 351, 355 reserved, 160, 394 Rich text, 126 shared, 122 Text, 126 Fields, working with adding to existing documents, 395 annotating, 380 CGI variables and, 499 copying, 122 creating, 121, 342 default active, 153 default values for, 128, 148 defined, 81 deleting, 122 described, 121 editing, 360 encrypting, 363 examples, 344 exchanging data in, 326 formulas, 148 hiding, 61, 153, 154 HTML attached to, 156 inheriting documents in, 158 inheriting values in, 158 layout regions and, 155 modifying, 288 naming, 124 recalculating computed, 148 renaming, 125, 396 replacing field values, 288 resizing, 156 setting input validation formula, 148 setting translation formula, 148 shared resources as, 31 signing, 368 Web and, 465 File field, 394 File formats importing from and exporting to views, table for, 443 File upload control, 102 Flat style outline, 48 Floating point arithmetic, 129 Folder pane, 11 described, 41 embedding, 219 FolderOptions field, 164
Folders access to, restricting, 351 adding documents to, 161, 164 copying documents to, 287 creating, 227 defined, 227 embedding, 219 hiding, 351 MAPI Folder Interface and, 456 removing documents from without deleting, 287 security, 353 Web, 227 Fonts applying to text, 57 changing in a form, 58 Footers creating, 92 Foreign language applications designing for, 27 Foreign symbols translating, 444 Form buttons creating multiple on Web, 23 Form elements listed, 80 Form processed confirmation, 112 overriding, 162 Formatting columns, 223 dates, 223 HTML, 156, 210 numbers, 224 text, 57 times, 223 views, 210 Forms, types of anonymous, 90 billing, 111 dialog, 108 customized results forms, 493 Domain Search forms, 113 profile forms, 106 response, 92 version tracking, 94 Forms, working with access lists and, 351 Authors fields on, 351 autolaunching and, 332, 336 choices on, 110 compared to pages, 53, 79 copying, 84 creating, 79, 84, 360 default form selection,
overriding, 83 deleting, 84 described, 79 designing, 85, 332 designing prompts, 109 dialog boxes as, 108 displaying as Web page, 483 displaying documents with forms, 82 displaying without editable fields, 483 edit mode, 90 embedded controls on, 102 embedded navigators and, 241 embedding objects in, 327 examples, 344 field-exchange in, 326 footers on, 92 headers on, 92 hiding, 88 improving performance of, 118 launching an OLE object, 333 linking objects in, 327 naming, 86 navigators and, 228 objects and, 325 OLE and, 328 Readers fields on, 351 redesigning, 393 removing, 396 renaming, 391 replication and, 90 restricting access to, 355 storing, 396 storing with documents, 82, 162 templates and, 160 testing, 119, 384 Web applications and, 466 Web users access to, 89 window titles, 95 Formula fields described, 144 programming, 144 Formula language in Web applications, 497 Formula pop-ups creating, 263 defined, 248 deleting, 263 editing, 263 Formulas COL files and, 452 columns and, 194 creating, 263
Index 509
deleting, 263 dialog box, 108 editing, 263 entering in the Script area, 5 field, 146 for automating applications, 294 input translation, 146, 148 input validation, 146 literalizing, 144 lookup, 211 prompting users, 109 providing Web navigation with, 220 view, 189 Forwarding documents, 417 restricting, 355 Frames borders for, 167, 170 described, 165 in Web applications, 468 naming, 168 scroll bar for, 171 sizing, 170 specifying a target frame, 169 Framesets content for, 168 creating, 166 defined, 12, 165 keyboard accessibility and, 36 launching automatically, 165 opening with URL commands, 481 outlines and, 52 From field, 160 Full-text index copying settings, 18
choosing colors for, 64 copying, 232 creating, 66 database management and, 31 design tools for, 231 dynamic, 32 hiding, 32 importing, 232 layout regions and, 101 navigators and, 231 pasting, 232 shared resources, 30 text over, 155 Gray scale using to blend colors, 33 Group calendars in Web applications, 465 Group scheduler using, 102 Guides. See Outlines, Navigators
H
Headers creating, 92 Headlines database described, 144 subscriptions and, 30 Help creating, 377 displaying, 328 writing, 380 Hide-when conditions CGI fields and, 499 field settings, 154 options, setting, 29 Hiding automated components, 302 button hotspots, 261 columns, 207 databases, 411 design elements, 29, 411 designs, 18, 409 documents, 337 examples, 339 fields, 61, 153, 154 folders, 351 formula pop-ups, 264 graphics, 32 Java applets, 311 link hotspots, 260 menu choices, 239 objects, 339 outline entries, 47
G
getCodeBase in Java applets, 323 getDocumentBase in Java applets, 322 GIF files. See Graphics Global Workbench. See Domino Global Workbench Graphical date/time controls, 133 Graphics adding to navigators, 231 adding to outline entries, 46 alternate text for, 35 backgrounds, 68 changing when moused over, 33
paragraphs, 153 section titles, 369 servlet names, 438 subforms, 97 text pop-ups, 263 views, 183, 221, 239, 351 Hierarchy. See Expanding views, Response documents Hierarchical name displaying as common name, 136 Home pages creating, 53 defined, 56 launching, 56 specifying, 382 URLs, 382 Horizontal rules creating, 59 in Web applications, 469 Host forms, 108 Hotspots action hotspot, 265 and imagemaps, 69 button hotspot, 261 creating, 234 defined, 13, 234 examples, 248 formula pop-up hotspot, 263 link hotspot, 260 navigators and, 234 text pop-up hotspot, 262 URLs in, 260 Web applications and, 469 HTML adding, 205 alternate text tag, 35 attributes, 156, 309 columns and, 205 core attributes, 28 displaying information with Print statement, 291 field, 157 formatting, 156, 210 generating for hidden fields, 91 on pages and forms, 73 passing to server, 162 referencing objects with JavaScript, 28 tag attributes, 28 viewing frameset source, 167 views and, 210 HttpSession instance, 436
I
Icons creating database, 376 displaying in columns, 200 Image files, 489 Image resources as dynamic graphic, 32 changing, 34 creating, 32 described, 30 inserting, 34 maintaining, 31 sharing among databases, 34 Image set described, 32 Imagemaps described, 69 Images. See Graphics Imperial measurement, 129 Importing column format, 444 documents, 444 files into views, 443, 452 foreign characters and symbols into views, 444 graphics, 232 Java applets, 305 lines per page, 446 navigators, 241 Indenting documents, 196 response documents, 213 Indexes deleting, 225 refreshing, 225 settings, copied, 18 view, 225 Info field, 394 Infoboxes. See Dialog boxes, Properties boxes Inheriting creating fields for, 158 documents in fields, 158 field values, 149 related documents, 93 subjects in a response hierarchy, 159 Input forms, 108 Input translation formulas defined, 148 example, 150 settings for field, 148
Input validation formulas defined, 148 Inserting subforms, 98 International characters displaying on the Web, 127 in Web applications, 467 Items. See Field data
J
JAR files, 306 Java servlets, 431 Java applet properties Base class, 310 CodeBase, 310 CORBA classes, 310 CORBA SSL security, 311 DocBase, 310 Size, 310 Java applets alternate text for, 35 as shared resource, 31 BeanMachine and, 304 compared to servlets, 431 copying, 313 debugging, 320 deleting, 313 Domino, listed, 22 enabling on workstation, 304 exporting, 314 hiding, 311 importing, 305 linking to, on the Web, 306 overview, 303 pages and, 70 parameters, 307 persistence for, 317 refreshing, 314 requirements for, 304 running, 308 security, 314 selecting, 313 serialization, 319 servlets and, 431 setting HTML attributes, 309 shared resources, 312 starting, 313 stopping, 313 storing files for, 304 Troubleshooting, 320 Web and, 22 Web applications and, 498
Java compiler, 434 Java Debug Console, 320 Java programs creating for agents, 299 editing and the Reference tab, 5 importing into agents, 299 restricting use in agents, 274 servlets, 431 storing, 31 using for data access, 426 Java servlets, 434 JavaScript, 75 automating applications with, 295 editing, and the Reference tab, 5 table of supported objects, 296 Web applications and, 498 JavaScript code passing, 162 JavaScript header for pages and forms, 75 JDBC using for data access, 426 JPEG graphics. See Graphics
K
Keyboard accessibility, 35 Keyboard shortcuts and form names, 87 Keys. See Encryption keys Keywords COL files and, 449 See also Choice list fields
L
Labels fields, 124 Language preference setting, 27 Launch properties for pages or forms, 74 Launching databases, 25 databases into framesets, 172 documents, 378 documents or pages into framesets, 172 framesets, 165 home pages, 56 links, 26 objects, 74, 325
Index 511
pages, 26 target frames and, 169 Layout regions changing, 100 defined, 81 described, 99 fields in, 155 graphics in, 101 read access, 29 unsupported features, 138 Legacy databases connecting to, 425 Legend group scheduler, 105 Levels. See Expanding views, Response documents Line wrap in Web views, 175, 185 Linking columns to documents, 205 databases, 402 design elements, 402 designs, 402 documents, 415 mail, 415 objects, 325 templates and, 402 Links creating, 127, 260 defined, 247 deleting, 260 displaying, 205 editing, 260 launching automatically, 26 on pages and forms, 62 sending, 415 target frames and, 169 Links field, 394 Listbox fields aliases in, 140 creating, 138 Lists of choices displaying, 110 Login argument, 494 command, 477, 494 URL command guidelines, 476 Logout command, 477 Lookup formulas, 211 Lookup options for names, 136 Lookups creating, 111 view lookups, 137, 139, 141
Lotus components using, 326 Lotus Enterprise Integrator described, 426 Lotus palettte grays, 33 See also Color palettes LotusScript browser window, 5 debugger, 278 for application automation, 291 OLE and, 327 restricting use in agents, 274 storing programs, 31 using for data access, 426 Web agents and, 500 Web and, 464 LS:DO using for data access, 425
M
Macros. See Agents Mail agents, 422 applications, 414 automatic, 415 changing default font of, 58 fields, 418 fields for automatic, 417 fields for enabling, 160 forwarding, 417 in workflow applications, 414 linking, 415 MAPI classes and methods, 459 sending, 416, 419 Mail-in Database agents and, 422 creating, 421 Mail-in Database Document described, 421 Mail file accessing, 455 Mail integration overview, 455 Mail messages delivery, 456, 457 MAPI, 457, 459 non-Notes, 457 Mail option fields examples, 420 Mail queue outgoing, 456 Mail router, 457
Mail Send dialog box overriding choices, 419 Mail template changing fonts in, 58 MailFormat field, 419 Mailing documents, 416 Main class name, 305 MAPI Address Book provider, 455 classes and methods, 459 defined, 455 Message Store provider, 456 Message Transport provider, 457 overview, 455 platforms, 457 recipient types, 457 requirements, 457 service providers, 455, 456, 457 spooler, 457 MAPI Folder Interface and folders, 456 Maps. See Outlines, Navigators Master design copies creating, 383 Menu bar, 4 Menus actions, 254 displaying, 328 hiding choices, 239 shortcut keys and, 301 simulating for Web users, 254 Message sorting arbitrary, 456 Message store provider described, 456 Message Transport provider address type and, 457 message type and, 457 Messages delivery of, 456 MAPI classes and methods, 459 See also Mail Messaging application program interface (MAPI) Address Book provider, 455 classes and methods, 459 Message Store provider, 456 Message Transport provider, 457 overview, 458 platforms, 457 requirements, 457 service providers, 455, 456, 457 spooler, 457
Meta data passing, 162 Metric measurement, 129 Microsoft files importing into views, 445 Microsoft Internet Information Server (MIIS) server commands, 476 Microsoft Office Library template, 442 Mouse-over image creating, 33 Multilingual applications designing for, 27 settings for, 27
N
Named elements defined, 260 Names cascading, 301 displaying, 136 entering from a list, 136 Names dialog box displaying, 137 Names fields described, 136 in Web applications, 465 Naming categories, 187 databases, 18 forms, 86 frames, 168 framesets, 167 views, 181 Native controls, 152 Navigating Web sites, 215, 240 Navigation pane. See Folder pane Navigator templates forms as, 228 Navigators. See also Outlines actions in, 230 automating, 234 color, 233 creating, 229 designing, 229 displaying, 239 editing, 230 embedding, 240 examples, 236 formulas and, 235 graphics and, 231
highlighting, 233 hotspots and, 234 imagemaps and, 69 importing, 241 opening, 239 programming, 230 renaming, 391 scripts and, 235 styling, 233 templates and, 228, 241 testing, 242 text on, 233 Web, 228, 229, 469 web applications and, 229 Notes/FX. See also Notes Flow enabling, 343 in Web applications, 465 setting up, 342 using, 342 NOTES.INI recording debugging information, 283 NOTES.INI settings Default_Index_Lifetime_Days, 225 Notes Browser previewing in, 37 Notes classes setting up applet access to, 314 Notes Client designing for Web and, 21, 90, 127, 157 launch options, 25 search forms and, 113 NotesFlow. See also Notes/FX actions, 326 applications, 325 field-exchange, 326 NotesLog class debugging setting up, 283 Notes Mail. See Mail NotesSession class, 500 NSF files copying, 18 creating, 20 NTF files creating, 388 defined, 16, 397 using, 16 Number fields described, 128 Numbering documents in views, 194
O
Object parameter in Java applets, 319 Objects autolaunching, 331 drawing, 232 embedding, 327 enhancing, 233 hiding, 339 hotspot, 234 launching, 325 linking, 327 referencing with JavaScript, 28 resizing, 329 updating, 331 viewing properties and events of, 5 Objects tab, 5 OCX. See Custom controls ODBC data sources, 429 Datalens and, 429 described, 425 using, 428 OLE actions and, 340 applications, 325 autolaunching objects, 336 automating, 340 custom controls, 327 exchanging data, 342 launching objects from a form, 333 launching objects in-place, 335 LotusScript and, 327 publishing actions using, 341 resizing objects, 329 Web and, 325 OLE custom controls. See Custom controls OLE objects autolaunching, 330, 333, 338 launching, 329 opening with URL commands, 489 OpenAbout command, 480 OpenAgent command, 481 Web agents and, 500 OpenDatabase command, 477
Index 513
OpenDocument command, 484 OpenElement command, 489 OpenForm command SearchDomain and, 490 SpecialAction argument and, 495 OpenFrameset command, 481 OpenHelp command, 480 OpenIcon command, 481 OpenPage command, 486 OpenServer command, 477 OpenView command, 477 optional arguments, 479 Ordered lists in Web applications, 467 Outbox folder transferring responses and, 456 Outline applet, 51 described, 22 Outline entries adding graphics to, 47 customizing, 46 described, 42 displaying as a hierarchy, 47 hiding, 47 styles for, 50 Outline views defined, 173 described, 174 Outlines creating, 42 described, 11, 41 designing, 41 displaying in framesets, 52 embedding, 45, 46 styles for, 50 Web users access to, 51 Overriding, 112 default form selection, 83 Form processed confirmation, 162 proxy settings for previewing, 39
P
Page breaks in views, 210 Pages backgrounds for, 68 compared to forms, 53 defined, 53, 74 elements on, 53 embedding controls on, 71 events for, 75 fonts in, changing, 58
graphics on, 66 HTML and, 73 Java applets and, 70 launching, 26 launching into framesets, 172 links and, 62 opening with URL commands, 486 programming, 75 styling text in, 57 Palettes for choosing colors, 64 grays, 33 using to blend colors, 31 Parallel reviews in workflow applications, 413 Parameters setting for Java applets, 307 Password fields described, 142 Passwords URL commands and, 494 PCX graphics. See Graphics Percentage calculating, 206 formatting numbers as, 129 Performance forms and, 85, 118 computed fields and, 147 group scheduler and, 105 headline monitoring and, 30 improving on Web, 24 lookups and, 140 stored forms and, 82 Perl script Web applications and, 498 Persistence Java applets, 317 session, 436 Personal Address Book using to enter names, 139 Personal agents controlling, 274 creating, 267 defined, 249 Web users and, 274 Personal views. See Private views Personal Journal template, 442 Pictures. See Graphics Pop-up calendar controls, 465 Pop-ups formula, 263 text, 262
Precision in Number fields, 129 Predefined fields list of, 160 Preview icons, 4 Previewing applications, 37 databases, 27 documents, 27 framesets, 167 hiding information during, 153 Notes client vs. Notes Browser, 37 setting up, 39 Printing headers and footers, 92 hidden information, 29, 154 restricting, 355 Private views, 178 Profiles creating user, 106 Programmable tables, 60 Programmer's pane, 5 Programming columns, 194 formula language in Web applications, 497 JavaScript in Web applications, 498 navigators, 230 Perl script in Web applications, 498 views, 477 Visual Basic script, 498 Programs creating for events, 266 Projects creating, 284 Prompts creating, 109 displaying, 109 Properties action hotspots, 265 changing, 23 changing database and design element, 23 for Java applets, 310 Properties boxes described, 6 Protecting anonymity, 90 design elements, 408 designs, 408
Proxy settings for previewing in browsers, 39 Public access agents, 360 defined, 360 described, 46 documents, 360 forms, 360 framesets and, 167 outlines, 46 views, 360 PublicAccess field, 360
R
Radio button fields, 137 RANGE statement, 450 Read-mode custom controls and, 331 Read access layout regions and, 29 restricting, 354 Read access list folders, 351 forms, 353, 354 views, 351 Readers field, 394 Readers fields creating, 355 described, 351 ReadExternalData parameter in Java applets, 317 ReadForm command, 483 Reading restricting, 353 Redesigning forms, 393 templates, 398 Redirect command, 477 domain search and, 490 Reference list using, 146 Reference tab, 5 Refreshing, 148 choice list field values, 152 defined, 404 designs, 406 field values, 146, 152 Java applets, 314 views, 225 Relational databases accessing with ODBC, 428 connecting to, 425
Release 4.5 attachment fields, 25 Release 4.6 hiding paragraphs from, 153 URL generation, 25 Reloading. See Refreshing Renaming agents, 391 databases, 391 fields, 125, 396 forms, 391 navigators, 391 shared fields, 123 views, 181, 391 Replace Design command defined, 406 Replication disabling, 349 forms and, 90 templates and, 407 Replication conflicts and agents, 269, 271 Replies automating, 422 Report on database design, 391 Reserved fields $Anonymous, 359 $PublicAccess, 360 $UpdatedBy, 359 list of, 160, 394 Reserved form names for navigator or view templates, 228 Resources. See Shared resources Response documents, 92 columns for, 214 displaying, 197 indenting, 213 inheriting subject, 159 limits on, 181 Response forms, 92 Restricting. See also Security access, 347 copying, 355 design changes, 383 editing, 356 examples of, 358 forwarding, 355 printing, 355 reading, 353, 354 Review requests in workflow applications, 413, 442
Revision tracking, 93 Revisions field, 39 Rich text fields, 126 on Web, 126 Rounding in Number fields, 129 Route. See Outlines, Navigators Routing automatically, 414 Rows opening to, 210 spacing, 207 styling, 207
S
SaveDocument command, 485 Schedules coordinating, 102 Scientific notation, 129 Screen-reader software designing for, 35 Script area, 5 Script libraries defined, 31 Scripts creating, 266 deleting, 266 Scroll bars for frames, 171 Search forms, 113 SearchDomain command, 490 SearchEntry, 491 Searches displaying results, 493 navigating through paged results, 116 navigating through results, 494 SearchFuzzy, 491 Searching multiple databases, views, domains, etc., 491 multiple Domino Directories, 455 URL commands and, 490 SearchSite command, 491 count parameter, 493 optional arguments, 491 start parameter, 493 SearchView count parameter, 493 optional arguments, 491 SearchView command examples and syntax, 491 start parameter, 493
Index 515
Secret encryption keys. See Encryption keys Sections access to, 369 collapsing, 369 creating, 61, 369 defined, 80 editors and, 369 hiding titles, 369 Secure Socket Layer. See SSL Security agents, 434 CGI and, 498 CGI programs, 434 database, 349 defined, 347 documents, 351 examples, 358 folders, 353 for agents, 273 for automation, 294 for servlets, agents, and CGI programs, 432 hidden fields and, 153 Java applet access to Notes classes, 314 loading servlet classes, 434 servlets, 434, 438 signatures and, 371 SSL and, 350 SSL certificates, 495 types of, 347 URL commands and, 494, 495 Serial reviews in workflow applications, 413 Server certificate request creating, 496 Server commands OpenServer, 477 Redirect, 477 Server tasks Design, 16 Updall, 225 ServerRequest command examples, 496 optional and required fields, 497 syntax, 496 Servers console commands, 280 restricting creation of databases on, 275 Service providers for MAPI, 455 installing, 457
Servlet API, 434 Servlet classes loading, 436 Servlet manager, 435 Servlets aliases, 434 compared to agents and CGI programs, 432 defined, 431 enabling, 435 enabling Domino support, 434 example, 439 including in applications, 431 initializing, 434 invoking, 433 loading, 438 properties of, 432 running, 434 security for, 434 servlets.properties file, 434 setting properties for, 437 URL extension mapping, 434 uses for, 432 writing, 434 servlets.properties file, 434 example, 439 sessdata.ser, 436 Sessions tracking, 436 Shared actions creating, 258 defined, 246 editing, 259 inserting, 258 Shared agents controlling, 274 creating, 267 defined, 249 on the Web, 500 Shared databases, 414 Shared fields converting to single-use, 124 copying, 122 creating, 122 deleting, 123 inserting, 123 renaming, 123 stored forms and, 83 Shared graphics. See Image resources Shared resources deleting, 313 described, 30 for Java applets, 312 Shared views, 178
Shortcuts menu choices and, 301 Signatures defined, 368 storing, 372 verifying, 372 Signing documents, 368, 371 Simple actions defined, 246 table of, 287 Simple agents. See Agents Simple functions for columns, 197 Site maps. See Outlines Site Registration template, 442 Size property for Java applets, 310 Sorting documents in views, 201 Sorting columns defined, 201 hidden, 204 Sorting order column, customizing, 204 SpecialAction argument, 495 SSL creating user certificates, 496 enforcing for a database, 350 server certificate request, 496 URL commands and, 495 Start parameter search results and, 494 Status tracking, 214 Stop Java applet, 313 Storing files for Java applets, 304 forms with documents, 81, 162 Java code, 31 LotusScript programs, 31 programs, 433 signatures, 372 Structured text files defined, 447 exporting to, 453 importing into views, 447 Style editor applet. See Editor applet Styles CSS, 28 Styling columns, 207 frames, 170 horizontal rules, 59 navigators, 233
rows, 207 text, 57 titles, 184 views, 207 Subcategories, 188 Subforms defined, 31, 81 described, 97 examples, 98 Subject field, 160 Submit button generating automatically on Web, 24 SubmitCert command examples and syntax, 496 optional and required fields, 496 Subscription documents storing, 144 Subscription forms creating, 30, 144 Subscriptions described, 144 enabling, 30 Symbols currency, 128 Symphony files importing into views, 445 Synopsis, 391
T
Tab order specifying for fields, 151 Tables in forms, 85 in the editor applet, 467 in Web applications, 470 programmable, 60 Tabular text files COL files and, 450, 453 defined, 445 exporting to, 453 importing into views, 446, 453 Target frames, 169 TeamRoom template, 442 Templates agents and, 398 changing, 397, 403 customizing, 398 defined, 16, 397 design changes and, 17 examples of, 399 fields in, 160 linking, 402
linking to, 402 list of Domino Designer, 441 master, 16 navigator, 241 redesigning, 398 replacing design and, 406 replication and, 403, 407 server, 17 unlinking design elements from, 409 Testing applications, 389 design, 385 forms, 119, 384 navigators, 242 views, 386 Text computed, 58 fields, 126 graphics with, 155 navigators and, 233 styling, 57 Web, 471 Text files exporting, 452 importing to a view, 445, 446, 447 Text pop-ups creating, 262 defined, 247 deleting, 262 editing, 262 Thousands separator setting, 129 TIFF files. See Graphics Time controls creating, 134 in Web applications, 465 Time zone options, 131 Times calculating by formula, 133 columns for, 223 displaying, 223 entering, 130 formatting, 130, 132, 223 Title field, 83, 394 Titles database, 17 frameset, 167 window, 95 Totals calculating, 206 Tracking document status, 214 editors, 359
server usage, 111 sessions, 436 unread documents, 222 versions, 93, 162 TranslateForm argument, 496 Translating applications, 27 applications, and choice list aliases, 140 foreign symbols and characters, 444 Translation formulas defined, 146 setting for fields, 148 Tree style outline, 47 Troubleshooting agents, 277 calendar views, 177 fields, 394 framesets, 172 Java applets, 320 Truncation in imported text, 446
U
Unlinking templates and databases, 409 templates and design elements, 409 Unread marks color, 222 displaying, 222 Updall, 225 UpdatedBy field, 359, 394 Updating custom controls, 331 design elements, 404 designs, 404 documents, 393 Java applet files, 31 objects, 331 views, 225 Upgrading framesets and, 166 Web and, 24 URL commands authentication and, 494 count parameters, 493 explicit, 486 guidelines, 475 home page, 382 implicit, 486 opening documents by key, 485
Index 517
search, 113 searching and, 493 server commands, 477 ServerRequest, 496 start parameters, 493 syntax, 475 URL extensions for Java servlets, mapping, 434 URL links pages and, 62 URLs generating, 477 generating in Release 4.6, 25 in link hotspots, 260 servlet, 433 Use JavaScript when generating pages setting when to use, 23 User profiles creating, 106 Using This Database document creating, 377 inheriting from template, 399 opening with URL commands, 480
V
Values recalculating for computed fields, 146 refreshing, 152 Version control forms for, 94 Version tracking field for, 161 VersionOpt field, 162 Versions conflict documents as, 90 forms for creating, 162 tracking, 93, 162 View applet described, 22, 216 view properties and, 472 View lookups choice list aliases and, 141 choice list fields and, 139 Names fields and, 137 View menu working with framesets and, 170 View template defined, 215 View templates forms as, 228
Views, 449 access to, 351 alias names, 181 All by Category, 186 calendar, 173 categories and, 185 categorized, and aliases, 141 character sorting rules, 201 character translation file (.CLS) and, 444 COL files and, 452 collapsing, 207 columns in, 10 copying, 179 creating, 179, 360 default, 210 defined, 10, 173 deleting, 179 designing, 179 displaying, 210 documents and, 189 embedding, 215, 218 entering names from columns in, 139 exporting, 443, 452, 453 formatting, 210 grouping, 183 hiding, 183, 221, 239, 351 HTML and, 210 icons in, 200 importing, 443, 444 importing tabular text into, 446 indenting in, 213 indexes, 225 limits on, 181 lookups in, 111 mapping imported columns to fields, 448 naming, 181 opening, 210 page breaks and, 210 private, 178 programming, 189 public access, 360 refreshing, 225 renaming, 181, 391 searching, 490, 491 setting line counts, 221 shared, 178 single category, 220 sorting documents in, 201 styling, 207 switching, 205 testing, 386
troubleshooting, 177 types of, 173 unread marks, 222 updating, 225 URL commands and, 477 Web, 175, 471 Vision-impaired users designing for, 35 Visual Basic script Web applications and, 498
W
Web @commands and, 23, 497 @functions, 463, 497 actions, 220, 464 agents, 464, 500 authentication and, 494 CGI variables, 499 creating forms for, 466 documents, 87 example of agents, 272 fields and, 465 file attachments on, 102 folders, 227 formulas, 220 hidden fields and, 90 hiding design elements, 411 improving performance on, 24 Java applets, 498 Java programming, 498 JavaScript, 498 LotusScript and, 464 mailing features, 417 navigating, 215, 240 navigators, 228, 229, 469 Notes/FX and, 326 Perl script, 498 previewing requirements for, 38 private views and, 179 search forms and, 113 security and SSL, 350 Server document and, 382 simulating Notes menus for, 254 tables, 470 text, 471 unsupported features, 24, 133, 137 upgrading and, 24 views, 175, 471 Visual Basic script, 498 Web agent scripts DocumentContext property, 500
Web applications color for, 21 designing, 21 displaying text in, 57 home pages for, 56 Notes client and, 15 Web browsers hiding paragraphs from, 153 launch options, 25 proxy settings for, 39 setting up for previewing, 37 using with Notes client, 127 Web elements date picker, 72 embedding on pages, 71 Web pages in frames, 169 Web users access to outlines, 51 attaching files, 102 designing for Notes and, 157 Domino applets for, 22 form access, providing, 89 registering for Domino applications, 442 WebQueryOpen events agents and, 433 described, 272 WebQuerySave events agents and, 433 described, 272 Width columns, 207 Window buttons, 4 Window titles, 95 Windows. See Framesets WindowTitle field, 394 WKSCOL statement, 449 Work area overview, 4 Work pane, 4 Workflow applications, 325, 442 applications, planning, 414 defined, 413 features, 415 overview, 413 Worksheet files COL files and, 448, 449 exporting to, 452 importing into views, 445 WriteExternalData parameter in Java applets, 317 WriteObject parameter in Java applets, 319
Y
Y2K Notes and, 129
Z
ZIP files, 306
Index 519