Using Simple Triggers in Google Drive

In this previous post I described how to write your first, simple, Google Apps Script. Let’s build on that a little by looking at Simple Triggers. Google Sheets, Docs and Forms can all use triggers. Triggers are a script resource that allow code to run in response to some event they detect.

There are various types of trigger including Installable Triggers and Time-Driven Triggers but in this post we’ll just consider the most straightforward type, Simple Triggers.

To create a Simple Trigger, you need to make a function with a special name; there are three such names to choose from, depending on what you’re trying to achieve:

Triggers of the onOpen() type run when you first open a spreadsheet, document, or form. A common use for this kind of trigger is to add a custom menu to the editor’s menu bar.

onEdit() triggers run when one or more cells of a spreadsheet are edited. You might use this type of trigger to record or email details of the change that’s just been made, for example.

Triggers with type onInstall() run when a script is installed from the Add-on store or from the script gallery.

Let’s use a trigger of the onOpen() type to add a custom menu to a spreadsheet. Open the script editor from within your sheet by using Tools > Script editor… then erase any code already listed and enter this:

// Add a custom menu to a spreadsheet.
function onOpen() {
 // create a variable 'sheet' that references the current spreadsheet:
 var sheet = SpreadsheetApp.getActiveSpreadsheet();

 // make a new array 'menuItems' to store the items in the custom menu:
 var menuItems = [];

 // Define the new menu items:
 menuItems.push({name: "Menu Item 1", functionName: "function1"});
 menuItems.push({name: "Menu Item 2", functionName: "function2"});
 menuItems.push({name: "Menu Item 3", functionName: "function3"});

 // add hem to the menu
 sheet.addMenu("MyNewMenu", menuItems);
}

function function1() {

}

function function2() {

}

function function3() {

}

The empty function definitions function1, function2 and function3 will hold the code you want to run when the menu item is selected. We’ll leave these blank for the purposes of this demo. Here’s the code in the code editor:

Click image to enlarge

Click image to enlarge

Save the code using File > Save (give it a name of your choice when prompted) then close and re-open the spreadsheet.

If all has gone well, your new menu will be created once the spreadsheet has opened:

Click image to enlarge

Click image to enlarge

Simple Triggers have a few limitations that you should be aware of. They can’t, for instance, access any services that require user authentication. For example, the Google Translate and Maps services are anonymous and can be accessed by s simple trigger, whereas services like Calendar, Gmail etc. are out of bounds. Also, simple triggers can only modify the current document, and are forbidden from accessing any others.