Google Apps Script

Libraries

A library is a project that can be included by you or other developers to gain access to its functions. To learn how to properly write, include and use a library, see the sections below.

  1. Managing libraries
    1. Gaining access to a library and including it in your project
    2. Using a library
    3. Deleting a library
  2. Creating a library
    1. Sharing a library
    2. Best practices to writing a library
    3. Resource scoping
    4. Testing and debugging

Managing libraries

Gaining access to a library and including it in your project

  1. To include a library in your project you must have at least a read-level access to it. If you are not the author of the library that you want to include, you need to contact the author and request them to grant you access.
  2. You also need the project key of the library you are including. If you have access to the library, you can find the project key under File > Project Properties... Otherwise, you need to ask the author of the library to give you the project key.
  3. Select Resources > Manage Libraries...

  4. Paste in the project key of the library that you want to use into the Find a Library text box.
  5. Click Select.
  6. The library is added to the list of the libraries you have included in your project.
  7. Click on the Versions dropdown and select a version of this library that you want to use.

  8. Check to see if the default Identifier name is the one that you would like to use with this library. This is the name that shows up in autocomplete. For example, if you set it to Test then you could call a method of that library as follows: Test.libraryMethod().
  9. Enable Development Mode if you want to override the selected version. For more information, see Testing and debugging a library.
  10. Click Save to save the libraries you have added and close the dialog box.

Using a library

You can use your included library just as you would use a default service. For instance, if you have chosen Test as an identifier for your library, just type Test immediately followed by a period to see autocomplete information listing the methods of the library.

The reference documentation for an included library can be opened by following these steps:

  1. Select Resources > Manage Libraries...
  2. The name of the library that you have included is a link that opens a new browser tab which contains the reference documentation for this library.

Removing a library

  1. Select Resources > Manage Libraries...
  2. Click on the 'x' button to the right of the library to delete it.
  3. Click Save for the changes to take effect.

Creating a library

Sharing a library

There are three things that you need to do to share your library with others. First, you must grant at least a read-level access to your project for all potential users. Then, you must provide them the project key of your library which can found under File > Project Properties... Finally, you must have at least one saved version of your script. For more information, see Creating a version.

Best practices to writing a library

Here are some guidelines to follow when writing a library:

  1. You should choose a meaningful name for your project since it is used as the default identifier when your library is included by others.
  2. If you want one or more methods of your script to not be visible (nor usable) to your library users, you can end the name of the method with an underscore. For example, myPrivateMethod_().
  3. If you want your library users to make use of Script Editor autocomplete and the automatically generated documentation, you must have JSDoc style documentation for all your functions. Here's an example:
    /**
    * Raises a number to the given power, and returns the result.
    *
    * @param {number} base the number we're raising to a power
    * @param {number} exp the exponent we're raising the base to
    * @return {number} the result of the exponential calculation
    */
    function power(base, exp) { ... }

Resource scoping

There are two types of resources when you are working with libraries: shared and not-shared.
A shared resource means that both the library and the including script have a built-in access to the same instance of the resource. The following diagram illustrates a shared resource using the example of User Properties:

Shared Resource

A not-shared resource means that both library and the including script have built-in access only to their instance of the resource. However, a library can provide access to its not-shared resources by having explicit functions that operate on them. Here is an example of a function that you would include in your library to expose its Script Properties:

function getLibraryProperty(key) {
  return ScriptProperties.getProperty(key);
}
The following diagram illustrates a not-shared resource using the example of Script Properties:

Not-Shared Resource

This table lists the shared and not-shared resources for your reference:

ResourceShared*Not-Shared**Notes
LockThe same instance is visible to all including scripts when created in the library.
Script PropertiesThe same instance is visible to all including scripts when created in the library.
CacheThe same instance is visible to all including scripts when created in the library.
TriggersSimple triggers created in library are not triggered by the including script.
ScriptApp
UiApp
User Properties
Logger and execution transcript
Sites, Spreadsheets and other containersA call to getActive() returns the container of the including script.
MailApp and GmailApp
* This means that the library does not have its own instance of the feature/resource and instead is using the one created by the script that invoked it.
** This means that library has its own instance of the resource/feature and that all scripts that use the library share and have access to that same instance.

Testing and debugging your library

When you are using a debugger within a project that has a library included you are able to step into a function of the included library. The code shows up in the debugger in the read-only mode and at the right version.

When you are writing a library and doing a lot of testing, you should use Development Mode. Once the development mode is on, the following becomes true:

  1. Anyone who has editor-level access to the script has the latest changes made to the files in the library project even if it was not saved as a version.
  2. The autocomplete is still generated based on the selected version.
  3. Anyone with only the read-level access to the script still uses the selected version regardless of whether the development mode is on or off.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.