G Suite Business customers can preview App Maker. Ask your domain admin to apply for early access.

Widget Logic

There are two ways to provide additional logic to your UI: events and input constraints.

Events

You can make your UI more dynamic by defining widgets' actions in response to events. For example, the onClick event on button widgets determines what buttons do when clicked.

Most widgets have at least three events available: onAttach, onDetach, and onDataLoad. Some widgets have additional events related to their intended use. For example, a Text field widget has an onValueChanged event, but not an onClick event.

Use the Events section of the Property Editor to define how a widget responds to events. Click the arrow next to an event name to open the Choose an Event dialog. Select one of the premade scripts there, or write your own script by clicking Custom Action.

Event Name Description
onAttach Executes a script when the widget is attached to the DOM.
Example: An onAttach event on the main panel of an app could read a cookie to initialize state when a view loads.
onDetach Executes a script when the widget is detached from the DOM.
Example: An onDetach event on the main panel of an app could write to a cookie to save the current state of a view when a user leaves.
onDataLoad Executes a script when the widget and its data loads.
Example: An onDataLoad event on a list widget could hide certain rows of the panel based on the results of a query.
onClick Executes a script when the user clicks the widget. Available on button, link, and other clickable widgets.
Example: An onClick event on a button could bring the user to a different view.
onValueChange Executes a script when the widget's value property changes.
Example: An onValueChange event on a text field could execute a search on the field's datasource after a user finishes entering a query.
onValueEdit Executes a script when a user edits the widget's value. Unlike onValueChange, this event doesn't run in response to bindings or programmatic changes.
Example: An onValueEdit event on a text field could highlight matching terms in response to a search query.
onValidate Executes a script when the widget's value changes or another script triggers validation. The script only executes if the new value satisfies the widget's constraints.
Validation note: Return an empty string, null, or undefined for valid values. Return a non-empty string with an error message for invalid values.

Validate input

It's often helpful to validate user input before saving it to a database. For example, your app might require that a supplied phone number has the correct number of digits or that a user's first and last name fields are both filled in. In App Maker, you can use constraints to validate input or write your own validation scripts that run during onValidate events.

Validation with constraints

Text field and text area widgets have a Data Validation section in their Property Editor. These constraints trigger when the widget's value changes, and can display an error if the constraints aren't met. Constraints accept explicit values, data bindings, or binding expressions.

Property Description
required When enabled, indicates that input is required.
minLength Defines the minimum allowed character length of the string, including whitespace. Leading or trailing whitespaces aren't counted.
maxLength Defines the maximum character length of the string, including whitespace. Leading or trailing whitespaces aren't counted.
regexp Defines a regular expression to validate user input. Uses the JavaScript regular expression library.
Example: An expression that matches any US Postal code format: ^\d{5}(-\d{4})?$.

Validation with onValidate events

The onValidate event allows you to write your own validation scripts. It's best used in the following cases:

  • Your use case is more complex than widget and field constraints can cover.
  • You need to provide error custom messages.
  • Your validation depends on the value of other fields or widgets.

The onValidate event works with constraints, as it only triggers if the value passes constraints.

Example: A hotel booking app, wants to let users to enter a value between 1 and 21 for their floor number, but not 13.

Set the min length constraint to 1, the max length constraint to 21, and check for the unlucky number in the widget's onValidate event:

  if (newValue == 13) {
    return "Please select a number with a bit more luck.";
  }

Trigger validation with the validate method

Constraints and onValidate scripts only trigger when a widget's value changes, and sometimes that isn't enough. For example, if you have a form with validation on every field, but a user clicks Submit without filling out a single one, their validation checks might never run.

To avoid this scenario, you can trigger validation using the validate method. Using the example above, you could attach the following code to the onClick event of the Submit button, assuming it's in the same panel as the validated fields:

  if (widget.parent.validate()) {
    // We passed validation! Do whatever you want here...
  }

Alternatively, you can validate each widget explicitly:

  if (widget.parent.children.WidgetToValidate.validate()) {
    // We passed validation! Do whatever you want here...
  }

Validation priority

App Maker validates widgets in the following order:

  1. Widget constraints:
  2. Required
  3. Max/min length/number
  4. Regular expression
  5. onValidate event
  6. Bound properties constraints like field constraints

Validation stops as soon as any step determines a value is invalid. For example, with the required constraint checked, the onValidate event nevers receives a null value, as that value fails validation during the constraints check.

Bound properties aren't updated until a new value passes validation. If a widget becomes valid after failing its initial check, as a result of a validate() call, bindings involving its value property update appropriately.