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 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.
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.
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.
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.
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.
To open the binding selector, clicknext to a widget property in the Property Editor, and then click the property. If 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.
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 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
@datasources.Employee.items..name returns a list of all employees' names.
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
- Properties and Bindings: Take an in-depth, conceptual look at properties and bindings.
- Model Datasources: Learn more about model and relation datasources.
- Relations Guide: Get hands-on experience with relation datasources.
- Client API—DataSource: See all datasource properties and methods available in client scripts.