Tutorial 2: Work with Data

Intermediate App Maker skills

access_time 15-20 minutes

What you’ll build

You’ll build a simple employee database app. A user of the app can:

  • Create new employee records and enter data in them
  • Edit employee records
  • Navigate between records
  • Sort records
  • Delete records

What you’ll learn

This tutorial teaches you how to:

  • Create a data model and add fields to it. You learn data-related concepts—models, fields, records, datasources, and data bindings.
  • Add form and table widgets to a page. You learn how to modify these widgets and how they work. You also learn the difference between insert forms and edit forms.

Create your app

  1. Sign in to the G Suite account provided by your employer or school.
  2. Open App Maker.
  3. Create a blank app:
    • If App Maker displays the welcome dialog, click Create New App.
    • Otherwise, click Menu menu chevron_right New chevron_right Blank Application.
  4. Rename the app Employee Database.

Create a model

Create a model and define its fields. A model contains the data that is available in your app. Model fields are like columns in a table, for example, Name, Email, and HireDate. Models store data in records, like rows in a table. For this tutorial, you’ll use a Google Cloud SQL model.

  1. In the left navigation, point to Data and click Add add. The Create Model dialog opens with Google Cloud SQL selected.
  2. Click Next.
  3. Name the model EmployeeData.
  4. Click Create. App Maker creates the model and opens the Model editor.
  5. Click the Datasources tab. Notice that the model has one datasource named EmployeeData that's automatically created by App Maker. A datasource sets what data in the database is available in the app UI.
  6. Click EmployeeData to open the datasource editor and inspect the datasource settings.

    By default, all data is available (no Query is set), the datasource is automatically loaded (Automatically load data is selected), and changes are automatically saved (Manual save mode isn't selected). For this app, the default behavior is OK. For other apps, you might want to turn off Automatically load data if you want to pass a query from the user first. You might want to turn on Manual save mode if you want users to explicitly save changes to records in the datasource. For example, they might have to click a Save changes button.

Add fields to the model

In the Fields tab, for each field:

  1. Click Add New Field and select the field type.
  2. In the Name field, enter the field name. You can leave the description and other settings unchanged.

    Add the following fields:

    Field nameField type
    NameString
    EmailString
    HireDateDate
    ActiveBoolean

Set up a page for the UI

Your app has one page to start. Name the page and assign it your model's datasource. When you create a page, it has no predefined datasource. When you select a datasource for a page, widgets on the page automatically inherit the datasource.

  1. In the left sidebar, point to NewPage and click More more_vert chevron_right Rename
  2. Enter EmployeePage and click OK.
  3. In the Property Editor (visible when Editor edit is selected), click the datasource property.
  4. Click EmployeeData to select it as the datasource.

Add an edit form

An edit form lets a user:

  • Create new records in the database
  • Enter data for the records
  • Select values for fields that have choices, such as boolean fields, date fields, and fields that have possible values
  • Edit data in records
  • Delete records from the database

To add an edit form:

  1. Open the Widgets palette (click Widgets ) and add a Form Form Widget to the page.
  2. Because you set the page datasource to Inherited: EmployeeData, that datasource is automatically suggested. Keep it selected and click Next.
  3. In the Choose form type dialog, select Edit then click Next.
  4. Specify options for the form:

    • Field—Select the datasource fields to include in the form.
    • Editable—Set fields as editable.

    For this tutorial, keep the defaults. The default options create a form that includes all datasource fields. All fields but Id are editable.

  5. Click Finish.

Add a table

A table shows data as rows and columns. Rows correspond to records in the model and columns correspond to fields. A user can use a table to:

  • View multiple records at the same time and move between pages of data
  • Edit record data in editable fields
  • Sort records by column
  • Delete records

To add a table:

  1. From Widgets , add a Table Form Widget to the page below the edit form. Align the left edges of the edit form and table.
  2. Because you set the page datasource to Inherited: EmployeeData, that datasource is automatically suggested. Keep it selected and click Next.
  3. Specify options for the table:

    • Field—Select the datasource fields to use as columns in the table.
    • Editable—Select which fields are editable.

    For this tutorial, keep the defaults. The default options create a table with columns that correspond to all datasource fields and none are editable. In general, apps perform best when they don't have too many editable fields. Instead of a fully editable table, provide popup dialogs to create and edit records and a read-only table to review records, as in this tutorial.

  4. Click Next.

  5. Keep the additional options—paginated, sortable, and deletable rows.

  6. Click Finish.

Preview and test your app

  1. In the top-right corner, click Preview to run your app in a new browser tab.
  2. Click Allow to let your app use specific information.
  3. Enlarge the browser window to fit the entire edit form and the top of the table.
  4. In the Edit EmployeeData form, try to enter a name in the Name field. You can’t because there isn’t a record yet.
  5. Click Create to create a record. The app adds the record to the table. This is a real record in the database. Now you can enter data and it is automatically saved to the database. This behavior is useful when a user wants to update a record, but it isn't intuitive to create a record. Insert forms, described later in this tutorial, are a more intuitive way for users to add data.
  6. Fill in the form. As you enter data and select values, App Maker adds the values to the table. The data is live for each field as soon as you press Enter, click outside a field, or make a selection.
  7. Click Create to create an additional record, and enter data for that record.
  8. Select one of the records in the table. Click Delete delete in the edit form to delete the record. There’s no automatic undo, though that could be done with scripts.
  9. Note the controls App Maker adds to the bottom of the form. Use them to navigate between pages of data.

Congratulations! You’ve just built an App Maker app that works with data.

Explore the power behind the UI

Before you close this tutorial, explore the features that provide the power behind the UI: bindings, events, and actions.

Learn about bindings

A binding is a two-way link between a widget property and another property. A data binding is when a widget property is bound to a property of a datasource.

Because bindings are two-way, changing one bound property changes the other.

Explore how the app UI uses bindings:

  1. If the app Preview tab is still open, close it and go back to App Maker.
  2. On the Edit Employee form, select the Name text box.
  3. In the Property Editor, notice that the value property is set to @datasource.item.Name.

    This binding links the value of Name in the edit form with the value of Name for the record in the datasource. The path in the value property defines the binding as:

    • datasource—Refers to the datasource for the widget
    • item—Refers to the currently selected item (record)
    • Name—Refers to the record's value for Name
  4. In the Property Editor, select the label property. Notice that it is set to @models.EmployeeData.fields.Name.displayName.

    This binding links the label of the Name text box in the edit form with the displayName property of the Name field in the EmployeeData model. The path in the label property defines this binding as:

    • models.EmployeeData—Refers to the EmployeeData model.
    • fields.Name.displayName—Refers to the displayName property of the Name field.

Learn about events and actions

You can connect things that occur (events) with responses (actions).

Events trigger actions. App events include:

  • An app starts
  • A datasource loads
  • An app checks permissions
  • A user clicks a button
  • An app accesses or changes data
  • An app validates data

Actions are responses to events. Actions include:

  • Create a new item
  • Delete the current item
  • Reload a datasource
  • Run a client script

Explore how the app uses events and actions:

  1. In the Edit EmployeeData form, select the Create button.
  2. In the Property Editor, locate onClick. The onClick event is when the user clicks the Create button. The onClick event is listed in both the Button and Events sections (the same item is shown in two places, for convenience).
  3. Click onClick. The menu includes possible actions to take when the user clicks the button. In this case, the action is a custom script. Click Custom action to open the code. This code creates an item in the datasource that is assigned to the widget. App Maker has a Create new item preset action, but that action is for insert forms.
  4. In the canvas (the page editor), in the table, click the Name header.
  5. In the Property Editor, click onClick > Custom action. When the user clicks the Name header, the action is a custom script that sorts the table by the Name field.

Compare an insert form to an edit form

Before you leave the topic of forms, compare an edit form to an insert form.

Earlier in this tutorial, you found that an edit form lets the user edit a record in the database. When no records exist, the user must create a record before they can enter data. In contrast, an insert form initially saves data to a single draft record that’s in the datasource, not in the database. When the user is ready, they explicitly save the contents of the draft record to the database.

An insert form lets a user:

  • Enter data and select values in fields in a draft record
  • Save the contents of the draft record in a new record in the database. After the data is copied, the draft record is emptied.

Add an insert form

  1. From Widgets , add a Form Form Widget to the page next to the edit form.
  2. The Inherited: EmployeeData datasource is selected by default. Leave this selection and click Next.
  3. Select Insert and click Next. Leave all fields selected so that they're present on the form and editable.
  4. Click Finish.

Explore how the insert form works

  1. In the top-right corner, click Preview to run your app in a new browser tab.
  2. If the table contains records, point to the row and click Delete delete until no records are present.
  3. Fill in the Create EmployeeData form. You can enter data immediately, unlike the Edit Employee form, but the data isn't added to the table. As you enter data, App Maker saves it to the draft record in the datasource, not the database. The table doesn't update until you save the record to the database.
  4. Click Submit to create a real record in the database. App Maker copies the data from the draft record to the real record, then empties the draft record. Now the data is in the table because the data is in the database. The data also appears in the edit form, which contains data from the currently selected record.

    When you enter data in the edit form, data doesn't appear in the insert form, because the values in the insert form are bound to the draft record.

Explore how an insert form is built

  1. If the app Preview tab is still open, close it and go back to App Maker.
  2. On the Create EmployeeData form, select the Name text box.
  3. In the Property Editor, notice that the value property is set to @datasource.item.Name, the same as the edit form. However, because this form is an insert form, this binding links the value of Name in the insert form with the value of Name for the draft record in the datasource. Learn more about draft records and create-mode datasources.
  4. Now select the Submit button. Notice that the action for the onClick event is Create New Item. For an insert form, the Create New Item action:
    1. Creates a new record in the database
    2. Copies the contents of the draft record into the new record
    3. Clears the draft record

Next steps

  • Take Tutorial 3—Learn about styling an app.
  • Learn more about data—Read the documentation on models
  • Study the sample app—The Hello Data app replicates your work here, with some changes to the edit form.