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

Bind Widgets to Data

App Maker makes it easy to connect your app's UI to data with data binding. Data binding establishes a two-way link between a widget property and a datasource. This link allows your widgets to access and update data from models, relations, and other App Maker properties.

Datasources

Datasources give widgets a simple way to access data. They provide a list of items that represent data of some kind, usually data model records or record relations. They also have a singular item which represents the currently-selected item from the items list. Widgets use the list to access records, edit relations, and much more.

You can see a widget's current datasource in its datasource property in the Property Editor. Widgets inherit their datasource from their parent widget, unless you explicitly assign a different one. You can only assign layout widgets' datasources. All other widgets receive their datasources through inheritance, so it's often helpful to use layout widgets to group other widgets both visually and logically.

Model datasources

App Maker automatically creates a model datasource for each model you add. Model datasources act as bridges between widgets in an app and data on the server. A datasource builds its items list from a query sent to the server. Widgets can then use that list to create, read, update, and delete records from the model.

Read more about model datasources.

Relation datasources

Relation datasources are an extension of model datasources that allow you to access and modify relations for a selected model. They use inheritance to find the currently-selected record from a parent widget's datasource and retrieve a list of related records for that record.

A relation datasource's items property is a list of all records related to the parent widget's current record. Its item is a single record from that list. Because a relation datasource's item is a record, it's possible to have a relation datasource based on another relation datasource.

Read more about relation datasource.

More datasources

While model and relation datasources are most common, App Maker lets you use any property in your app as a datasource. For example, you can use user groups or custom properties as datasources. To access other datasources, click Advanced at the bottom of the Choose datasource pop-up.

Bindings

A binding is a two-way link between a widget property and a different property, usually a property of that widget's datasource. Because bindings are two-way, a change to one bound property is reflected in the other. For example, you could bind the value property of a text box to an EmployeeName field in a model datasource of an onboarding app. Users could use the text box to update employee names on the server. Additionally, any change to a name on the server automatically updates the text displayed in the text box.

Add bindings

To open the binding selector, click arrow_drop_down chevron_right Binding next to a widget property in the Property Editor, and then click the property. If Binding is already visible, just click the property.

The binding selector lets you add bindings by declaring binding paths that tell App Maker where a bound property is in relation to the current widget. The selector has two modes:

  • Simple: The simple binding selector lists the properties of the current item of the datasource and automatically creates a binding path based on your selection. It opens by default for any widget with a datasource when no binding has been defined, or when the defined binding matches the selection.

  • Advanced: The advanced binding selector lets you bind any property in the app. Use the wizard at the top of the selector to generate a path or write your own in the Binding expression field at the bottom. Access the advanced selector by clicking Open Advanced from the simple binding selector. It also opens by default for widgets without datasources, and for widgets with datasources when a defined binding doesn't match a selection in the simple binding selector. Click Less... to display the simple binding selector.

Binding expressions

A binding expression is a JavaScript expression that lets you perform operations on the output of binding paths. A single binding expression can include multiple binding paths, but only one JavaScript expression. If you need more than one JavaScript expression, use the binding expression to call a client script and supply binding paths as parameters.

App Maker recalculates binding expressions when the value of any binding path in the expression changes. Binding expressions only impact how widgets display data, and can't change the actual data in a binding path. This means that you can't use binding expressions in the value field of input widgets. Use simple binding paths instead.

Sample binding expression: "Hello, " + @user.username + ". My name is " + @widget.name + "."

Projections

Projections let you access properties from records in a datasource's items list. Access projections with the ..projections.. option in the advanced binding wizard, or use the projection operator .. in a binding path. For example, for an Employees datasource with a name property, @datasources.Employee.items..name returns a list of all employees' names.

Custom Properties

Custom properties are page-level properties that store data for a single user session. Custom properties are useful when you need to bind properties of multiple widgets to a single value. For example, bind the visible property of several menu widgets to a boolean ShowAll custom property to toggle the visibility of those widgets as a group.

Create custom properties by selecting a page's main panel, and clicking the Custom Properties group in the Property Editor. Access the current page's custom properties from the advanced binding selector, using either the properties option in the wizard or the @properties shortcut in a binding expression. To access a different page's custom properties, use the page option in the wizard or the @pages shortcut.

Additional resources

  1. Properties and Bindings: Take an in-depth, conceptual look at properties and bindings.
  2. Model Datasources: Learn more about model and relation datasources.
  3. Relations Guide: Get hands-on experience with relation datasources.
  4. Client API—DataSource: See all datasource properties and methods available in client scripts.