Working with Fields

Fields are used to store data on a form. There are many different types of fields. The field type defines the values that can be stored in the field and, in some cases, the presentation of the field on the form. This section describes each of the field types.

As you work with the various fields in the Designer client, you'll notice that a unique quick-reference icon is embedded in each field. These serve as an indicator of the field type, which is specified in the properties dialog. The following table provides an overview of each field type along with the quick-reference field symbol.

Field Type	Description Summary	Field Symbol
Authors	Refines who can edit a document
Checkbox	Creates checkboxes on the form (keyword field)
Color	Allows users to pick colors
Combobox	Creates a dropdown on the form (keyword field)
Date/Time	Defines format for dates and times
Dialog List	Displays a dialog with selectable values (keyword field)
Formula	Contains a formula
Listbox	Creates a scrollable list of values (keyword field)
Names	Used to capture and store user names
Number	Stores and formats numeric values
Password	Stores an encrypted password value
Radio Button	Creates radio buttons on the form (keyword field)
Readers	Defines who can read the document
Rich Text	Allow users to specify font, color, and size
Rich Text Lite	Similar to a Rich Text field, but developers can limit what types of objects can be stored in the field
Text	Used to store plain text
Time Zone	Allows users to select a time zone

Tip

These field types are based on Lotus Notes release 6. Some field types are not available in release 5, and additional field types may be available when using release 7.

 

Working with Keyword Fields

Before we talk about each field type, let's spend a moment talking about a group of fields that contain predefined values. These fields are classified as "keyword fields" and contain predetermined values that can be selected by users. Using keyword fields, you can enforce a consistent nomenclature for data values and help steer the user as he or she completes the form. There are five field types that are considered to be keyword fieldsCheckbox, Combobox, Dialog List, Listbox, and Radio Button.

These field types can be configured to accept only the data values in the field or to allow users to specify new values. These two options, which are set on the second properties tab, offer enormous flexibility in the management of the field content. Some keyword fields also provide the option to select multiple data values. This option is set on the first tab in the properties dialog (see Figure 4.8).

Figure 4.8. Allow multiple values setting

There are several ways to define the data values for this field type. The data values can be based on hard-coded values or a computed formula specified on the second tab of the properties dialog. There are up to five unique methods for defining the data values for keyword fields (see Figure 4.9). Not all of these options appear for every field type. Design options include the following:

• Enter choices (one per line) Used to specify hard-coded values for the field. In general, this field should be used when values will not be added or changed (e.g. male and female, or the months of the year).
• Use formula for choices Used to dynamically define values for a field. Using formulas, you can pull information from documents, fields, or views to populate the keyword list. This option offers the flexibility to add or remove values from the list without having to modify the Notes database design.
• Use Address dialog for choices Used to display the Personal or Notes address book. This option enables users to select people or servers from a dialog list to populate the field and is often used to define a list of people to receive an email.
• Use Access Control List for choices Used to populate the field with user names from the Access Control List (ACL).
• Use View dialog for choices Used to populate the field with values from a view. Alternatively, you could utilize the "Use Formula" option to achieve the same result.

Figure 4.9. Choice types for keyword fields

Tip

See "Working with @DBColumn" and "Working with @DBLookup" in Chapter 14, "Design Enhancements Using Formula Language," to learn how to dynamically build a list of values (and avoid hard-coded values) for checkbox, combobox, dialog list, listbox, and radio button fields. This allows the list of values to change without having to modify the application.

 

Authors Field

This is a special field used to manage who can edit a document. The authors field works in conjunction with the ACL and refines who can modify a document. The field affects users with Author and Editor database access. Only users who are specified in this field can make document updates. The users specified in the field could be computed based on a formula or editable from the document. Users with Reader access cannot gain edit authority by including their name in the field. Users with Author access are able to modify the document only if their name is included in the field. Users with Editor access by default have the ability to edit the document and are unaffected by the authors field. In short, the authors field allows you to refine who can modify a particular document.

Checkbox Field

As the name implies, this field will display a series of checkboxes on a form (see Figure 4.10). Values for the checkbox field are specified in the field properties dialog and can be hard-coded or computed. The field properties dialog also allows you to specify the number of columns and the display presentation. This type of field enables users to select all applicable values associated with the field.

Figure 4.10. Example checkbox field

The properties dialog also allows you to define the appearance of the checkbox field on the form. This is called the border style, and it resides on the second tab of the properties dialog. The border style can be set to None, Single, or Inset.

The second tab is also used to define the various values for the checkbox field and the number of columns to be displayed. Values can be hard-coded or determined by a formula.

Color Field

Adding a color field displays a color picker on the form (see Figure 4.11). This field allows the user to select a color.

Figure 4.11. Example color field

 

Combobox Field

The combobox field provides a list of values available for a field. When the user clicks on the field, a dropdown list is displayed and allows the user to select the appropriate value. If the combobox contains a large number of options, the field automatically inserts a scroll box that allows users to move up and down within the field (see Figure 4.12).

Figure 4.12. Example combobox field

As with other keyword fields, a combobox can be configured to accept values not in the list or to only permit users to select from the existing list. The combobox field is commonly used in both Lotus Notes client applications and Web applications.

Note

The height and width properties of a combobox field are not supported in Web applications. By default, the field width will be set to the width of the longest text value.

 

Date/Time Field

Date/Time fields are used to store and display dates and times in various formats. This field supports both the 12-hour and 24-hour time format and dates that range from 1/1/0001 to 12/31/9999.

With Date/Time fields, you can specify to display only the date, only the time, or both. This gives you great flexibility as to the format of the field. As with other fields, the format for the Date/Time field is configured in the properties dialog. The format settings are defined in the second property tab for the field. The following table shows some of the supported date and time formats.

Date/Time Configuration Options	Settings	Example
Month, day, and year	Date	07/28/2005
Weekday, month, day, and year	Date	Thu 07/28/2005
Month and year	Date	07/2005
Month and day	Date	07/28
Year	Date	2005
Month	Date	07
Day	Date	28
Weekday	Date	Thu
Hours, minutes, and seconds	Time	09:28:55 AM
Hours	Time	09
Minutes	Time	28
Seconds	Time	55
Month, day, year, and time	Date and Time	07/28/2005 09:28:55 AM
Weekday, month, day, year, and time	Date and Time	Thu 07/28/2005 09:28:55 AM

Note

Using Formula Language, you can create dates with the month spelled out (e.g., January 01, 2005). See "Create a Formatted Date String" in Chapter 14 for additional information.

Tip

Use the @Today function to set the field to today's date or the @Now function to set the field to the current date and time. These functions can be used for default field values or to track historical changes to a document.

 

Dialog List Field

A dialog list field displays a list of valid field choices in a dialog box window. This field can be identified by a "down arrow" located to the right of the field. Clicking on the arrow displays the dialog box. This field can be configured to allow any value or only those currently listed. The values can be hard-coded or determined by a formula. Note that Figure 4.13 illustrates a dialog list where only one value in the list can be selected.

Figure 4.13. Example dialog list field with static values

In this second example, users have the ability to select one or more values from the list as well as to enter new keyword values in the field at the bottom of the dialog box (see Figure 4.14).

Figure 4.14. Example dialog list field with dynamic values

Tip

The dialog box in the Lotus Note client can be resized. To do this, right-click and hold the lower-right corner of the dialog box. Then drag to the desired size.

 

Formula Field

The formula field is a special field type used to create a "headline" application. This is a very specialized field that automatically notifies people of changes to the database. The field works in conjunction with a special database called Headlines.nsf.

Note

To implement this function, you will need to create a form called $Subscription and include a formula field called $HLFormula. For additional information, see the Domino Designer help for exact setup instructions.

 

Listbox Field

The listbox field is used to create a scrollable list of data values (see Figure 4.15). Using this properties dialog, you can specify the height and width of the field (which are defined in the first tab). The border style and data values can be defined in the second tab of the properties dialog. The values can be hard-coded or determined by a formula.

Figure 4.15. Example listbox field

Note

The listbox height and width properties are not supported in Web applications. By default, the field width will be set to the width of the longest text value.

 

Names Field

A names field is used to capture and store user names. This field also has a down arrow, located to the right of field, which displays an address book. The address book allows the application user to select user names from a public or personal address book. More importantly, however, this field stores values based on the Lotus Notes name hierarchy and can be used to generate emails.

Tip

A names field allows users to select names from the address book and ensures correct spelling.

For example, you may have an application that tracks project meeting agendas and minutes. The form could be divided into two sectionsagenda information and meeting minutes. Each section could have a names field. The first would allow the author to select all the users that have been invited to the meeting. The second names field would be used to track all the users that actually attended the meeting. Because these fields contain names based on the Notes user ID hierarchy, a button could be added that sends meeting minutes to everyone that was invited to the meeting.

Tip

Use the @Name function to change the data format of a names field. See Chapter 5, "An Introduction to Formula Language," and the Chapter 14 section, "Format a user's name" for additional information and examples.

Note

You must select the Allow multiple values checkbox on the field properties dialog in order to store more than one user name.

 

Number Field

The number field is used to store numeric values including mathematical symbols (e.g., plus, minus, decimal, percent, dollar, etc.). Using the properties dialog box, you can define the format of the number field, such as the following:

• Number format (Decimal, Percent, Scientific, or Currency)
• Decimal places (Fixed or Varying)
• Thousands separator
• Decimal symbol

Numeric fields accept numbers that range from 2.225E-308 to 1.798E308 with fourteen-digit accuracy.

Password Field

The password field is a plain-text field that replaces letters on the screen with asterisks as characters are entered in the field. It's important to understand that the contents of this field are not encrypted. In other words, this is not a secure field. The information stored in this field is still visible from the document properties dialog box.

Radio Button Field

This type of field displays a series of radio buttons on a form. Radio button values are specified in the properties window and can be hard-coded or computed. The properties window also allows you to specify the number of columns and the display presentation.

Unlike checkbox fields that allow multiple values to be checked, only one radio button value can be selected. For example, you could add a field called "gender" on a form. This field would allow users to select either Male or Female.

The properties dialog also allows you to define the appearance of the radio buttons on the form. This is called the radio button border style, and it resides on the second tab of the properties dialog.

The second tab is also used to define the various values for the radio buttons and the number of columns to be displayed. Values can be hard-coded or based on a formula.

Description	Example
None	No border is displayed.
Single	A single-line box frames the radio button options.
Inset	The radio buttons are framed inside a gray box window.

 

Readers Field

The readers field is used to refine who can access or view a particular document in the Notes databases. With this field, only the people listed in the field will have the ability to view the document provided that they have been granted accessed to the database in the ACL.

Another very important aspect of this field is that Lotus Notes will only copy or replicate documents for which the user is included in the reader field. Those documents where a person's name is not included in the list will not be copied when performing a database copy or replicated during the database replication process. In fact, the document will not even appear in a view.

Tip

A readers field is a great way to manage access to content in a database. For example, this field could be implemented such that people will only see documents they create. In other words, John can see only his documents, and Susan can see only her documents.

Note

A readers field is an extremely powerful feature. Be sure to thoroughly test the application to ensure that the design is working as intended before deploying the database. If you're not careful, you could easily lock access to documents from everyone including developers and administrators.

 

Rich Text Field

Notes manages text in several different waysRich Text, Rich Text Lite, and plain text. Rich Text fields store the text along with the font, size, color, and other text properties (e.g., underline, bold, subscript, strikethrough, etc.). In addition to robust text features, Rich Text fields enable users to create tables, embed graphics, attach files, add Web links, create buttons, and create OLE objects and sections among other things.

Note

The content of a Rich Text field cannot be displayed in a view column. Consider using a text field to display data in a view. However, you can use @Abstract in a separate field and display a subset of the Rich Text contents.

 

Rich Text Lite Field

This field supports the same formats described in the previous section, "Rich Text Field." However, developers can limit the types of objects that can be stored in the field. For example, developers can set the properties for this field to only allow text or a file attachment.

Text Field

Text fields store data in a plain-text format, accepting only alphanumeric characters (letters AZ, numbers 09, and punctuation characters). A text field, unlike the Rich Text field, does not allow users to set the font, size, or color. This field also does not support tables, graphics, sections, or other robust text formatting. This type of field is strictly intended to capture text.

Note

Information stored in a text field can be displayed in a view, whereas the contents of a Rich Text field cannot be displayed in a view.

Note

Numerical values stored in a text field cannot be used in a mathematical calculation. However, provided the field only contains numbers, the @TextToNumber function can be used to convert the value.

 

Time Zone Field

A time zone field is used to display a list of all available time zones in the world (see Figure 4.16). In addition to the time zone, the field includes a representative list of cities associated with the time region.

Figure 4.16. Example time zone field

 

Setting the Field Mode (Editable versus Computed)

By now you should understand that there are many different types of fields. In addition to defining the type of field, you can also specify how data values are stored in the field. Using the properties dialog, each field can be set to one of four modeseditable, computed, computed for display, or computed when composed (see Figure 4.17). All computed fields must contain a valid formula used to calculate the result. Computed fields cannot be directly modified by the end-user community.

Figure 4.17. Setting the field display mode

• Computed The data value is automatically computed. Computed fields are often used to calculate one field value based on another field value (e.g., calculate the day of the week given a specified month, day, and year). Computed fields are calculated when a document is created or saved.
• Computed for display The data value is automatically computed when the form is displayed. The value, however, is not actually stored in the document. It's important to note that this mode is not supported with Rich Text fields.
• Computed when composed The data value is automatically computed when the document is first created and cannot be modified. After this value is set, it will not be automatically computed again. For example, this field mode is often used to track the document creation date and author. Because the creation date is a fixed point in time, you can use this option to automatically capture and store the date. However, this type of field can be programmatically changed.
• Editable This field mode allows anyone with appropriate access to edit or modify field content.

Most forms have a combination of these fields, where most are editable fields and perhaps a few are computed fields.

Note

A field can either be editable or computed, but not both.

 

Hiding Objects

Using the "Hide When" property tab, you can define when an object is visible to users. The "Hide When" tab is usually the second to last tab in the properties dialog and is represented by a window shade in the tab (see Figure 4.18). Here you can hide the object

• Based on the client type
• In read-only mode
• In edit mode
• When printing
• When copied to the Clipboard
• Based on a custom formula

Figure 4.18. Setting the "Hide When" formula

This robust set of configuration options can be applied to text strings, fields, sections, buttons, and practically any other object that's displayed to the user. As you develop applications, you'll find that the "Hide When" settings are used to manage the display of buttons as well as sensitive field and text information.

For example, if you currently have a document opened in edit mode, it doesn't make sense to have the Edit button displayed. So, in this case, you'd want to display the button when Previewed for reading and Opened for reading and hide the button when Previewed for editing and Opened for editing.

Other times you'll want to hide text paragraphs and fields to limit the display of information to specific groups. For example, unless you're a member of the "Helpdesk," you could hide the employee's workstation specificationsoperating system, fix pack level, machine type, and so on. In other words, you can target the display of information based on the person viewing the information.

Note

Roles are assigned to a group of people and generally grant the group authority to perform tasks that people outside of the group cannot. See Chapter 19, "Security," for additional information pertaining to application security.

Note

A valid formula must be specified if the Hide paragraph if formula is true option is selected. Often the formula is set to display information based on a person's access role. See "Managing Access to Forms and Documents" in Chapter 19 for additional information.

Tip

A quick way to completely hide a field is to select Hide paragraph if formula is true and set the formula to 1. Alternatively, if you're looking to hide a field but to retain a hide formula that has already been entered, select all checkboxes under the Hide paragraph from section.

Note

The "hide" feature should not be used as a means to secure data. Even though the field or paragraph is hidden, it can still be viewed in the document properties dialog box.

 

Field Processing Order

All fields on a form are calculated in a specific sequencefrom left to right, top to bottom. This is most important with regards to placement of computed fields and "Hide When" formulas on the form. Figure 4.19 illustrates a form that contains a number of fields and the processing order sequence.

Figure 4.19. Field processing order

So why is the field processing order important? Because the field order can affect other field values for the form. Let's say there are two computed fields on a form. The formula for one field (Time2) is based on the result of another field (Time1). In this situation, placement of the field affects the ability to calculate the data value. If "end time" is placed before "start time" on the form, Lotus Notes will most likely display an error message when the form is initially created.

Note

The Designer client will not flag errors in the sequencing of fields. If a computed field is placed on the form ahead of a dependent field, an error message will mostly likely be displayed in the Lotus Notes client when the user attempts to open the form. When this occurs, an error message is presented and the form does not display. Whether an error is displayed will depend on the design of the database and the formula stored in the design element.

 

Setting the Form Type

As a groupware product, Lotus Notes is often used to collaborate, discuss, and share information. To help facilitate this process, Designer allows you to create a hierarchical structure of documents stored within the database. This hierarchy is often called a Main document and Response document.

These form types help facilitate discussion and enable related documents to be grouped together when displayed in a view. There are currently three form types that can be implemented in a Notes database:

• Document This is the default form type for all forms created in the database and is considered to be the main, or parent, document. A main document can have one or more related response documents.
• Response Response documents are tied to a Main document and are often referred to as child documents. When displayed in a view, Response documents appear indented under the parent document.
• Response to Response Finally, as the name implies, this document type is tied to response documents. These documents are often considered to be grandchild documents. In a view, these documents are indented beneath the response document.

Note

Although form type can be used to determine whether a document is a child or grandchild document, Notes actually identifies these response documents by the presence of the $REF field on the form. In other words, it's possible to create a child document without specifically setting the form type to "Response." This can be accomplished through the use of the MakeResponse method in LotusScript or the MakeResponse method of the Document class in Java.

Working with Layout Regions