Data Events allow users to perform specific actions when certain events are triggered. Actions can include things like custom alerts and validation messages, setting field values, choices, labels, descriptions, requirement & visibility settings, HTTP requests and more. Event triggers include things like record loading, editing, validating, saving, value changing, and more.
How Data Events Work
You can think of Data Events as an extension of calculation fields. While calculation fields allow you to define dynamic expressions for a particular field, data events allow you to define actions for the entire record. You have access to all the existing calculation expressions, in addition to many data event functions for building out truly custom workflows.
When building your app, you will see a “Data Events” button in the app builder setting sidebar on the right. Clicking this launches a modal window, very similar to the expression builder modal for calculated fields. This is where you define your data events for form actions.
save-record event, which calls the
changeStatus function when the record is saved. Inside the
changeStatus function, we are calling the
SETSTATUS function with a status parameter of ‘inspected’.
This could easily be expanded to programmatically set the record status based on values from other fields or even filter the list of available status options based on the user or their role.
We’ve exposed the following events that you can hook into while building your forms.
load-repeatable- Fires when the record / repeatable editor is displayed
new-repeatable- Fires when a new record / repeatable is created, after
edit-repeatable- Fires when a record / repeatable is edited, after
save-repeatable- Fires immediately before a record / repeatable is saved and after it’s been validated
validate-repeatable- Fires right before the record / repeatable is saved to check any validations
change-geometry- Fires when a record’s / repeatable’s geometry changes
change-project- Fires when a record’s project changes
change-status- Fires when a record’s status changes
change- Fires when a field’s value changes
click- Fires when a hyperlink field is tapped
add-photo- Fires when a photo is added
add-video- Fires when a video is added
add-audio- Fires when an audio clip is added
After registering an event to listen for, you’ll generally want to take some type of action. Actions typically fall into the following categories:
Display A Message
ALERT- Displays a message as an alert popup
INVALID- Displays a validation error message and prevent the record or repeatable item from being saved
PROGRESS- Displays a non-dismissible progress message (useful when loading external data)
Messagebox- Displays a message that allows the user to select an option within the message box that is being displayed.
Set Form Elements
SETDESCRIPTION- Sets the description of a field
SETHIDDEN- Sets the visibility of a field
SETLABEL- Sets the label of a field
SETMAXLENGTH- Sets the maximum length for a field
SETMINLENGTH- Sets the minimum length for a field
SETREADONLY- Sets a field to be read-only or editable
SETFORMATTRIBUTES- Set various attributes of your app, like being able to save as draft or the photo quality settings.
Set Field Values
SETLOCATION- Sets the location of the record
SETPROJECT- Sets the project of the record
SETSTATUS- Sets the status of the record
SETVALUE- Sets the value of a field
Set Field Options
SETCHOICEFILTER- Filters the choices in a choice field
SETCHOICES- Sets the available choices for a choice field
SETSTATUSFILTER- Sets the available choices for a status field
Interact With External Services
OPENURL- Opens a URL for a website or mobile app
REQUEST- Performs an HTTP request and executes the callback on completion