Google Apps Script Custom Menus

 

It is fitting that my first post on this site is about custom menus with Google Apps Script, because, often, custom menus are your users’ first touch with your custom functionality. Your users will be surprised the first time they see the custom menu on their Google App UI. And they will be delighted when the functionality fulfills their expectations. This post will show how to surprise and delight your users with the Google Apps Script UI menus. 

 

Google Apps Script UI Menu

 

 

How Custom Menus Work

Custom menus allow you to execute the Google Apps Script functions that you have defined. Each menu item, when clicked, triggers the Google Apps Script function that corresponds to that menu item. Custom menus are easy to create, and we will get to that in a minute, but let’s get a few questions out of the way first.

Menus can be created and modified*, but menus cannot be deleted.

Most often, Menus are created with the onOpen() function, but they can also be created by an ay trigger or event. For example, you could use a menu item click to create another menu. Similarly, many Google Docs add-ons use the add-on menu to create a menu to offer access to the functions of their add-on.

Unfortunately, Menus cannot be dynamically created. The menu item names can be, but the functions that the menu items trigger can not be. This will become clear later, but the functions that are called by each menu item must be defined in advance and cannot take arguments. If you want to call functions with dynamic inputs, use the PromptResponse class or the value of the active cell if you are using Google Spreadsheets.

Menus can be modified in the sense that they can be replaced with an updated instance (copy) of the same menu. Any time the .createMenu() is used to create a menu with a name that has already been used, the .addToUi() method will then replace that original menu with the new menu.

 

Let’s Make a Custom Menu

Creating custom menus is very easy because the code that creates reads exactly like the menu appears. Each chained method gets a new line to represent the menu feature that the method adds.

 

Create Custom Google Apps Script Menus

 

To create a menu that appears when the Google Spread or Google Docs application is opened, place the call to .createMenu() inside the .onOpen method.

 

The Ui Class and the Menu Class

Custom menus make use of two Google Apps Script classes. The Ui Class offers the ability to add to, and modify the user interface of the Google App that the script is bound to. This is everything from pop-up prompts and alerts, to sidebars, to of course, menus. The Ui class offers the only way to create a Menu object, with the .createMenu() method.

The Menu class is much smaller in scope. The Menu class only offers the ability to define the appearance and functionality of a menu, and that is all.

If you find yourself creating big menus with sub menus, you might want to define each menu individually and pass them to their parent menu, in the .addSubMenu() method. For illustration purposes:

 

Three tier menus are actually not a good idea. Here’s why:

 

Tips on User-Friendly Menus

At a minimum, menus should be easy to use and fast to load. For usability, Google’s Material UI Guidelines, recommends the following:

  • Menu names and menu item names should be short, descriptive, and accurate, with sentence casing.
  • Do not duplicate menu names or menu item names
  • Menus should be nested no more than one level deep. (The example above was for example purposes.)

 

Google Apps Script Menus Hello World

 

Get started! To see how these menus work. Copy and paste one of the scripts into the Google Apps Script editor and press play. I hope this helps keep the users of your custom Google App Script happy!

 

February 3, 2017

Posted In: User Interface

Tags: ,

One Comment