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.

  Note: List fields are only available in Calculated and Directory models.

  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

Note: Dates created by client scripts use the default browser timezone, while dates created by server scripts use getScriptTimeZone(), which returns the script creator's timezone.

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.

Note: Some text input widgets can also perform data validation. Look for a Data Validation section in the Property Editor. Data validation for models is more secure than data validation in an app's UI.

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. Values for dates are always validated against UTC, even when a widget is configured to use the browser's time zone.
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).

Note: Empty strings are valid input for required fields. To ensure that users provide non-empty values, set a minimum length for string fields.

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 widgets—Specific 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

Note: To aid the user and constrain items in the list to a predefined set, for example, days of the week or a list of skills, you can define choices for the items in the list field in a separate model or as possible values in the model. Provide a multi select widget for the user to select among the choices. Don’t provide a text box for entering data. To let users enter other values too, use a different list field.