OnPress property

Invoked when the user presses the button.

Only action formulas may be associated with this property. Unlike a regular formula, which calculates a value, an action formula makes something happen. It does so by assigning a value to another property using := or by invoking an action function.

(Of course, regular functions may be used to calculate the value to assign to a property with :=, and to calculate the parameters given to action functions.)

An action function can do everything that a regular button can, including sending email, copying values to the clipboard, displaying a different screen and showing messages. Action formulas also have access to functions not accessible to regular buttons, which enable you to ask users to enter text or numbers, show transient banners and ask users for confirmation.

Unlike regular buttons, a formula button can perform multiple actions, either one after another, or by waiting for one to complete before invoking the next one. Action formulas can also use conditional logic, meaning that an action is only performed if one condition is TRUE, otherwise another action is performed. This makes it possible to model complex business logic.

This action formula shows a message:

This action formula assigns a value to Field1:

This action formula hides a text box:

Here is the full list of action functions.

Using IF to express conditions

Use a function like IF or SWITCH to perform one action if a condition evaluates to TRUE and another action otherwise.

This formula sends an email if all fields in the app are valid and shows a message otherwise:

App.Fields.ValidApp,Fields,Valid returns a logical array, where TRUE indicates that a corresponding field is valid and FALSE indicates that a corresponding field is invalid. AND returns TRUE only if all those elements are TRUE, meaning that all fields are valid.

Running multiple actions

A button can run any number of actions. Separate actions with ;;;.

This action formula assigns two values to two different fields and hides a text box:

By chaining together multiple actions with ;;;, you can create buttons that do nothing but calculate values. For some apps, this can be an appealing alternative to having Calcapp calculate values as the user types.

This formula resets all fields of the app and then brings the user back to the first screen:

This formula assigns values to the fields of a screen named SecondScreen, before taking users to it:

If users should only be able to reach the second screen through the button, and not by pressing Next in the upper-right corner, ensure that the NextScreenAvailable property of whatever screen precedes it is set to FALSE.

Waiting for actions to complete

Many action functions perform actions that can take some time to complete. EMAILREPORT, for instance, sends a report through email. It does so by asking our server to create the report and send it, which takes a second or two.

EMAILREPORT lets you perform other actions while our server is busy fulfilling the request. This action formula asks our server to start the process, and then immediately shows a banner:

If you want to perform an action once the report has been successfully sent, use the AWAIT function. This formula shows another banner when the report has been sent:

Handling errors

The AWAIT function takes three parameters: the action, the formula fragment which is run when the action completes successfully and the formula fragment which is run if there is a problem completing the action. Only one of the latter two parameters must be provided, meaning that you can write a formula that only takes action if a completing the first action fails.

This formula shows an error message if sending a report fails:

Above, the third parameter, OnFailure, is given a name. That enables us to completely leave out the second parameter, which we don't need. An alternative to naming the third parameter is to use BLANK()BLANK() as the value for the second parameter:

The third parameter has access to a special value, named Error, which has more information on the error, including an error message.

If an action function does not complete successfully, and you don't handle the error by providing an OnFailure parameter, your app will show an error message. If you don't want your users to see any error messages, not even your own, you can pass BLANK()BLANK() as the OnFailure parameter.

Asking users questions

Use the PROMPT and PROMPT.NUMBER functions to ask users to enter text strings or numbers, respectively. Use AWAIT to read the entered value.

This formula asks the user to enter the email address where a report should be sent, before sending the report:

The second parameter to AWAIT has access to a special value named Result, containing the result communicated by the action. For PROMPT the result is the text string entered by the user. For PROMPT.NUMBER, the result is the number entered by the user.

(This is similar to the third parameter to AWAIT, which has access to a special value named Error, with additional information on what went wrong.)

If you like, you can use -> to rename the Result value:

You can ask the user any number of questions:

When asking multiple questions with PROMPT, it is necessary to rename the Result value. If we don't, there is no way to access results other than the last one.

Finally, use CONFIRM to ask users to confirm a choice. This formula asks the user to confirm before resetting all fields of the app, immediately followed by displaying the first screen:

Examples