Started originally as a side project by Mike Harm, a developer of Google Sheets, Google’s Apps Script is a scripting language and platform which is compatible with any application within Google Suite. Today, more than 10 years after its release, Apps Script has become one of Google’s most popular developer projects, which allows the public to create and share add-ons, web apps, and more within any of the Google Suite applications used by millions of people every day [3]. Now more than ever, the transition for the typical Javascript user to Apps Script creator is simple, as long as the user gains a full understanding of the comprehensive Apps Script documentation. In this blog post, we will go over the basics of Apps Script and how to find your way through its extensive guide so you can create the G Suite project you need.
What is Apps Script?
Scripting platforms like Apps Script dynamically process web sites and applications on the server side, allowing its users to view their projects from the client side in real time as they build and test their programs. Mike Harm’s focus when he joined Google as a programmer in 2007 was to make the application programming interface, or API, of Google Sheets more user-friendly. However, with his prior graduate school experience teaching an introductory computer science course to students outside the computer science department at Northeastern University, Harm began his side project of a JavaScript-based scripting language for spreadsheets as a way to allow more non-traditional programmers to create projects due to Javascript’s accessibility and popularity [3]. Since then, the idea took off and grew, making Apps Script the platform that allows the layman to develop their own functionalities for applications such as Google Drive, Docs, Sheets, Slides, and much more.
Where do I begin?
Even for the programmer that is familiar with Javascript, Apps Script’s breadth can seem daunting, but Google’s Apps Script Fundamentals page assures users that users only need prior experience with Google Sheets API, before jumping into tutorials for add-ons for Google Sheets, Forms, and Chat [5]. To a programmer with no prior experience scripting languages, however, it is easy to get lost in the documentation, making it difficult to know what to do when you first get to the Apps Script platform. A good place to start is by learning about Apps Script manifest file in the Reference Overview page, which explains the purpose and use of a manifest file, a special JSON file (JavaScript Object Notation file) with a certain configuration and data structure needed to specify the program’s file contents and the JSON fields it could contain to properly run your script [11]. For simple projects, creating a custom manifest file may not be necessary, but Google Workspace add-ons for example, require their own manifest file guides, and there are a separate set of dependencies in order to use certain libraries and advanced services. It is important to make sure that the manifest file is tailored to your project because many problems can come from incorrectly running your project script.
Within the Apps Script environment, there are the options to open files, libraries, and services. If it is necessary for your project, the manifest file will have to be a .json file. For example, for a Google Workspace add-on, the documentation gives an example manifest file that could be needed [1, Fig. 1] and a key to the different fields used [1, Fig. 2].
!["Common: The manifest configuration for parameters that are common for every host application. Some values defined here are used as a default when specific values for a particular host are omitted."
The JSON representation features the homepageTrigger, LayoutProperties, and UniversalAction objects, logoUrl, name, and openLinkUrlPrefixes[] strings, and useLocaleFromApp boolean.](https://mochiresearch.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-02-at-4.43.24-PM-1024x663.png)
Source: Adapted from [1]
![The key to the fields includes:
“homepageTrigger: object (HomepageTrigger), The default trigger function specification for creating the add-on homepage. This specification is used if a host-specific homepage trigger is not defined. If this is omitted as well, a generic homepage card is constructed and used when needed.
layoutProperties: object (LayoutProperties), A configuration for the colors used in the add-on toolbar and buttons.
logoUrl: string, Required. The URL of the image shown in the toolbar.
Name: string, Required. The name of the add-on shown in the toolbar.
openLinkUrlPrefixes[]: string, Required if the add-on displays any outbound links, whether within widgets using an OpenLink or text widget using HTML anchor tags. A list of HTTPS URL prefixes. To protect user data, any link rendered by the add-on must match one of the prefixes in this list. See Whitelisting URLs for more details.
universalActions[]: object (UniversalAction), List of universal actions that are always available in the add-on UI.
useLocaleFromApp: boolean, If true, add-on event objects passed to action callback functions or trigger functions include the locale and timezone information of the user. Defaults to false. See Accessing user locale and timezones for more details.](https://mochiresearch.com/wp-content/uploads/2021/08/Screen-Shot-2021-08-02-at-4.44.05-PM-1024x811.png)
Source: Adapted from [1]
You will also need at least an .html file to create the user interface of your program. In your files, you will also have all the Apps Scripts .gs files, which are scripts created by Google Apps Script, as needed to build your project. Following the Google Workspace add-on example, a Google Docs Translation Add-on Tutorial serves as an example of how to use .html and .gs files together in their sample code [10, Fig. 3], which is also available to view on GitHub.
Source: Adapted from [10]
When adding libraries or services to your project, you will need the script ID of the library or you can choose between different Advanced Google Services to connect to the public Google API in your program.
Syntax and Custom Functions
As the name suggests, JavaScript is at the heart of Apps Script because the platform and language is meant to build off of an existing, widely used programming language. In terms of syntax for Apps Script, you can assume that the syntax is the same as standard JavaScript, which has thousands of guides and resources to it online and in text due to its large user base. Aside from refreshing your JavaScript skills, the only syntax you would have to learn to use are the custom functions when making add-ons or web apps that work with Google Workspace applications. The Apps Script documentation has a lengthy “Google Workspace services” section that provides insight to the different functions and variables of each application in Google Suite, such as Google Drive, Google Docs, Calendar, Gmail, and more. Each application has various pages listing the classes specific to the app, the various methods, interfaces, and even enums, to use the G Suite application’s user data in your project. Some examples include the Google Doc’s getEditors() function, which returns an array of User classes for each person with edit access in the Document, of which you can call the getEmail() method to get the email of the user. Google allows you to work with virtually as much information as they get from users of their G Suite applications themselves, giving Apps Script users free reign to create whatever add-on or compatible web app they can dream of.
Libraries, Blobs, and Script Services
The key to making the most of Apps Script functionalities is understanding how to find your way through the guides and documentation that apply to your project. One way to make the most of the open source nature of Apps Script, especially when it comes to creating add-ons for popular G Suite apps, is by using libraries available for public use. Apps Script documentation describes libraries as other script projects whose functions can be repurposed for other projects [8]. Because you need a library’s script ID and at least viewing permissions to it, looking for open source Apps Script libraries is a good way to save time and speed up your project building process.
The Apps Script documentation also provides some insight on Script Services, which are advanced information to make a more complex and robust project, including Cache Service, Optimization Service, JDBC Service, and XML Service. What is most commonly needed for a basic project, however, is the Base Service, where you can further access information from your project’s users, as well as managing script logs and dialog boxes [2]. This is done with introducing yet another list of classes, interfaces, and enums specific to Apps Script. Some examples of classes are the Blob, what they describe as “a data interchange object for Apps Script services”, and the more straightforward Console and RgbColor, among many others [4]. Script Services may not be necessary for your first project on Apps Script, but when you do move onto greater programs, Google offers various ways to enhance your projects.
Apps Script Community
Just like any other online community of programmers, there is a surprising amount of programs, support, and guides available for public use. A great place to start is the open source Apps Script community’s Apps Script masterlist on GitHub, where you can find lists of even more helpful resources, starter kits, library databases, samples, and cheat sheets [6]. Also available are open source apps and add-ons for Google Suite applications on GitHub, each with varying crediting necessary, however, so it is important to check the author’s use permissions. Overall, they serve as useful add-ons and as a working example of sample code to help guide your project, or to just be a good place to find an add-on that can even help you finally unsubscribe from all your bulk online shopping emails. For a more active community of apps script users that may be willing to collaborate, a good place to start could be r/GoogleAppsScript on Reddit. Just like any other Reddit community, it is an open space to find answers to common Apps Script questions that others may have had. The subreddit features a live chat room to ask and answer questions, as well as guides to programming in App Script and ongoing updates about changes related to the platform. Making the most of online communities, whether it is related to Apps Script programming or any type of programming skill or platform, is key to making the most of your time and energy. Apps Script’s nature as a platform is to be open source and collaborative, so there are many more places online where you can find people willing to help each other realize their projects in Apps Script as long as you seek them out!
Launching Your Apps Script Project
With the coding portion of your program completed, it is now time to launch your Apps Script project and continue testing your user interface! In the Apps Script environment, the first step is to create a new deployment, one of the options the platform gives you when clicking “Deploy.” Every Apps Script project uses the Google Cloud Platform, or GCP, to manage the authorizations needed for G Suite add-ons and web apps as well as any Advanced Google Services you have used. Options for Script projects are either a default GCP project, which is created by Apps Script and is good for small programs and testing, or a standard GCP project, which should be created for any project that you would want to publish for public use [7]. Creating a standard GCP project allows you to manage who can test your project, change security settings, and much more. Google does a good job of not overwhelming users at once when creating a project for App Script with simpler settings. In order to finally deploy your Apps Script project, all you need is your GCP project number to deploy for the first time to be able to test run your project by choosing your add-on in the G Suite app your project uses. Apps Script allows you to manage different deployments during testing stages, and if you choose to, you can publish your app publicly or within your organization in Google Workspace Marketplace [9].
Enjoy creating your App Script projects!
Sources
[1] “AddOns manifest resource | Apps Script,” Google Developers. https://developers.google.com/apps-script/manifest/addons (accessed Aug. 02, 2021).
[2] “Base Service | Apps Script,” Google Developers. https://developers.google.com/apps-script/reference/base (accessed Jul. 29, 2021).
[3] “Celebrating 10 years of Apps Script: looking back on how it started,” Google Cloud Blog. https://cloud.google.com/blog/products/g-suite/celebrating-10-years-of-apps-script-looking-back-on-how-it-started/ (accessed Jul. 24, 2021).
[4] “Class Blob | Apps Script,” Google Developers. https://developers.google.com/apps-script/reference/base/blob (accessed Jul. 29, 2021).
[5] “Codelabs: Apps Script Fundamentals,” Google Developers. https://developers.google.com/apps-script/quickstart/fundamentals-codelabs (accessed Jul. 29, 2021).
[6] “GitHub – contributorpw/google-apps-script-awesome-list: The usual list of links to interesting resources for Google Apps Script,” GitHub. https://github.com/contributorpw/google-apps-script-awesome-list (accessed Aug. 01, 2021).
[7] “Google Cloud Platform Projects | Apps Script,” Google Developers. https://developers.google.com/apps-script/guides/cloud-platform-projects (accessed Jul. 28, 2021).
[8] “Libraries | Apps Script,” Google Developers. https://developers.google.com/apps-script/guides/libraries (accessed Aug. 01, 2021).
[9] “Overview: Publish an app | Google Workspace Marketplace,” Google Developers. https://developers.google.com/workspace/marketplace/how-to-publish (accessed Jul. 27, 2021).
[10] “Quickstart: Add-on for Google Docs | Google Workspace Add-ons,” Google Developers. https://developers.google.com/workspace/add-ons/editors/docs/quickstart/translate (accessed Aug. 02, 2021).
[11] “Reference overview | Apps Script,” Google Developers. https://developers.google.com/apps-script/reference (accessed Jul. 28, 2021).
