Using Formulas in Forms and Subforms

Chapter 4, "Forms Design," describes what forms and subforms are and how to construct them. In this section, you'll see how to create effective subforms and forms.

In workflow applications, you will frequently find that certain types of items are best kept in a database profile form. These can be short lists of lookup keywords, replica IDs for HR databases, and escalation triggers, to name just a few. For convenience, you can name and alias the database profile form the same way so that other design objects that reference them can be reused. The agent in Chapter 5 that opens the database profile form is a good example. Because the name of the database profile form always has the same alias, GPF, the agent (see Listing 13.1) can go in your database library of reusable objects.

Listing 13.1 Set Global Profile Agent

@If(@Contains(@UserRoles; "Profile");
 @Do(@Command([EditProfile]; "GPF")) ;
 @Return(@Do(@Prompt([OK]; "Warning!"; "You are not authorized to edit this database

's profile!")) ) )

NOTE

In past editions of Notes and Domino, you needed Designer access to create a database profile document. In Notes and Domino 6, you need only Author access, so it is doubly important that you, as the database designer, control access to the database profile document. You do this by using the previous agent and creating the Profile role in the database ACL.

 

You retrieve the fields on the profile document using the @Function @GetProfileField , which has the following syntax:

@GetProfileField(profileformname; fieldtext; key)

key is an optional parameter. If your profile document stored the replica ID of the HR lookup database in a field called cHRLookupID, you would retrieve it from the profile document using the following formula:

@GetProfileField("GPF"; "cHRLookupID")

As mentioned earlier, the database profile document is an ideal place to store short keyword lists. This has several advantages. Items in the profile document are cached when the database is opened, so data access is very fast. If you stored short keyword lists in a document, you'd have to create a form plus a visible view and probably a hidden lookup view. That's wasteful for lists that are short, have no other directly associated data, and are not subject to frequent change. For example, you may be creating a workflow database to grant your staff access to various company buildings . You believe that this meets the criteria because the list is short, is relatively constant, and has no other related data that might be dependent upon the building. By storing the list of buildings in the profile database, you could populate a keyword field using a formula like this:

@GetProfileField("GPF"; "cBuilding")

Settings for Profile Documents

The only difference between a regular document and a profile document is how the form is called. When you open a form with @Command([EditProfileDocument]) , the document that is created becomes a profile document. When a profile document is opened, it is automatically placed in edit mode. Because of this, you want to control who creates and edits the profile document for a database. Be sure to deselect Include in Menu and Include in Search Builder on the Form Info tab.

Figure 13.1 shows a database profile document under construction. You can tell where the Formula language can be used in the Object tab of the Info List when the form is in design. Beside each of the form events is a small symbol indicating the types of languages that are available. A small cyan diamond indicates that only the Formula language can be used. If code has been written for the event, the symbol is filled. Figure 13.1 shows the Objects tab for form events.

Figure 13.1. This database profile form has a window title completed in the script area. Note that only one button is needed: Save and Close.

Window Title

Each form can display a title in the window title and the task button in the workspace. If you do not specify a window title formula, the Notes Client displays (Untitled), so it is always a good idea to include this formula, especially for applications intended for use by Notes clients .

If you look at the window title formula in Figure 13.1, you'll see yet another way of making your code reusable. It combines the static text "Database Global Profile for" with @DBTitle , which adds the title of your database to the window title.

NOTE

Web clients do not display the window title, but the value that is returned in the Window Title event is stored in the HTML

tag.

 

Window title formulas are usually fairly simple, although you have a wide range of @Functions available. The window title formula expects text, which is rendered in the window title bar and task button. Usually, you display the name of the form, and the formula simply evaluates it to a text constant. Frequently, designers test whether the document is a new one and display New as part of the window title. Window title formulas are composed in the Window Title event for a form. To create the window title formula shown in Figure 13.1 for the database profile document, use the following steps:

1. Open Domino Designer if you have not done so already, and open the Database Global Profile form.
2. Usually, the Window Title event is displayed by default when you open a form. In case it's not, open the form tree in the Object tab and choose Window Title.
3. Enter the following window title formula. You can click the green check mark to check your syntax.

"Database Global Profile for " + @DbTitle

As you can see, this is a fairly simple formula. There is really not much reason to create complex formulas here because users rarely look at the window title. However, if you want to display whether a document is new, you can use a formula such as this:

@If(@IsNewDoc; "New Building Access Request Form"; 
 "Building Access Request Form for " + cRequester)

WebQueryOpen and WebQuerySave Events

These two events have pre-established formulas. Both events run an agent and use the following @Command:

@Command([ToolsRunMacro]; "")

The WebQueryOpen event runs when the form is opened in a Web browser, and the WebQuerySave event runs when the form is closed. They are functionally equivalent to the LotusScript QueryOpen and QuerySave events.

The agents that you run can be any typeFormula, LotusScript, or Javaand they must be set to one of the Manual options. Because these agents can run on the server, they can accomplish tasks that a Web client cannot.

Domino Web mail uses this technique to send mail. Because a Web browser can't directly send mail, the agent sends the mail when the document is saved.

Insert Subform Formulas

You can write a formula that controls the subform that is inserted at a specific point in a document. This is useful under many circumstances. For example, you might want to have a different set of buttons appear for each client type using your application. The following formula accomplishes this:

@If(@ClientType = "Notes"; "subStdButtons"; "subWebButtons")

A more sophisticated approach is illustrated by the following formula:

@If(@IsNewDoc @Contains(@UserRoles;"Admin") 
 @Contains(cMgrName; @Name([CN]; @UserName));
 "subEditReq";
 "subReadReq")

The subforms involved in this formula, subEditReq and subReadReq, mirror each other, except that one contains editable fields (subEditReq) and the other is read-only. When the document is new, or when users with the Admin role or users who are listed as the manager open the document, they are presented with the editable version. Otherwise, the read-only version is displayed. Similarly, you can insert subforms based on other fields or document conditions.

CAUTION

Using editable and read-only subforms to control the document display is by no means a security feature. The fields in the underlying document can still be edited through an agent, for example. If you need to control who can edit the document and when, using Author fields is a far better solution.