Introducing Versions and Libraries in Apps Script

Tuesday, May 22, 2012 | 6:48 AM

Labels:

Have you ever written a particular piece of code over and over again?  Or used scripts to do something that you thought others might want to do as well?  Starting today, you’ll be able to share and reuse those scripts as libraries, right from inside Google Apps Script.

Why use a Script Library

I often write scripts which check the National Weather Service for relevant weather-related information.  This allows me to send myself an email if it’s going to rain, reminding me to bring an umbrella to work, or to annotate my spreadsheet of running workouts with the temperature of the day.

Remembering how to query the National Weather Service every time I write a script is a daunting task, however.  They have a complicated XML format that  is tricky to parse.  As a result, I end up just copying and pasting code each time.  This is not only error-prone, but also has the big disadvantage that I have to fix all of my scripts one by one whenever the Weather Service’s XML format changes.

The code I use to query the National Weather Service is a perfect use case for a library.  By using a library, I no longer have to copy and paste code in my script project.  Since logic is centralized, updates need to be applied just once.  And now I am able to share my library with other developers who can benefit from the work I’ve already done.

Writing a Library

Libraries are written just like any other Apps Script project.  A good library has a clean API which is also well documented.  Here’s a code snippet from my WeatherService library:


/**
 * Queries the National Weather Service for the weather
 * forecast of the given address. Example:
 * 
 * <pre>
 * var chances = WeatherService
 *                 .getPrecipitation("New York, NY");
 * var fridayChance = chances[“Friday”];
 * Logger.log(fridayChance + “% chance of rain on Friday!”);
 * </pre>
 * 
 * @param {String} address The address to query the
 *          temperature for, in any format accepted by
 *          Google Maps (can be a street address, zip
 *          code, city and state, etc)
 *          
 * @returns {JsonObject} The precipitation forecast, as
 *          map of period to percentage chance of
 *          precipitation. Example:
 * 
 * <pre>
 * { Tonight: 50, Friday: 30, Friday Night: 40, ... }
 * </pre>
 */
function getPrecipitation(address) {
  // Code for querying weather goes
  // here...
}

Notice how detailed the documentation is. We know that good documentation makes for a great library. So, for every library Apps Script will also auto-generate a documentation page based on the code comments using the JSDoc format.  If you want a method in your code to not be exposed to users, simply end its name with an underscore.

Saving Versions

Before code can be used as a library, a version of it needs to be saved.  Versions are a new concept in Apps Script, and they represent a snapshot of your project which won’t change even as changes are made to the script code. Versions are useful because they allow you to change your library code without breaking existing users.  Once you’re happy with the changes you’ve made, you can then save a new version. Please see the user guide for saving a version and sharing your code as a library is easy.

Using Libraries

Using a library only takes a few steps. To be able to use a library, the owner of the library must share the library and its project key with you. You can follow these instructions to then use a library. To use this National Weather Service library, please visit this page for project key.

Useful Features of Libraries

Script Libraries come with three interesting features.

  1. Documentation - In the Script Libraries dialog, you can click on the title link to navigate to documentation page for the library. See example of a generated documentation.
  2. Development Mode can be used to test changes to a library without saving a new version. See our User Guide for more details
  3. Autocomplete in Script Editor - Typing in the editor will auto-complete your library function names.

Interesting Libraries You Can Use

To get started on using Script Libraries, you can find a list of useful libraries contributed by two of our top contributors - James Ferreira and Romain Vialard. You can also find a detailed user guide on managing versions and libraries. We hope you enjoy using libraries.



Gustavo Moura

Gustavo has been a Software Engineer at Google since 2007. He has been part of the Google Docs team since 2009. Prior to that, he worked on AdWords. In his free time he plays soccer.

8 comments:

astilly said...

This looks like it could open powerful possibilities. What happen to a script that is published with dependencies on libraries. Do the libraries come with it when it is installed?

James Ferreira said...

Thank you Google Apps Script team for making this possible! Our collection of libraries can be found at GoogleScriptExamples.com
James Ferreira

gmoura said...

@astilly, yes. The libraries do come with the script when it is installed.

The one thing to keep in mind is that, for things to work properly, the library needs to be visible to the person installing the script, so for a published script it's probably a good idea to only depend on public libraries.

Anton S said...

Thank you Apps Script team! I've been for this feature for so long! ;)
You are the best.

Benjamin Talic said...

This is great :) Definitely what Apps Script needed :)

Eduardo Cereto Carvalho said...

Thanks this is good stuff,

I created a library to query Google APIs. I use the DiscoveryAPI to build an API client. So it should work fine for any library that is documented through the Discovery API. So far I tested it with Google Analytics and works fairly well. I also tested with some simple Google+ calls.

http://goo.gl/VDRl1

This will come very handy to me. Thanks.

Chitchats Manifests said...

Gustavo,
I just want to update a function in my library and then have the change affecting all spreadsheets using the library.

Is there a way I can do that without having to increment the version and go into every single spreadsheet script to include the recent version?

Timothy Mwirabua said...

Hey there thanks for the info. I am new to GAS, how do I view the code for the published version of my standalone app https://script.google.com/macros/s/AKfycbwvCnn7WfTWsU2sz-8ONeM_gLM_y5pZd31s6lb68bjyx1bETOyy/exec
Because i just edited numerously for days and I just wanna compare with my current code before saving a new version.
current code>>
https://script.google.com/d/1H6DLb8L6Qd3g55Dzn_A7ed61QvM_OcrLINDfya1i1h7JAyV_jLH7nmcq/edit