Google Apps Script allows you to programmatically create and modify Google Docs, as well as customize the user interface with new menus, dialog boxes, and sidebars.
The basics
Apps Script can interact with Google Docs in two broad ways: any script can create or modify a document if the script's user has appropriate permissions for the document, and a script can also be bound to a document, which gives the script special abilities to alter the user interface or respond when the document is opened. To create a container-bound script from within Google Docs, click Extensions > Apps Script.
In either case, it's simple to interact with a Google Doc through Apps Script's Document Service, as the following example demonstrates.
function createDoc() {
var doc = DocumentApp.create('Sample Document');
var body = doc.getBody();
var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
body.insertParagraph(0, doc.getName())
.setHeading(DocumentApp.ParagraphHeading.HEADING1);
table = body.appendTable(rowsData);
table.getRow(0).editAsText().setBold(true);
}
The script above creates a new document in the user's Google Drive, then inserts
a paragraph that contains the same text as the document's name, styles that
paragraph as a heading, and appends a table based on the values in a
two-dimensional array. The script could just as easily make these changes to an
existing document by replacing the call to
DocumentApp.create()
with DocumentApp.openById()
or openByUrl().
For scripts created inside a document (container-bound), use
DocumentApp.getActiveDocument().
Structure of a document
From Apps Script's perspective, a Google Doc is structured much like an HTML
document—that is, a Google Doc is composed of elements (like a
Paragraph or
Table) that often contain other
elements. Most scripts that modify a Google Doc begin with a call to
getBody(), because the
Body is a master element that
contains all other elements except for the
HeaderSection,
FooterSection, and any
Footnotes.
However, there are rules about which types of elements can contain other types. Furthermore, the Document Service in Apps Script can only insert certain types of elements. The tree below shows which elements can be contained by a certain type of element.
Elements shown in bold can be inserted; non-bold elements can only be manipulated in place.
Replacing text
Apps Script is often used to replace text in Google Docs. Let's say you have a spreadsheet full of client information and you want to generate a personalized Google Doc for each client. (This type of operation is often called a mail merge.)
There are many ways to replace text, but the simplest is the
replaceText() method shown in the example below. replaceText supports most
of JavaScript's regular expression features. The first function below
adds several lines of placeholder text to a Google Doc; in the real world, you
would be more likely to type the placeholders into the document yourself. The
second function replaces the placeholders with properties defined in the
client object.
Note that both of these functions use the
getActiveDocument()
method, which only applies to scripts created inside a Google Doc; in a
stand-alone script, use
DocumentApp.create(),
openById(),
or openByUrl()
instead.
Add some placeholders
function createPlaceholders() {
var body = DocumentApp.getActiveDocument().getBody();
body.appendParagraph('{name}');
body.appendParagraph('{address}');
body.appendParagraph('{city} {state} {zip}');
}
Replace the placeholders
function searchAndReplace() {
var body = DocumentApp.getActiveDocument()
.getBody();
var client = {
name: 'Joe Script-Guru',
address: '100 Script Rd',
city: 'Scriptville',
state: 'GA',
zip: 94043
};
body.replaceText('{name}', client.name);
body.replaceText('{address}', client.address);
body.replaceText('{city}', client.city);
body.replaceText('{state}', client.state);
body.replaceText('{zip}', client.zip);
}
Custom menus and user interfaces
You can customize Google Docs by adding menus, dialog boxes, and sidebars. Keep in mind, however, that a script can only interact with the UI for the current instance of an open document, and only if the script is bound to the document.
See how to add custom menus and dialogs to your Google Docs. To learn more about creating custom interfaces for a dialog or sidebar, see the guide to HTML Service. If you're planning to publish your custom interface as part of an add-on, follow the style guide for consistency with the style and layout of the Google Docs editor.
Add-ons for Google Docs
Add-ons run inside Google Docs and can be installed from the Google Docs add-on store. If you've developed a script for Google Docs and want to share it with the world, Apps Script lets you publish your script as an add-on so other users can install it from the add-on store.
To see how you can create an add-on for Google Docs, see quickstart for building Docs add-ons.
Triggers
Scripts that are bound to a Google
Doc can use a simple trigger to respond
to the document's onOpen event, which
occurs whenever a user who has edit access to the document opens it in Google
Docs.
To set up the trigger, just write a function called onOpen(). For an example
of this trigger, see Custom menus in Google Workspace.
Although the simple trigger is useful for adding menus, it cannot use any Apps
Script services that require authorization.