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

Scripting Overview

App Maker makes it possible to create relatively complex apps without coding, but sometimes you need functionality that widgets and the model editor alone can't provide. App Maker's JavaScript script editor can help you fill in the gaps.

There are two types of scripts in App Maker: client scripts that run on users' browsers and server scripts that run on App Maker servers. Here are just a few examples of what you can do with scripts in App Maker:

  • Perform app-specific logic and calculations
  • Connect to external web services
  • Create custom permission checks
  • And more...

Client and server scripts

Though client and server scripts both run JavaScript, they differ in where they're used and even how they function.

Client script quick facts

  • Client scripts run on users' browsers. They can access the DOM, browser local storage, and more.
  • Client scripts can edit widget properties. App Maker exposes widgets as JavaScript objects, so you can change their appearance, events, and other properties programmatically.
  • Client scripts block the browser. To keep apps responsive, complex calculations should be avoided in client scripts.

  • Client APIs are asynchronous. Some client script calls execute out of order. See the work with data models example below for details.

  • Client scripts aren't secure. Advanced users can see and change client scripts with browser tools. Don't rely on them for data security or consistency.

Server script quick facts

  • Server scripts run on Apps Script. They can access databases directly and use Apps Script APIs like calendar, email, and more.
  • Server scripts don't keep state between requests. They run on distributed servers, so each time you call a scripts its global variables are empty.
  • Server scripts are sometimes subject to quotas. Calls to Apps Script services are limited by daily quotas.
  • Server scripts can be secure. Unlike client scripts, you can trust server scripts to control access to sensitive data. Use them for auditing and to enforce data consistency.

Script examples

The easiest way to understand the difference between client and server scripts is by example. The scripts below are from a to-do list app that lets users create multiple to-do lists, each with multiple to-do items.

Client: interact with pages and widgets

This onClick script for DeleteTodoListButton switches to a confirmation page when a user clicks the button:

app.showPage(app.pages.DeleteTodoListConfirmationView);

Client: implement property bindings

This script is a binding expression for DeleteTodoListButton's enabled property. It ensures that the button is only enabled when there aren't any to-do items in a list, so users can only delete empty to-do lists.

@datasource.item != null && @datasource.item.TodoItems.length == 0

Client and server: work with data models

Client:

This script creates and selects a new to-do list. It first calls a server script to create a new list record, then reloads the TodoList model, and finally selects the newly-created list.

function onCreateTodoListClick() {
  var datasource = app.datasources.TodoList;
  google.script.run.withSuccessHandler(function(newKey) {

    // When created, redisplay todo lists.
    datasource.load(function() {

      // When reloaded, select new todo list.
      datasource.selectKey(newKey);
    });
  }).createTodoListWithItem();
}

You might notice that the code doesn't match the order of operations above. That's because this script, like many client scripts, executes asynchronously. The script can't just execute createTodoListWithItem() then load(), because, both being asynchronous, there's no guarantee that a new to-do list will be created before the datasource reloads.

Instead, createTodoListWithItem() calls load() with a callback that only executes after a to-do list item is successfully created. Learn more about asynchronous scripts and callbacks in Client Scripts.

Server:

This server script is createTodoListWithItem(), called from the client script above. It accesses the app's database to create a new to-do list and an item for that list, then returns the list's Key.

function createTodoListWithItem() {
  // Automatically number todo lists for the user.
  var lock = LockService.getScriptLock();
  lock.waitLock(10000);
  var query = app.models.TodoList.newQuery();
  var allTodoLists = query.run();
  var todoList = app.models.TodoList.newRecord();
  var newListNumber = allTodoLists.length + 1;
  todoList.name = "My list " + newListNumber;
  app.saveRecords([todoList]);
  lock.releaseLock();

  // Create first todo item for user convenience.
  var todoItem = app.models.TodoItem.newRecord();
  todoItem.TodoList = todoList;
  app.saveRecords([todoItem]);
  return todoList._key;
}

Server scripts don't save their data automatically, so the script calls saveRecords() to save its changes to the model. Remember to do the same when writing your own scripts that create or edit records.

The script also uses locking to ensure data consistency. Learn more about locking in Server Scripts.

Server: security, auditing, and data consistency

Server scripts help you keep your data consistent and secure. The script above used the lock service to achieve atomicity of query and create operations.

You can also implement custom permissions by using exceptions to disallow certain model events. For example, adding the following to a model's onDelete() event prevents record deletion:

throw "Deletions now allowed";

You can also create audits using the onCreate() handler:

var email = Session.getActiveUser().getEmail();
record.setAudit("Created on " + new Date() + " by user " + email + "\n");

Client and server: fetch data from other URLs

Client:

Use an XMLHttpRequest, or App Maker's HtmlArea widget to inject an IFRAME.

Server:

Use Apps Script's URL Fetch Service.

Client: integrate custom JavaScript libraries

There are two ways to load external JavaScript libraries, depending on the library:

JsHint validation instructions

App Maker supports some JsHint directives: JsHint options

Globals

The globals directive tells the static checker about global variables defined outside of App Maker:

 /* globals externalVar1, externalVar2 */
 var foo = externalVar1 + externalVar2; // no warnings
 alert(foo); // no warnings

Ignore

The ignore directive turns off the static checker for a block of code:

 /* jshint ignore:start */
 var foo = externalVar1 + externalVar2; // no warnings
 alert(foo); // no warnings
 /* jshint ignore:end */
 alert(undefinedVar); // "Unknown identifier"