Setting Form Properties

As with other Notes objects, forms have properties. The Form properties box has several tabs that control various settings, as listed in Table 4.2.

Table 4.2. Form Properties Box Tabs

Tab	Contents
Form Info	Name , Comment, Type, Display, Versions, Options, and Conflict Handling
Defaults	On Create, On Open , On Close, On Web Access, and Data Source Options
Launch	Auto Launch and Auto Frame
Form Background	Color , Graphic or Resource, and Options
Header	Add Header to Form, Size , and Border
Printing	Specify Header or Footer (radio button set), Header/Footer Text, Format, and Options
Security	Read Access, Create Access, Encryption Keys, Disable Printing/Forwarding/Copying to Clipboard, and Public Access

Each of these form attributes is discussed in the following sections.

Using the Form Info Tab

The Form Info tab of the Form properties box is shown in Figure 4.4. The Form Info tab contains many important settings.

Figure 4.4. The Form Info tab is the first tab of the Form properties box.

TIP

You can find the name of a tab on any properties box if you let the mouse pointer hover over the tab. Floating text shows the name of the tab. This is illustrated in Figure 4.4.

 

First and foremost, every form must have a name. It is also a good idea to use an alias. You add a form alias by placing the pipe symbol ( ) next to the form name and following it with the alias. It is a good idea to limit the length of the alias to a few characters ”two or three characters are more recognizable and easier to type. In addition, aliases are useful when you change the name of the form. Because Domino stores the alias in the document's Form field, you don't lose the connection to documents created with earlier versions. The form name might be Supplies Requisition, but the alias might be something like RQ. The combined name that appears in the Name field would be Supplies Requisition RQ. The text to the left of the pipe character is what is displayed on the Create menu; the text to the right of the pipe character is what is stored in the Form field. A form can also have more than two names, separated by the pipe symbol. When you use more than two names , the leftmost text is always the name of the form, and the rightmost text is always the alias.

TIP

Virtually every design element can have an alias. In fact, it is always a good idea to add an alias to each design element. When you write code, always use the design element's alias. That way, you can change the name of the element without breaking your code.

You don't have to enter the form name followed by a space, the pipe symbol, and then another space followed by the form synonym. Domino Designer automatically inserts the spaces before and after the pipe symbol. In other words, you can type a form name like so:

My FormMF

Domino Designer will correctly insert spaces, as in the following:

My Form MF

 

If you have a large number of forms, collecting them into categories to display on the menu is good programming practice. Adding text followed by the slash character ( ) to the name of the form causes forms to cascade under the text preceding the slash character in the Create menu. For example, if you have several different types of requisitions, you might include a grouping for hardware requisitions. The following list depicts a series of forms that would cascade under the Create menu as hardware requisitions:

Hardware RequisitionPC

Hardware RequisitionLaptop

Hardware RequisitionPrinter

You can also use an underscore character preceding a letter in the form's name to create a hotkey for that letter in the form's name.

The complete name of the form, including synonyms, special characters, and cascading menu text, cannot be more than 256 bytes. However, as with field names, it is best to keep the name short and user -friendly.

The next two fields are the Comment and Type fields. The Comment field can be used to enter a brief comment about the form's purpose. The form type is set in the Type drop-down list. As discussed earlier, there are three choices: Document, Response, and Response-to-Response.

In the Display section, the Include In settings for Include in Menu and Include in Search Builder are checked by default; Include in Print, new to Designer 6, is unchecked by default. The In Menu setting has two choices: Create Menu and Create Other Dialog Box. Setting In Menu to Create Menu displays the form on the Create menu. Setting In Menu to Create Other Dialog Box displays the form in a dialog box when Create, Other is chosen from the menu. The second Include setting is Include in Search Builder. Leaving this option checked allows the form to be used in a full-text search builder window. Include in Print enables contact printing, new to Designer 6.

NOTE

Contact printing allows you to print multiple documents on a single page. For example, you can print address labels from a contacts database by enabling contact printing on a special form designed to display the documents in standard address formats.

 

You can establish version control for documents by choosing a setting from Versions other than None, which is the default, and making a choice in the Create Versions field. The settings for version control are listed in Table 4.3.

Table 4.3. Version Control

Field	Option
Versioning	None (default). New versions become responses. Previous versions become responses. New versions become siblings.
Create Versions	(Available when versioning is changed from None.) Manual: File, New Version Automatic: File, Save

Versioning is useful in applications that involve document approval or collaborative authoring. An example is a corporate policy library. Most companies have an approval route that corporate policy documents take before becoming official policy. Notes and Domino is ideal for this kind of application because it supports mail routing, and the Corporate Policy database can be mail-enabled to match the corporate routing structure. In this kind of application, it might be useful to allow more than one person to work (collaborate) on a particular document.

With version control, each version of the document is saved. Notes controls the manner in which the document's versions are saved with the Versioning and Create Versions fields. When a new version becomes a response, the original document remains the main document and is listed first in the view. The new version is a response document and is indented and listed underneath the original. When a previous version becomes a response, the new version is listed first in the view, and the original is listed as a response underneath the new document. When new versions become siblings, all are saved as main documents, with the original listed first in the view.

If Create Versions is automatic, a new version is automatically created whenever the new document is saved. If Version Control is set to Manual, the user can determine whether a new version is created. The latter option is more flexible but less secure.

CAUTION

Versioning is not available for Web clients .

 

The bottom of the Form Info tab has a series of check boxes:

• Default Database Form ” Domino uses the default database form to display documents with no associated form (the Form field is empty).
• Store Form in Document ” Whenever the document is saved, the form is saved with it.
• Disable Field Exchange ” This stops documents created with the form from participating in Notes/FX (Notes Field Exchange).
• Automatically Refresh Fields ” This refreshes all fields whenever a change is made to any field while in edit.
• Anonymous Form ” No author information is saved with the document.
• No Initial Focus ” When a document is displayed with this setting, there is no initial focus on the frame containing the document.
• No Focus on F6 ” This prevents F6 and Shift+F6 from adding focus to a frame. F6 selects the next frame, and Shift+F6 selects the previous frame.
• Sign Documents That Use This Form ” Digital signatures are enforced when a document created from the form is saved. This does not work for Web clients.
• Render Pass-Thru HTML in Notes ” Pass-thru HTML is displayed to Notes clients as it would appear to a browser client.
• Do Not Add Field Names to Field Index ” Field names are typically stored in a table that permits them to be seen in various places, such as view columns and actions. Checking this property prevents the field names for a form from being saved to the field index.

Each database should have a default database form. When a form is set as the default database form, any document that does not have a form designated will be opened with the default form.

Storing the form in documents can be useful in certain circumstances; however, you need to be aware that it can dramatically increase the amount of disk space for the database. To use stored forms, you must also enable Allow Use of Stored Forms in This Database on the Form Info tab of the Database properties box. Stored forms are available to Web clients as read-only documents ”they cannot create a document with a stored form. For example, you can use stored forms to email documents into a database that doesn't contain the form used to create the document. When users open the document in the mail-in database, it will be displayed in its native format. Documents created with stored forms include several reserved fields. $Title contains the original form name, whereas $Info, $WindowTitle, and $Body contain additional information used to display the document.

Fields can be exchanged with other applications using Notes/FX and OLE. When you disable Field Exchange, you stop Notes/FX “enabled applications from exchanging information.

Checking Automatically Refresh Fields causes Notes to refresh every field in the document whenever any field is changed. Automatically refreshing the fields can slow performance significantly, although with today's powerful PCs, this is less of a factor than it used to be.

CAUTION

Automatically Refresh Fields should almost never be used. It can significantly impair the performance of a form because it calculates every formula for every field whenever information in a field is entered or edited. In general, do not use this option, but if you must, ensure that there are few computed field formulas requiring a refresh.

 

NOTE

Automatically Refresh Fields does not apply to Web applications because HTML pages are relatively static documents. You can use @Command([ViewRefreshFields]) to refresh the display of fields on a Web document.

 

The Anonymous form was introduced in R4. By default, Notes keeps track of the document authors and editors in special fields created internally. If you check Anonymous Form, this tracking does not happen and documents can be created and saved anonymously. This is useful for applications such as a corporate suggestion box. In this type of application, people might be less than open if they know their names can be linked to their input. Note that to maintain complete anonymity, you must avoid including any computed fields based on formulas such as @UserName .

The Conflict Handling section is new to Designer 6; previous releases had a single check box, Merge Replication Conflicts. Because Notes supports multiple editors for individual documents, conflicts can occur when two or more editors change an item. Fields as well as forms have an internal sequence number that the replicator uses to detect a conflict. During replication, Notes checks to see if the document sequence numbers are different and then compares the contents of each field. If a conflict is detected , four options in the Conflict Handling section determine what happens:

• Create Conflicts ” This is the default selection. Replication conflict documents are automatically created whenever Notes detects a conflict.
• Merge Conflicts ” If a conflict is detected, the documents are merged unless two or more editors change the contents of the same field. In that case, a replication or save conflict document is created.
• Merge/No Conflicts ” This option merges the conflicts but does not create a replication conflict document.
• Do Not Create Conflicts ” No merge takes place; one document is kept and the conflicting document is discarded.

When you choose one of the first two options, a conflict document is created. One of the two documents is the main document, and the second document, also known as a replication or save conflict document, appears with a diamond next to it in views.

Using the Defaults Tab

Figure 4.5 shows the settings available on the Defaults tab. There are several sections: On Create, On Open, On Close, On Web Access, and Data Source Options.

Figure 4.5. The Defaults tab of the Form properties box has new options in Designer 6, including a Data Source section.

The On Create Section

In the On Create section, you can set up inheritance from one document to another to retrieve specific values or to retrieve the entire document into a rich-text field. Because Domino is not a relational database, it is not always easy to get information from other documents. If you need information from another document in the current document, you can store it in the new document using inheritance. Relational database designers may cringe because this violates principles of relational design. However, Domino is quasirelational, at best, and duplication of data items among documents (redundancy) is not as important.

Inheritance happens only once ”when the document is composed. For inheritance to work, the new document must be composed while the document from which the information is to be inherited is highlighted in a view or is opened. Inheritance is frequently used between main documents and response documents, but it can also occur between two main documents. It is important to note that if information in the parent document changes, the information in the child document does not change automatically.

Using the Document ID

If you store the document ID of the parent document in a field in the child document, you can then update the values of either document using two @Functions: @GetDocField() and @SetDocField() . The syntax requires you to supply the document ID and field name, as in the following:

@GetDocField(cParentDocID; "cFullName"

In this expression, cParentDocID is created using inheritance from the parent document. The value formula for cParentDocID is @Text(@DocumentUniqueID . Note that if the child document is a response document type, the special field called $Ref can be used to retrieve values from the parent document.

Two kinds of inheritance exist. One is field-level inheritance ”individual fields inherit information from a parent document. The fields can have the same name, but they don't have to. The default value (or value, if the field isn't editable) formula must be the name of the field to be inherited.

The second type of inheritance pulls the entire document into a rich-text field. When you click this option, two new fields open. The first contains a list of rich-text fields in the document, and the second lists three types of inheritance: Link, Collapsible Rich Text, and Rich Text (see Figure 4.6). If you choose Link, a document link icon appears in the Rich Text field. Collapsible rich text places the entire document into a section that can be collapsed or expanded; an example of this type of inheritance is the Reply with History form in the Notes Mail database. The Rich Text option simply displays the document as it appears.

Figure 4.6. Inheriting documents into rich-text fields allows three choices for inheritance.

The On Open Section

The On Open section has two options: Automatically Enable Edit Mode and Show Context Pane. In some applications, you might want to have certain forms automatically open in edit mode. This can be a convenience for users. Don't worry about unauthorized access to data ”individuals with Reader access will not be able to edit or create a document. Clicking Show Context Pane opens another drop-down list containing two choices: Doclink and Parent. The Show Context pane can be somewhat obtrusive because the bottom half of the form automatically opens to the linked document, whether you select Doclink or Parent.

The On Close Section

On Close has only one field: Present Mail Send Dialog. This automatically prompts users with the Mail Send dialog box when the document is saved. Note that this does not work for a Web client. (Chapter 24, "Creating Workflow Applications," discusses mail-enabling Notes applications.)

The On Web Access Section

The On Web Access section is redesigned in Domino Designer 6. You can specify the type of content by selecting Notes, HTML, or Other in the Content Type radio button. Character Set can be used for international applications. Generate HTML for All Fields allows hidden fields on the form to participate in a Web client session. The three color pickers at the bottom are for Active Link (red), Unvisited Link (blue), and Visited Link (purple). You can use the color pickers to set the link colors. If you view the HTML source of a document, you'll find a line similar to the following:

<

BODY TEXT

="000000"

BGCOLOR

="FFFFFF"

LINK

="0000FF"

ALINK

="008080"

VLINK

="FF00FF">

This specifies active links ( ALINK ) as cyan, unvisited links (LINK) as blue, and visited links (VLINK) as purple. The values are in hexadecimal format.

In the Data Source Options section, you can enter or select a Data Connection Resource (DCR) to use with the form. For more information on DCRs, see Chapter 22, "Accessing Data with DECS and DCRs."

Working with the Launch Tab

Two settings are available on the Launch tab: Auto Launch and Auto Frame (see Figure 4.7). Numerous choices are available from the Auto Launch drop-down list on the Launch tab. You can launch attachments, document links, a wide variety of SmartSuite application objects, Microsoft Office suite objects, Paint Shop Pro images, MIDI sequences, QuickTime movies, and many more. The list is seemingly endless. The default setting for Auto Launch is None; switching to other options adds more choices to the section, as illustrated by Figure 4.7.

Figure 4.7. Selections on the Launch tab of the Form properties box expand when certain Auto Launch options are selected.

The Frameset and Frame choices at the bottom of the Launch tab are shown in Figure 4.8. After you select a frameset in the Auto Frame section of the tab, you can choose a specific frame from that frameset. Documents created with the form appear in that frame. (Framesets are discussed in Chapter 10, "Adding Framesets to Domino Applications.")

Figure 4.8. The Auto Frame section of the Launch tab launches documents in a specific frame for both Web and Notes clients.

Using the Form Background Tab

Three sections exist on the Form Background tab: Color, Graphic or Resource, and Options. The Form Background tab enables you to set the background color of forms and to add images to the background of a form. Various options related to the background of the form can also be set from this tab (see Figures 4.9 and 4.10).

Figure 4.9. The Form Background tab of the Form properties box has settings for color, images, and options.

Figure 4.10. Clicking the button for the Color field of the Form Background tab displays the color palette.

You can use background colors to differentiate among types of forms. The standard Notes color picker is available from the Color field by clicking the drop-down arrow. Although a large number of colors are available, some platforms will not be able to display all those colors, so be careful which colors you choose. It is usually best to choose lighter colors because it can be difficult to read text on a dark background.

Using the Notes Color Picker

In previous releases of Notes and Domino, the color picker had a fixed set of colors. Each color had a name assigned, such as cyan, red, magenta , 10% gray, or pale yellow. Now the color picker displays the RGB values of the colors instead, which is somewhat less useful because you don't normally refer to 10% gray as 239,239,239 . Clicking the color wheel, the small button with the color circle in the upper-right corner of the color picker, enables you to build custom colors. You can revert to the system colors by clicking the system button just to the left of the color wheel.

Embedding a graphic in the background is different from pasting or importing it directly on the form. When a graphic is pasted or imported on the form, it is like any other object on the form; it occupies space just as text or fields do. When an image is embedded in the background, other objects can be placed on top of it. You can embed graphics on the background of a form with the Paste Graphic or Import Graphic buttons, or you can use an image resource by clicking the Browse Images or Formula buttons . Images can be removed with the Remove Graphic button.

To use the Paste button, copy an image to the Clipboard and click the Paste Graphic button. Unless the image covers the entire background, it is tiled so that it covers the entire background of the form. You can click the Import Graphic button to import JPEGs or GIFs from the file system. The same rules apply for the effects on the background as those that apply to the Paste Graphic button.

The Image Resource field was added in R5. If you click the Browse Resources button beside the field, Domino Designer 6 opens a dialog box from which you can choose and insert a shared image resource. Note that the image resource must already exist. You can remove an image resource by deleting the filename from the field or by clicking the Remove button. The Formula button opens a window that enables you to write a formula to insert an image. Figure 4.11 shows the Insert Image Resource dialog box.

Figure 4.11. The Insert Image Resource dialog box displays a thumbnail of the image on the right of the dialog box.

NOTE

For more information about shared resources, see Chapter 7.

 

TIP

If you don't want to be bothered with the background during development, click Hide Graphic in Design Mode. Displaying a background during design can cause your work to go slowly as the Designer refreshes the background image.

 

The Options section contains several options that become visible once an image is selected:

• Hide Graphic in Design Mode
• Hide Graphic on 16 Color Displays
• Allow Users to Change These Properties
• Repeat

For the most part, the options are self-explanatory. The Allow Users to Change These Properties option deserves further treatment, however. This option refers only to the settings in the Options setting. If you click one or more of the options, such as Hide Graphic on 16 Color Displays, users can change them in a document. The options appear on the Background tab of the Document properties box. There you can check or uncheck the options as you see fit. For example, you can switch from Do Not Tile Graphic back to a tiled background. When you've created a background color or image, you can add text and fields to the form that will appear in the foreground.

The Repeat option is a drop-down list containing six options for tiling images: Repeat Once, Repeat Vertically, Repeat Horizontally, Tile (the default), Size to Fit, and Center.

TIP

Use transparent GIFs where possible. This special image type displays whatever is underneath the background color of the GIF, and it works in both Web and Notes clients.

 

Using the Header Tab

Figure 4.12 shows the Header tab of the Form properties box. The Header tab enables you to specify properties for a header region that appears at the top of a document. This property is available only for Notes clients and doesn't work on the Web. There are three sections: the Add Header to Form check box, Size, and Border. When Add Header to Form is checked, the size of the header region can be specified in pixels, by percent, or by Fit to Content.

Figure 4.12. The Header tab allows you to set properties for the form header, a nonscrolling region at the top of a document.

You can set scrolling inside the region to Yes, No, or Auto. If the contents of the region exceed the height, scrollbars appear to allow users to scroll through the region. This is similar to scrollbars that appear for frames in framesets in Web browsers.

You can also allow the user to resize the header by clicking Allow Resizing. Note that this setting is available only when a border is specified. To show the border, click the Border spinner to a setting greater than 0 and select a color. In addition, 3D shading adds a three-dimensional appearance to the border.

Setting a nonscrolling header region for documents enables you to place certain items, such as fields, text, hotspots, and graphics, in the header that will remain visible wherever the user happens to be in the document. Any item that a form can contain can be placed in a header. If you want to use a table in the header, you must place a text object before the table. The text object can be a space or an empty line feed.

CAUTION

If you add a header to an existing form, the border will fall wherever you specify. If you have text or fields in that area of the form, they automatically become part of the header. If you have a graphic resource used in the background, it appears only in the header; the form itself will have no background image. Background for documents colors are not affected in the same way.

 

Setting Print Options

The Printing tab allows you to specify the settings for the header and footer when printing the document (see Figure 4.13). There are four sections: Specify Header or Footer, Header/Footer Text, Format, and Options.

Figure 4.13. You can define a formula for headers and footers on the Printing tab of the Form properties box.

The Specify Header or Footer section enables you to specify whether the settings are for the header or the footer. You can specify different settings for each. After you've clicked the appropriate radio button, you can create the header or footer in the Header/Footer text window. This window has six buttons below it, which, from left to right, insert the following:

• Page number
• Total number of pages
• Date
• Time
• Tab
• Title

Hover help is available for each button by positioning the mouse pointer over it. Except for the Tab button, all the other choices are self-explanatory. There are only three preset tab stops: left, center, and right. The formula for the footer shown in Figure 4.13, Printed: &DPage: &P of &Q , places the text Printed: plus the date flush left, Page: plus the page number, and of plus the total page count flush right. In the Format section, you can change the font, size, and style of the text for headers and footers. There is only one check box in the Options section: Print Header and Footer on First Page. This is checked by default. If you uncheck it, any document that spans multiple pages will not have the header and/or footer on the first page.

CAUTION

The settings for Header and Footer on the Printing tab should not be confused with the settings on the Header tab. These settings affect documents printed with the form, whereas the settings on the Header form affect the visual appearance of the form.

 

Setting Form Security

The last tab, the Security tab, contains advanced properties for the form. The first two list boxes for read access and create access can be used to enhance author access to the form. Each of these list boxes provides access to the database ACL, from which you can choose specific users, groups, or roles to limit read or author access. (These options are covered in more detail in Chapter 23, "Securing Domino Applications.") Figure 4.14 shows the Security tab of the Form properties box.

Figure 4.14. The Security tab of the Form properties box enables you to determine reader and author access and set the encryption key.

The Default Encryption Keys field enables you to assign a specific encryption key to a form. If you then place encryptable fields on the form, when the document is saved, the encryption keys are applied to those specific fields.

CAUTION

Note that although a user might have Editor access to the database and the form, if the user does not have the encryption key, he will not be able to save the document created with the form.

 

Specifying Encryption Keys

Users can elect to encrypt a document with any key they possess, as long as there are encryptable fields on the document. However, you can ensure that a specific encryption key is used by adding the reserved field SecretEncryptionKey to the form. The field should be computed text and should evaluate to the name of an encryption key. Whenever a user with the key saves the document, the fields set for encryption will be encrypted using that key. This technique has the same effect as setting a default encryption key, but it can offer more flexibility.

For example, you might want to allow a certain class of users to create a document but not encrypt it. Other users who are editors of the documents can then encrypt the document using a secret encryption key. To accomplish this, you can include a subform that contains unencrypted fields for the first class of users, and another subform for the editors who use encrypted fields. This second subform should also include the special field SecretEncryptionKey. Using a computed subform will enable you to display the correct form at the correct time.

Two check boxes are located at the bottom of the Security tab: Disable Printing/Forwarding/Copying to the Clipboard and Available to Public Access Users. Disabling printing and forwarding of the form is not a true security feature because any reader of the document can access the fields. However, it is a deterrent to unauthorized access. Available to Public Access Users is designed to enable users with no access or Depositor access levels to see certain documents, views, or folders in the database. To create a form that is available for public access, you must include a field called $PublicAccess with a value of 1 .