Getting User Input

You can use several @Functions to get input from users, including @DialogBox() , @PickList() and @Prompt() . @Prompt has a number of variations, from a simple OK dialog box to a multivalue select box. The function @DialogBox() displays any form for user input, but it is most effective when used with a form or subform containing a layout region or a table. Using @DialogBox() in that fashion enables you to create what appear to be standard Windows dialog boxes. The @Picklist() function displays either a view or a Domino directory in a dialog box.

CAUTION

Each of the @Functions discussed in this section are available only to Notes clients . They will not function on the Web.

Using @Prompt

@Prompt has a number of useful styles. The syntax of @Prompt is as follows :

@Prompt([style] : [ NOSORT ] ; windowtitle ; promptText ; defaultChoice ; choiceList ; fileType )

Table 12.13 describes the styles for @Prompt .

Table 12.13. @Prompt Style

CAUTION

Be careful using @Prompt() , @DialogBox() , and @Picklist() in agents. Agents using the Formula language operate on one document at a time and do not store values from one document to the next . It is often good practice to restrict an agent using these @Functions to the setting Manually from an Agent List, which keeps the agent from appearing in the Action menu. You then launch the agent from a Form Action Bar button. If you enable the user to run the agent from the menu, he can potentially run it on multiple documents ”literally, hundreds and hundreds, or worse , all documents in the database. It would be extremely frustrating to the end user to answer @Prompt([OKCANCELEDIT]...) over and over again.

The following is an example of code from an agent that runs manually from the agent list and that is launched by an action button in a view. This example shows you how @Prompt() can be used to obtain user feedback and incorporate that feedback in a document:

REM "Find out how many hours it took"; jnHours := @Prompt([OKCANCELEDIT]; "Effort"; "Please enter the number of hours."; 0); @If(jnHours = 0; @Return(""); @Success); FIELD nActual := jnHours; FIELD cStatus := "Completed"; FIELD dComplete := @Today

Figure 12.10 shows the dialog box displayed by the agent using @Prompt .

Figure 12.10. The prompt box asking for the number of hours is displayed by @Prompt([OKCANCELEDIT...) .

Using @DialogBox

@DialogBox() can be used with any form or subform to gather or display input. If the form or subform contains layout regions or tables, @DialogBox() will display the first layout region or table. Figure 12.11 shows the use of @DialogBox() with a subform containing a layout region. The layout region is set to 3D, which gives the dialog box a standard Windows look and feel. When the dialog box is opened, any fields on the form that have corresponding fields in the underlying document are inherited. Similarly, unless you specify otherwise , when you close the dialog box by clicking OK, the values you have entered in the dialog box are saved to the underlying document.

Figure 12.11. Using @DialogBox() to get user input is a powerful tool.

For the values entered using @DialogBox , the underlying document must be in edit mode. @DialogBox has several parameters that you can use to determine whether it displays information, stores it in the document, or allows new fields to be written to the document. You can also specify a title for the window and the location of the buttons. The syntax of @DialogBox() is as follows:

@DialogBox( formname ; [AutoHorzFit] : [AutoVertFit] : [NoCancel] : [NoNewFields] : [NoFieldUpdate] : [ReadOnly] ; [SizeToTable] ; [NoOkCancel] : [OkCancelAtBottom] ; windowtitle )

The parameters for @DialogBox are described in Table 12.14.

Table 12.14. @DialogBox Parameters

All parameters are optional except formname . If you are using a layout region, it is best to use both [AutoHorzFit] and [AutoVertFit] parameters. The following formula for an action button launches an edit window into a sales document:

@DialogBox("subDBoxSales";[AutoHorzFit]:[AutoVertFit]:[OkCancelAtBottom]; "Sales Dialog Box Example")

TIP

If you looked at the last formula, you might have seen the title of the dialog box source, subDialogSales. You don't have to create a full-blown form for @DialogBox . You can create a layout region on a subform and call it in the same way you call a form. Consider adding a prefix such as dBox or subDBox to the form or subform name to distinguish it from other forms or subforms. For example, dBoxHistory could be used for a subform used to display document history.

Using @PickList()

The function @PickList() loads displays either a view or a lookup into the Domino directory in a dialog box with OK and Cancel buttons. It is extremely fast and does not cache the results. The syntax is as follows:

@PickList([CUSTOM]:[SINGLE]; server:file; viewName; windowTitle; promptText; columnNumber; category)

Table 12.15 describes the pick list styles available. Figure 12.12 shows an example. The following is the code that produced the pick list:

@PickList([Custom] ; ""; "PL"; "Parts List"; "Choose a part"; 1);

Figure 12.12. @PickList produces a dialog box using a view. A check mark indicates which document(s) have been selected.

Table 12.15. @PickList Styles

R5 added the capability to use a replica ID in @PickList() . This removed a serious limitation in that, before R5, you had to know the filename and path relative to the data directory to call @PickList() .

@Picklist() can also display a lookup into the Domino directory. The following is the syntax for that lookup:

@PickList([Name] : [Single])

If you specify Single , Notes displays a list from the Domino directory that enables you to choose a single name. Otherwise, you get the familiar two-pane mover dialog box that enables the user to select multiple entries from the Domino directory.