Knowing Where to Use @Functions and @Commands
The Formula language can be used in agents , replication formulas, views, forms, actions, pages, and fields. Most often, you write formulas in the Programmer's pane. In some cases, if an item allows a formula to be written only in the Formula language, there is usually a separate window in which to construct the formula. An example is a formula for a keyword field. (Using the Formula window is discussed in the next section, "Working with the Formula Window.") If there are multiple ways to program an event or object, you do so in the Script area of the Programmer's pane. Objects that can be programmed with Formula language @Functions and @Commands have Formula as a choice in the Run drop-down list.
Working with the Formula Window
The Formula window appears in items that are programmable only with the Formula language. Examples are the Hide Action formula and a keyword field formula. Two window types are available: One is embedded in the properties box, and the other is a modal window launched from the Formula Window button on the properties box. See Figure 12.1 for an example of both types.
Figure 12.1. You can compose a keyword field formula in the properties box or in the larger, modal window; note the formula in the properties box and the Fields and Functions dialog box.
The space inside the properties box is quite limited, but if you have a simple formula to enter, it will often suffice. You can see this window in both Figures 12.1 and 12.2.
Figure 12.2. The syntax checker buttons appear when formulas are modified or created.
When you enter a formula directly in the embedded formula window in the Field properties box, there is a syntax checker available, as shown in Figure 12.2. The syntax checker consists of two buttons, one with a check mark on it and the other with a x symbol. Whenever you enter or modify a formula, these two buttons appear. Clicking the check mark button tests the syntax of the formula. Clicking the x button restores the syntax to its original state. (This same syntax checker is available in the Design pane, discussed in the next section.) In any case, you can't save a formula that is not syntactically correct. You can, however, save a formula that has logic errors even though the syntax is correct, so be careful and test your work.
TIP
To save your work on a formula that is not syntactically correct, enclose the entire formula in quotes or curly braces and place a REM at the beginning of the line. Be sure to use the slash character if there are embedded quotes in the formula. You can later return to the formula, remove the quotes or curly braces, and continue work.
The second type of window is a modal dialog box. Figure 12.1 shows a keyword formula being constructed in the modal Formula window using @DBColumn( ). This larger window is launched from the Formula Window button in the properties box. In addition to having a larger area in which to work, the formula window has a Fields and Functions button that launches a pick list for database fields and @Functions. Unfortunately, there is no syntax checker for this window. However, when you click the Done button, the syntax is tested ; you can't exit the modal window unless the syntax is correct.
Writing Formulas in the Script Area
The Design pane is discussed in Chapter 3 and is covered briefly here in the context of writing formulas. Figure 12.3 shows an input validation formula for a field. This formula ensures that the user cannot save the document without entering information into the cSubject field.
Figure 12.3. The Script area is used to construct many types of formulas, including the formula for the Input Validation event.
To the left of the Script area, you will notice that the Info List is open to the Objects tab and that the Input Validation event is selected. The formula in Listing 12.4 is typical of fields with required entry.
Listing 12.4 Input Validation for the cSubject Field
REM "Do not execute this formula unless the doc is being saved!"; REM "If the cSubject field is empty, @Failure returns a "; REM "window to the user which displays the text in the quotes."; REM "The cursor is then positioned in the cSubject field." ; @If(@IsDocBeingSaved & cSubject = ""; @Failure("You must enter a subject for this document!"); @Success)
If you make a syntax error, Domino Designer catches it when you try to exit the field or save the form. Clicking the syntax checker button also catches any mistakes. If there is an error, a message appears at the bottom of the Design pane and the offending entry is changed to red. Figure 12.4 shows an error condition in the formula listed earlier.
Figure 12.4. An extra right parenthesis was placed at the end of the @If() statement to generate an error; the error message is at the bottom of the Script area.
Figures 12.3 and 12.4 showed the Objects tab in the Programmer's pane, which lists all of the programmable events for the object. The Reference tab contains extensive help for programming the object. Figure 12.5 shows the Reference tab for the Input Validation event. In the drop-down list, you can choose from Database Fields, Formula @Commands, and Formula @Functions. For events that have other scripting languages available, choices appear for those languages as well. Selecting an item in the Reference list and clicking Help opens a separate application window with the appropriate Help document displayed. The Paste button can be clicked to copy the field or command into the Script area.
Figure 12.5. The Reference tab allows programmers to choose fields and language components to use in the current object.