Introduction to Datasources in Google App Maker

Understanding what a datasource is and how to use it is key to building pages that works with data in App Maker. This article will cover the basics of working with datasources.

For a more general introduction of Google App Maker, please refer to my Getting Started with App Maker tutorials.

What is a Datasource?

When you create your first data model in App Maker, you may notice there is a tab named “Datasource” when you are viewing your model. These are known as query datasources. One will be automatically created for you when you create a new data model, and by default it will have the same name as your data model.

A Data Model in App Maker named “Project” — by default, it has a datasource named Project that can be found under the Datasources tab

A query datasource can be seen as a view of your data. It is analogous to a filtered view on a spreadsheet — when you apply a filter, you will generally only see a subset of your records, but all the data is still there behind the scenes. In App Maker, your data is stored in the model, and you can have one or more datasources to set up different views with different filters/sorting applied to that data. Since pages in your application access you data through datasources, you can set up different datasources that are catered to the needs of your pages.

Example of a data model with 2 datasources. In this example task list application, users can view one page to review all tasks, or view a different page to work only with incomplete tasks. We can set up two datasources — one that returns all tasks, and one that only returns incomplete tasks. The pages will use the datasource that has the data it needs to show to the user.
In App Maker, you can add additional datasource using the [Add Datasource] button when viewing your data model

Using datasources in the UI

App Maker UI widgets access data through data bindings to datasources. Datasources can be assigned to the Page itself, or to a Table or a Form widget, or any widgets under the Layout section such as the Fixed Panel. These widgets act as containers where you can place other widgets inside, and the child widgets will inherit the datasource assigned to the parent container.

A layout widget (Horizontal Panel) with the “IncompleteTask” datasource assigned, as seen in the Property Editor panel on the right. The TextBox placed inside the panel inherits the IncompleteTask datasource, which cannot be changed.

A page can utilize multiple datasources by having multiple Layout widgets with different datasources assigned. A datasource can also be shared between multiple pages.

Example of a page that uses two Table Widgets with different datasources assigned, showing two different views of the same data
Example of two different pages using the same datasource. Different widgets are used on each page — the left one uses the List widget while the right uses the Table widget — but the view of the data is the same as it is the same datasource. Even the selected data record (highlighted) is the same when user switch between the two pages due to the shared datasource

When writing client-side scripts, a widget’s datasource can be accessed using widget.datasource. You can also access a datasource by name using app.datasources.{datasourceName} , e.g. app.datasources.IncompleteTask. Some useful properties & functions of the datasource includes:

  • items - the list of records in the datasource. For example, datasource.items.length will give you the number of records in the widget’s datasource.
  • item- the currently selected item in the items list. By default this is the first record in the items list. The currently selected item is the easiest to see in Table or List type widgets where it gets highlighted. The user can change this by clicking on the record on these widgets. The item is null if there are no records in the datasource items list.
  • query allows you to apply filters and sorting criteria through client side script. See “Setting up filters in a Datasource” section below for more information.
  • load() triggers the reload of the datasource. This will make the app retrieve the most up-to-date data from the server at the time to refresh what’s shown in the widgets.

Setting up Filters in a Datasource

So how do you apply different filter criteria to different datasources to produce different views of the data? One of the easier method to achieve this is to set up the Query property in your datasource through server side script. You can access this by expanding the Datasource panel in App Maker and selecting “Query Script” under the Query section.

Expanded panel showing the “IncompleteTask” datasource’s query script. This script applies a filter to look for records where Status = “Incomplete” so that the datasource will only return records that satisfy the filter.

You can read more about the Query object in the reference documentation. To apply a filter to your data, you can write a script in the following format:

query.filters.{fieldName}._{filterType}= {filterValue};

where

  • {fieldName} is the name of the field in the data model that you want to apply the filter on
  • {filterType} is the comparison type for your filter, e.g. equals, notEquals, lessThan, greaterThan. You can find the full list in the reference documentation.
  • {filterValue} is the target value for your filter.

Examples:

  • query.filters.Status._notEquals = "Complete"; — this will return records where its Status does not equal Complete.
  • query.filters.Priority.lessThan = 3; — this will return records with Priority < 3.
  • query.filters.Status._in = ["Incomplete", "In Progress", "Waiting"]; — this will return records where its Status is Incomplete, or In Progress, or Waiting. Note that the “In” and “notIn” filters expects an array as its filter value.

In your Query Script, after you have written out your filters, they should be followed by the line return query.run(); so that the query is executed in your datasource to return your filtered results to the UI.

You can also apply filters on the client side (e.g. when scripting an OnClick event) through the datasource’s query object. The format of the script is quite similar to the server-side script — e.g. app.datasources.IncompleteTask.query.filters.Status._equal = "Incomplete"; will apply a Status = Incomplete filter to the IncompleteTask datasource. Note that you must call reload afterwards to apply the filter, e.g. app.datasource.IncompleteTask.load(); .

Example of applying the filter on the client-side. The Button [View Incomplete Only] inherits the same datasource as the Table widget. By writing the script to apply the filter in the onClick event on the button and to reload the datasource, the user will be able to apply that filter by clicking the button.

For More Information

You can read Google’s official documentation on datasources for more information. There are many other options and parameters that you can set to tailor a datasource to your needs, such as sorting, turning off automatic data load, etc. If you are a beginner just starting out with App Maker, the default datasource created for you should be sufficient for simple applications, but as you start to grow your application to create more specialized data views for different types of users and use cases, learning how to set up and utilize multiple datasources will help you put the right data into your pages.

Visit my blog or follow me on twitter for more App Maker content!

Cleo is a Google Developer Expert for Google Workspace based out of Vancouver, BC, Canada.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store