@Prompt (Formula Language)

Displays a dialog box to the user and returns a text value based on the user's actions in the dialog box. @Prompt is useful for prompting a user for information and determining a course of action based on the user's input.

Summary of Dialog Box Styles

This table shows the different styles of dialog boxes you can display. @Prompt accepts parameters and returns a value based on the style you indicate.


Style	Purpose	Contains	Return value
ChooseDatabase	Allows user to select a database	Controls and displays for browsing databases; Open, Select, Cancel, Browse, Help, and About buttons	Text list of 3 values. Server name, file name, and title of database. Returns null for server name if the database is local.
LocalBrowse	Allows user to select a file name from the local file system	Controls and displays for browsing local file system; Select, Cancel, and Network or Help buttons	Text. File name that user selected or entered.
Ok	Displays an informational message	Title and prompt; OK button	1 (True).
OkCancelCombo	Allows user to select one value from a drop-down list of choices	Title and prompt; List of choices; OK and Cancel buttons	Text. Value that user selected.
OkCancelEdit	Allows user to type in text input	Title and prompt; Text box for input; OK and Cancel buttons	Text. Value that user entered.
OkCancelEditCombo	Allows user to select one value from a list of choices, or type in a different value	Title and prompt; List of choices with text box; OK and Cancel buttons	Text. Value that user selected or entered.
OkCancelList	Allows user to select one value from a list of choices	Title and prompt; List of choices; OK and Cancel buttons	Text. Value that user selected.
OkCancelListMult	Allows user to select multiple values from a list of choices	Title and prompt; List of choices; OK and Cancel buttons	Text list. All values that user selected.
Password	Allows user to enter password without displaying it on the screen	Title and prompt; Text box that accepts and hides user input; OK and Cancel buttons	Text. Password that user entered.
YesNo	Allows user to make a Yes/No decision	Title and prompt; Yes and No buttons	1 (True, Yes) or 0 (False, No).
YesNoCancel	Allows user to make a Yes/No decision, or Cancel	Title and prompt; Yes, No, and Cancel buttons	1 (True, Yes), 0 (False, No), or -1 (Cancel).

Syntax

@Prompt( [ style ] : [NoSort] ; title ; prompt ; defaultChoice ; choiceList ; filetype )

Parameters

[ style ]

Keyword. Required. Indicates the type of dialog box to display. May be any of the following:

[ChooseDatabase]

[LocalBrowse]

[Ok]

[OkCancelCombo]

[OkCancelEdit]

[OkCancelEditCombo]

[OkCancelList]

[OkCancelListMult]

[Password]

[YesNo]

[YesNoCancel]

Include the brackets ([ ]); these identify the style parameters as keywords. If no [NoSort] keyword is provided, follow the style parameter with a semicolon (;).

[NoSort]

Keyword. Optional. Include this keyword if you want the members of choiceList to appear in the exact order in which you enter them. If you omit this keyword, the members of choiceList are sorted alphabetically.

title

Text. The text you want displayed in the dialog box's title bar. Required for all styles, although you can specify a null string with "". The maximum number of characters you can include in a title is 65. Provide a null string with the [ChooseDatabase] keyword; you cannot replace the default "Choose Database" title.

prompt

Text. The text you want displayed within the dialog box. Required for all styles, except LocalBrowse. If you use a formula for prompt and that formula returns a list, only the first item in the list is displayed as the prompt. To display the entire list, use @Implode. You can specify a field name to display the contents of the field as the prompt, but the field must be a text field. If it is a number or datetime field, precede it with @Text. @NewLine cannot be used in prompt. Use @Char(13) to insert a carriage return. The maximum number of characters you can include in the text that displays is 255. Provide a null string for the [ChooseDatabase] keyword; you cannot display custom text in the Choose Database dialog box.

defaultChoice

Text. The value that will be used as the default value for the user's input. The input section of the dialog box is primed with the value; the user can either accept it by clicking OK or replace it with another value. Not applicable to dialog boxes of style [Ok], [YesNo], [YesNoCancel], [LocalBrowse], or [Password]. Required for all other styles. For [OkCancelListMult], you can specify multiple default values as a text list "item1":"item2."

choiceList

Text list. The values that you want displayed in the dialog box's list box. The user can select one of these values as the input. Separate the values with colons, as in: "PHONE.NSF":@MailDbName. Each value in your list can be a text string, or an @function that returns a text string. Required only with styles [OkCancelList], [OkCancelCombo], [OkCancelEditCombo], and [OkCancelListMult].

filetype

Text. A value that specifies the types of files to display initially: "1" for NSF files only; "2" for NTF files only; "3" for files of all type. Required only with style [LocalBrowse].

Return value

choice

If the user enters a value, returns the value as text or a text list.
If the user selects Yes, returns 1 (True).
If the user selects No, returns 0 (False).
If the user selects Cancel, formula evaluation stops. The exception is [YesNoCancel], which returns -1 if the user selects Cancel.
@Prompt([OkCancelEdit]) returns only the first 254 characters of the text entered.

Usage

Use @Prompt in field formula, toolbar button, manual agent, form action, and view action formulas. This function does not work in column, selection, mail agent, or scheduled agent formulas, and has limited usefulness in window title and form formulas.

The title and prompt parameters are scalar. If you enter a list, only the first element displays. Use @Implode to convert the list to a string.

You cannot use this function in Web applications.

Examples

[Ok] displays an informational message; the user clicks OK to close the dialog box. Use this style when you want to inform the user about something, without receiving anything back except an acknowledgement.
```
@Prompt([Ok];"Reminder";"Don't forget to run backup tonight.")
```
This variation displays the contents of a multi-value item by imploding it.
```
@Prompt([Ok];"Value of mylist"; @Implode(mylist))
```
[YesNo] displays a warning, and gives the user a chance to proceed or cancel the operation. If the user selects Yes the numeric value 1 is returned. If the user selects No the numeric value 0 is returned.
```
@Prompt([YesNo]; "Send memo?"; "This memo will be sent to everyone listed in the To, CC, and BCC fields.")
```
[YesNoCancel] also displays a warning, and gives the user a chance to select Yes, No, or Cancel. If the user selects Cancel, the value -1 is returned.
```
result=@Prompt([YesNoCancel]; "Send memo?"; "This memo will be sent to everyone listed in the To, CC, and BCC fields" )
```
[OkCancelEdit] prompts the user to enter his or her name, which is returned as a text string. The name defaults to the current user's Notes/Domino user name, which is calculated using @UserName. If the user selects Cancel, Notes/Domino cancels the formula evaluation. Note that @Prompt([OkCancelEdit]) returns only the first 254 characters of the text entered.
```
@Prompt([OkCancelEdit]; "Enter Your Name"; "Type your name in the box below."; @UserName) 
```
[OkCancelList] displays a list box with database names (sorted alphabetically), prompts the user to select a database, and returns that database's name as a text string for use in a subsequent operation. If the user selects Cancel, Notes/Domino cancels the formula evaluation.
The third option in the list is the current user's own mail database, the name of which is calculated with @MailDbName. The user must select one of the listed options; by default, Schedule is highlighted (the value listed as the default must also be included in the display list).
```
@Prompt([OkCancelList]; "Select a Database"; "Select a database to open."; "Schedule"; "Schedule":"Phone Book":@Subset(@MailDbName;-1))
```
[OkCancelCombo] displays a dialog box similar to example 5, except that a drop-down list is used, so that initially only the default value is displayed. The user clicks the down arrow on the box to display the rest of the list. As in example 5, the user must select one of the listed values; by default, Schedule is selected. This function returns the user's selection. If the user selects Cancel, Notes/Domino cancels the formula evaluation.
```
@Prompt([OkCancelCombo]; "Select a Database"; "Select a database to open."; "Schedule"; "Schedule":"Phone Book":@Subset(@MailDbName;-1))
```
[OkCancelEditCombo] is similar to example 6, except here the user can edit the text box and type in any database name; this way, the user is not limited to the selections in the list. This function returns the user's selection or entry. If the user selects Cancel, Notes/Domino cancels the formula evaluation.
The default value must be included in the list, or the text box that displays initially will be blank.
```
@Prompt([OkCancelEditCombo]; "Select a Database"; "Select a database to open, or type a database specification."; "Schedule"; "Schedule":"Phone Book": @Subset(@MailDbName;-1))
```
[OkCancelListMult] displays a list of names, from which the user can select one or more (Mary Tsen appears as the default selection). This function returns the user's selection(s). If the user selects Cancel, Notes/Domino cancels the formula evaluation.
The default value must be included in the list.
```
@Prompt([OkCancelListMult]; "Select a Name"; "Select one or more names as recipients for this request."; "Mary Tsen"; "Mary Tsen":"Bill Chu": "Michael Bowling":"Marian Woodward")
```
[Password] displays a dialog box where the user can enter a password. Notes/Domino does not display the password on the screen. This function returns the password.
```
@Prompt([Password]; "Password"; "Enter the password for Approach database.")
```
[LocalBrowse] provides controls and displays that allow you to browse and select a name from the local file system. This example opens the Notes/Domino database file the user selects from the local browser. The "1" restricts the initial display to .nsf files.
```
file := @Prompt([LocalBrowse]; "Select a database to open"; "1");
@If(file = ""; @Return(1); "");
@Command([FileOpenDatabase]; "" :@Left(file; " "))
```
This code, in a form hotspot button, displays the Choose Database dialog box then sets field values on the document (which must be in edit mode) based on the result.
```
result := @Prompt([ChooseDatabase];"";"");
FIELD Server := result[1];
FIELD Filename := result[2];
FIELD Title := result[3]
```