PROMPT function

Prompts the user for a text string and returns a promise with the entered value. AWAIT(PROMPT("What's your name?"), BANNER("Hi " & Result & "!"))AWAIT(PROMPT("What's your name?"); BANNER("Hi " & Result & "!")) asks the user for their name and greets them once the name has been entered.

This function can only be used from an action formula. It is typically invoked from a formula associated with the OnPress property of a formula button.

The Title parameter may be used to set the title of the prompt. Use InitialValue to provide the value of the text field the user edits when the prompt is first shown. If either parameter is omitted, a blank value is assumed.

The prompt has a cancel button and an OK button. The labels may be set using the CancelLabel and OkLabel parameters, respectively. If a label is omitted, a label appropriate for the language of the app is used.

To prompt the user for a number, use PROMPT.NUMBER instead.

Reading the entered text string

PROMPT returns a promise, effectively promising to return the entered value at some point in the future. Use AWAIT to read the value.

The first parameter to AWAIT should be the promise returned from PROMPT and the second parameter should be a formula fragment that is run when the user presses the OK button. The formula fragment has access to the entered value under the name Result.

This formula asks the user to enter an email address and then sends a report containing all fields of the app to the entered email address:

AWAIT(PROMPT("Enter recipient:", Title: "Input"), EMAILREPORT({ App }, Result))AWAIT(PROMPT("Enter recipient:"; Title: "Input"); EMAILREPORT({ App }; Result))

The OK button of the prompt is enabled at all times, meaning that any text string is accepted. For a formula that only accepts valid email addresses, see below.

Storing the entered value for later use

If a report is typically sent to the same email address, asking the user to enter this address every time a button is pressed is not ideal. To solve this issue, the entered email address can be stored in a hidden field that retains its value even when the app is closed, named StoredEmailAddress.

Consider this formula:

AWAIT(PROMPT("Enter recipient:", Title: "Input", InitialValue: StoredEmailAddress), EMAILREPORT({ App }, Result); StoredEmailAddress := Result)AWAIT(PROMPT("Enter recipient:"; Title: "Input"; InitialValue: StoredEmailAddress); EMAILREPORT({ App }; Result);; StoredEmailAddress := Result)

The formula above asks the user for an email address before sending a report. It sets the initial value to the value of the StoredEmailAddress field and stores the entered email address in that field once it has been filled out, for use the next time the formula is run.

The formula stores the value using :=, which assigns values to properties. ;;; separates actions in an action formula, which are run one after the other.

Determining if the OK button should be enabled

The OkButtonEnabled parameter may be set to a formula fragment which returns whether the OK button should be enabled. To do its work, it has access to the input text string provided by the user, under the name Input. The formula fragment is run every time the user makes a change to determine if the OK button should be enabled.

This formula only enables the OK button if the length of the entered text string is greater than two:

PROMPT("Enter a value", Title: "Input", OkButtonEnabled: LEN(Input) > 2)PROMPT("Enter a value"; Title: "Input"; OkButtonEnabled: LEN(Input) > 2)

This formula only enables the OK button if the user has entered a valid email address:

PROMPT("Enter an email address", Title: "Input", OkButtonEnabled: ISEMAIL(Input))PROMPT("Enter an email address"; Title: "Input"; OkButtonEnabled: ISEMAIL(Input))

This formula only enables the OK button if the user has entered a valid US Social Security number:

PROMPT("Enter a Social Security number:", "Input", OkButtonEnabled: REGEXMATCH(Input, "^\d{3}-\d{2}-\d{4}$"))PROMPT("Enter a Social Security number:"; "Input"; OkButtonEnabled: REGEXMATCH(Input; "^\d{3}-\d{2}-\d{4}$"))

The formula above uses a regular expression, which only matches text strings that start with three digits, followed by a hyphen, two digits, a hyphen and four digits. Refer to the documentation for the REGEXMATCH function to learn more.

Asking multiple questions

With AWAIT, an arbitrary number of questions can be asked in succession. As an exercise, let's write a formula that asks a user their name and age and displays this information.

Recall that the first example formula asks the user for their name and displays it as a banner:

AWAIT(PROMPT("What's your name?"), BANNER("Hi " & Result & "!"))AWAIT(PROMPT("What's your name?"); BANNER("Hi " & Result & "!"))

Let's expand on this formula and ask the user's age too. Here's a first attempt:

AWAIT(PROMPT("What's your name?"), AWAIT(PROMPT.NUMBER("How old are you?"), BANNER("You're " & Result)))AWAIT(PROMPT("What's your name?"); AWAIT(PROMPT.NUMBER("How old are you?"); BANNER("You're " & Result)))

That works, but the banner only displays the age of the user, not their name.

Displaying both collected text strings presents us with a problem: as the entered age is available under the name Result, there is no way to access the entered name, which is also available as Result. Essentially, the new invocations of AWAIT and PROMPT overwrite the name with the age, making the name inaccessible.

This problem can be solved by renaming the results returned from AWAIT using ->, making them available under distinct names:

AWAIT(PROMPT("What's your name?"), Name -> AWAIT(PROMPT.NUMBER("How old are you?"), Age -> ALERT("Your name is " & Name & " and you're " & Age & ".")))AWAIT(PROMPT("What's your name?"); Name -> AWAIT(PROMPT.NUMBER("How old are you?"); Age -> ALERT("Your name is " & Name & " and you're " & Age & ".")))

Examples

AWAIT(PROMPT("What's your name?"), BANNER("Hi " & Result & "!"))AWAIT(PROMPT("What's your name?"); BANNER("Hi " & Result & "!"))

Asks the user for their name and greets them once the name has been entered.

AWAIT(PROMPT("What's your name?"), Name -> AWAIT(PROMPT.NUMBER("How old are you?"), Age -> ALERT("Your name is " & Name & " and you're " & Age & ".")))AWAIT(PROMPT("What's your name?"); Name -> AWAIT(PROMPT.NUMBER("How old are you?"); Age -> ALERT("Your name is " & Name & " and you're " & Age & ".")))

Asks the user for their name, then asks the user for their age, and finally displays an alert containing the information the user entered. The information the user enters is available as the values Name and Age, which is accomplished using ->.

AWAIT(PROMPT("Enter recipient:", "Input", OkButtonEnabled: ISEMAIL(Input)), EMAILREPORT({ App }, Result))AWAIT(PROMPT("Enter recipient:"; "Input"; OkButtonEnabled: ISEMAIL(Input)); EMAILREPORT({ App }; Result))

Asks the user to enter an email address and then sends a report containing all fields of the app to the provided email address. The OK button is only enabled if a valid email address has been entered.

AWAIT(PROMPT("Enter value:", InitialValue: StoredValue), StoredValue := Result)AWAIT(PROMPT("Enter value:"; InitialValue: StoredValue); StoredValue := Result)

Asks the user to enter a value and then stores this value as the value of the hidden field StoredValue, which retains its value even when the app is closed. The initial value of the prompt is set to the value of StoredValue, ensuring that the user is presented with their previously-entered value the next time the formula is run.