AWAIT function

Waits for a promise to return a response before running an action. 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 first parameter to AWAIT must be a promise. A function returning such a value promises to return a value at some point in the future, or at the very least indicate whether the operation the function started was successful. A promise either succeeds or fails, and it can only succeed or fail once.

The promise returned from PROMPT succeeds when the user has entered a value and presses a button. The value returned is the text string the user entered. The promise returned from EMAILREPORT succeeds when the report has been successfully sent — with no value returned — and fails if there is a network problem.

AWAIT and other similar functions are used to take action when a promise succeeds or fails.

Handling promises that succeed

AWAIT runs the formula fragment given as its second parameter when, and if, the promise succeeds. If the promise returns a result, it is available to the second parameter under the name Result.

This formula sends a report and shows a banner once it has been successfully sent:

AWAIT(EMAILREPORT({ App }, "test@example.com"), BANNER("Sent!"))AWAIT(EMAILREPORT({ App }; "test@example.com"); BANNER("Sent!"))

Handling promises that fail

AWAIT runs the formula fragment given as its third parameter when, and if, the promise fails. The third parameter to AWAIT has access to more information on the error which caused the failure, in the form of a value named Error.

This formula shows a banner when sending a report succeeds and an alert when it fails:

AWAIT(EMAILREPORT({ App }, "test@example.com"), BANNER("Done!"), ALERT("Could not send report: " & Error.Message & ".", "Error"))AWAIT(EMAILREPORT({ App }; "test@example.com"); BANNER("Done!"); ALERT("Could not send report: " & Error,Message & "."; "Error"))

The alert body contains an error message, which is available through the Error value available to the third parameter when EMAILREPORT fails.

If an action should be taken when a promise fails, but no action should be taken when it succeeds, BLANK()BLANK() can be given as the second parameter. Fully omitting the second parameter and naming the third parameter often makes for more readable formulas, though:

AWAIT(EMAILREPORT({ App }, "test@example.com"), OnFailure: ALERT("Could not send report: " & Error.Message & ".", "Error"))AWAIT(EMAILREPORT({ App }; "test@example.com"); OnFailure: ALERT("Could not send report: " & Error,Message & "."; "Error"))

If you don't handle promises that fail using the third parameter, your app displays an error message to your users. Use this parameter to show your own message instead, using a function like BANNER or ALERT. You can also provide BLANK()BLANK() as this parameter, if you don't want anything to happen if the promise fails.

AWAIT versus ;;;

AWAIT waits for the promise given to it to either succeed or fail before running either of its formula fragments. If two actions should be invoked one after another, use ;;; instead.

This formula sends two reports — one after another — containing different fields, sent to different recipients and without waiting for the first one to succeed or fail before sending the second one:

EMAILREPORT({ App }, "office@example.com"); EMAILREPORT({ Result }, App.UserEmailAddress)EMAILREPORT({ App }; "office@example.com");; EMAILREPORT({ Result }; App,UserEmailAddress)

This formula shows a banner with the message Sending report... and immediately sends a report. Then, when the report has been sent successfully, it shows another banner with the message Report sent:

BANNER("Sending report..."); AWAIT(EMAILREPORT({ App }, "test@example.com"), BANNER("Report sent"))BANNER("Sending report...");; AWAIT(EMAILREPORT({ App }; "test@example.com"); BANNER("Report sent"))

Using AWAITALL with the result returned from AWAIT

AWAIT returns the promise provided as its first parameter, which is useful on occasion.

This formula uses AWAITALL to show a banner with the message All reports sent once two reports have both been successfully sent:

AWAITALL({ EMAILREPORT({ App }, "user1@example.com"), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("All reports sent"))AWAITALL({ EMAILREPORT({ App }; "user1@example.com"); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("All reports sent"))

AWAITALL only runs the formula fragment given as its second parameter once all promises provided as its first parameter have succeeded. The promises given to AWAITALL are provided as an array, with { serving as the start of the array and } serving as the end of the array.

If a banner should be displayed when the first report has been sent successfully, wrap the first EMAILREPORT invocation with AWAIT:

AWAITALL({ AWAIT(EMAILREPORT({ App }, "user1@example.com"), BANNER("First report sent")), EMAILREPORT({ Result }, "user2@example.com") }, BANNER("All reports sent"))AWAITALL({ AWAIT(EMAILREPORT({ App }; "user1@example.com"); BANNER("First report sent")); EMAILREPORT({ Result }; "user2@example.com") }; BANNER("All reports sent"))

The reason this works is because AWAIT returns the promise it is given. From the perspective of AWAITALL, the array of promises it is passed looks the same no matter which of the formulas is used.

Examples

AWAIT(ALERT("Test"), BANNER("OK button pressed"))AWAIT(ALERT("Test"); BANNER("OK button pressed"))

Shows an alert, with a message and an OK button, and waits for the user to press the button. Once the user presses the button, a banner is shown.

AWAIT(PROMPT.NUMBER("Enter number:"), BANNER("Half of " & Result & " is " & (Result / 2)))AWAIT(PROMPT.NUMBER("Enter number:"); BANNER("Half of " & Result & " is " & (Result / 2)))

Asks the user to enter a number. Once the user has done so, the entered number and the entered number divided by two are shown in a banner.

AWAIT(EMAILREPORT({ App }, "test@example.com"), OnFailure: BANNER("Could not send report"))AWAIT(EMAILREPORT({ App }; "test@example.com"); OnFailure: BANNER("Could not send report"))

Sends a report, containing all fields of the app, and shows a banner if the report could not be sent successfully.