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

Fields

Fields let you categorize data in models. For example, an Employee model might have a FirstName field to store people's first names.

Fields are columns in a table. Records are the rows. Data goes into the fields in each record. For example, in the fourth record, the FirstName field might contain Bob.

You can put data into fields with server scripts, client scripts, and bindings.

Input from scripts must match the field's type. You can ensure the correct data type in the script, or use a binding transformer in the binding expression to convert data to the correct type. When possible, App Maker automatically converts input from an app's UI to the appropriate type.

Create fields

When you create a field, you assign it a type that determines the kind of data it holds. For example, a String field holds strings of characters such as names or email addresses, while a Number field holds numbers.

You can create:

  • Simple fields—Simple fields can contain at most one value. Most fields in your app are probably simple fields. Each field in each record contains either nothing (null) or a single value. For example, the JobTitle field in a specific record might contain:

    Software Engineer

    You can sort records by the data in simple fields. Labels used as column headings in the Table widget have predefined onClick actions that sort the table; for example:

    window._am.sortTableBy(widget.datasource,
        widget.datasource.model.fields.LastName,
        widget, window._am.TableState);

  • List fields—List fields can contain more than one value. App Maker stores the values in list fields as arrays.

    Each list field in each record contains either nothing (an empty array, [], not null), a single value, or multiple values. For example, the Measurements field in a specific record might contain:

    [0.312,1.245,1.434,1.789, 42]

    You can't sort records by the data in list fields.

Data types for simple fields

Type Description Example
String String of Unicode characters Field: FirstName

Contents: Susan

Number 64-bit floating point number Field: EmployeeID

Contents: 13465

Boolean true or false Field: IsActive

Contents: true

Date Date object Field: HireDate

Contents: 2015-09-28

Data types for list fields

Type Description Example
List<String> List of strings Field: FoodAllergies

Array: ["pecans","walnuts","shrimp"]

List<Number> List of numbers Field: MRITesla

Array: [1.2,1.5,3,7]

List<Boolean> List of Boolean values Field: Answers

Array: [true,false,false,true]

List<Date> List of dates Field: ReviewDate

Array: [2014-07-12,2015-07-15]

Set field properties

You can set field properties in the Fields tab of each model.

Name Description
Type The type of data your field stores—String, Number, Boolean, or Date for simple fields; or List<String>, List<Number>, List<Boolean> or List<Date> for list fields. The field type is not editable. To change the field type, delete and recreate the field.
Name A unique label used to access the field. It can only contain alphanumeric characters and underscores and must start with a letter.
SQL Type (Google Cloud SQL only) The underlying SQL type used to store the field's data.
Display Name A more human-readable name for your field. It doesn't have to be unique, and can include spaces and special characters.
Description A place to describe the field; used for reference only.
Use a Default Value If selected, you can specify a default value to use when an app creates a record.

Use default values

By default, App Maker uses null as the default value for all simple fields except Booleans, which default to false. For list fields, App Maker uses an empty array as the default value.

Checking Use a Default Value lets you set your own default value. Setting a default value can be useful for required fields, which don't accept null, and for any field that has a natural default state. For example, an Employee model with a Status field could default to Active, because each new record probably represents a new, active employee.

App Maker uses default values as initial values in the following cases:

  • A datasource's draft record
  • A record created in a datasource that uses manual save mode
  • A record created on the server using newRecord()
  • A record imported from a Google spreadsheet or a CSV file for which that field's value isn't specified

Validate data

Use data validation constraints for fields to restrict the data a field accepts. For example, you could ensure that a ZipCode field has a 5-digit value or that a Name field is at least two characters long. Available constraints vary by the type of field.

For list fields, if any validation criteria are set, then all items in a list must satisfy the validation criteria. For example, 2,3,5,3.235 fails Whole Number validation because 3.235 is not a whole number.

Name Type Description
Required All If selected, records won't save when the field is null, undefined, or an array with null elements (for list fields).
Minimum Length and Maximum Length String The minimum and maximum character lengths for the field.
Possible Values String, Number, Date A list that determines which inputs the field accepts.
Regular Expression String A set of conditions that a string must satisfy for a record that contains a field with this value to be saved.

Learn more about regular expressions.

Regular Expression Error Message String The error message an app displays when input doesn't match the specified regular expression.
Minimum Value and Maximum Value Number, Date The minimum and maximum value for the field.
Whole Number Number If selected, records won't save if the field's number contains significant decimal places. The numbers 4., 4.0, 0., .0, and 0.0 are whole numbers, as you would expect. Although the number 1.0000000000000001 is not a whole number, but App Maker considers it to be a whole number, because the number after the decimal point is not significant.
SQLtype Date

(Cloud SQL models only.) Controls how App Maker handles time zones:

  • TIMESTAMP—includes a time zone. App Maker converts the time to PT (UTC−7 or UTC−8) before writing it to the database.
  • DATE and DATETIME—doesn't include time zone information. App Maker reads and writes data as PT (UTC−7 or UTC−8).

Create records with required fields

App Maker throws an error when you try to create a record with a required field that is null or undefined, or an array with null elements for a list field. Here are several things you can do to avoid these errors:

  • Assign a default value—The simplest solution; a default value guarantees that a field has a value upon creation, avoiding any validation errors.
  • (Server side) Use a draft record—The newRecord() method lets you set required fields before saving a record to your model.
  • (Client side) Use a draft record—Automatic save mode datasources have a draft record in which scripts and data bindings can enter values before creating records.
  • (Client side) Use a manual save mode datasource—In manual save mode, users or scripts can fill in required fields before saving a record to avoid validation errors.

Get data into and out of list fields

You can get data into and out of list fields in these ways:

  • Use server or client scripts—Scripts can read and write the items in a list field’s array.
  • Use widgetsSpecific widgets and binding expressions work with list fields.
  • Use import and export—App Maker can import and export records that contain list fields.

Syntax for commas and quotation marks

In an app's UI and in Google spreadsheets intended for import operations or that result from export operations, the contents of list fields are comma-separated lists; for example:

capable truck,magnificent truck,best truck

Items in a string list field can contain commas. To distinguish content-commas from separator-commas, a special syntax is used for the UI and a different special syntax is used for import and export. For import and export, a special syntax is also used for double quotation marks.

Aspect UI syntax Import and export syntax
Comma in content Use \, (backslash comma) Surround the list item with double quotation marks
Double quotation marks in content No special syntax Surround the list item with double quotation marks and double the quotation marks in the content (" becomes "").

No special syntax is needed for single quotation marks. If an item contains both a comma and one or more double quotation marks, surround the item with only one set of double quotation marks.

Leading and trailing spaces in an item are stripped away when the data is saved.

Examples
UI syntax Import and export syntax
horse,dog,cat horse,dog,cat
horse,dog\,cat horse,"dog,cat"
horse,a "beautiful" dog,cat horse,"a ""beautiful"" dog",cat
horse,a "beautiful\, strange\," exotic dog, cat horse,"a ""beautiful, strange,"" exotic dog",cat