One useful application of the Google Slides API is to merge information from one or more data sources into a templated slide deck.
This page outlines how you can take data from an external source and insert it into an existing template presentation. The concept is similar to that of a mail merge using a word processor and spreadsheet.
There are several reasons why this approach is useful:
It's easy for designers to fine-tune a presentation's design using the Google Slides editor. This is much easier than tuning parameters in your app to set the rendered slide design.
Separating content from presentation is a well-known design principle with many benefits.
A basic recipe
Here's an example of how you can use the Slides API to merge data into a presentation:
Create your presentation as you want it to appear using placeholder content to help you with the design.
For each content element you'll be inserting, replace the placeholder content with a tag. Tags are text boxes or shapes with a unique string. Be sure to use strings that are unlikely to occur normally. For example,
{{account-holder-name}}
might be a good tag.In your code, use the Google Drive API to make a copy of the presentation.
In your code, use the Slides API's
batchUpdate
method, with a set ofreplaceAllText
requests, to perform all the text substitutions throughout the presentation. UsereplaceAllShapesWithImage
requests to perform image substitutions throughout the presentation.
Once you've created a deck with tags in it, be sure to make a copy and use the Slides API to manipulate the copy. Don't use the Slides API to manipulate your primary "template" copy!
The following sections include code snippets that illustrate some of this process. You can also view the above video to see a complete example (Python) combining several of the concepts from the individual sections below.
Merge text
You can use a replaceAllText
request to replace all instances of a given text string in a
presentation with new text. For merges, this is simpler than
finding and replacing each instance of text individually. One reason this is the
most sophisticated approach is that page element IDs are difficult to predict,
especially as collaborators refine and maintain the template
presentation.
Example
This example uses the Drive API to copy a template presentation, making a new instance of the presentation. Then it uses the Google Sheets API to read data from a Sheets spreadsheet, and finally uses the Slides API to update the new presentation.
The example takes data from 3 cells in one row of a named range in the
spreadsheet. It then substitutes that data into the presentation wherever
the strings {{customer-name}}
,
{{case-description}}
, or
{{total-portfolio}}
occur.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Merge images
You can also merge images into your presentation using a
replaceAllShapesWithImage
request. This request replaces all instances of shapes containing the
provided text string with the provided image. The request automatically
positions and scales the image to fit within the tag shape's bounds while
preserving the image's aspect ratio.
Example
This example uses the Google Drive API to copy a template presentation, making
a new instance of the presentation. Then it uses the Slides API to find
any shape with the text {{company-logo}}
and replace it with a company logo image. The request also replaces any
shape with the text {{customer-graphic}}
with a different image.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Replace specific text box or image instances
The replaceAllText
and replaceAllShapesWithImage
requests are useful for replacing tags throughout a presentation, but
sometimes you only need to replace elements according to another criteria, such
as being located on a specific slide.
In these cases, you must retrieve the IDs of the tag shapes you want to replace. For text replacements, you delete the existing text in those shapes and then insert the new text (see the sample Edit text in a specified shape).
Image replacements are more complex. To merge in an image, you need to:
- Get the tag shape's ID.
- Copy the size and transform information from the tag.
- Add your image to the page, using the size and transform information.
- Delete the tag shape.
Preserving the image's aspect ratio while scaling it to the desired size might require some care, as described in the following section. Also see this sample: Replace a shape tag with an image.
Preserve aspect ratio
When you create images using the Slides API, aspect fits are based only on the
image size, not on the size and transform data. The size data you provide
in the createImage
request is considered to be the desired size of the image. The API fits the
image's aspect ratio to this desired size, then applies the provided transform.
When replacing a tag with an image, you preserve the image's aspect ratio by setting the image's size and scaling as follows:
- width: set to the product of the tag's
width
andscaleX
- height: set to the product of the tag's
height
andscaleY
- scale_x: set to
1
- scale_y: set to
1
This causes the Slides API to aspect fit the image according to the
tag's visual size, rather than its non-scaled size (see
Replace a shape tag with an image).
Setting the scaling parameters to 1
prevents the image from being scaled
twice.
This arrangement ensures the image's aspect ratio is preserved, and prevents the image from exceeding the size of the tag shape. The image has the same center point as the tag shape.
Manage templates
For template presentations the application defines and owns, create the template using a dedicated account representing the application. Service accounts are a good choice and avoid complications with Google Workspace policies that restrict sharing.
When you create instances of presentations from templates, always use end-user credentials. This gives users full control over the resulting presentation and prevents scaling issues related to per-user limits in Google Drive.
To create a template using a service account, perform the following steps with the application credentials:
- Create a presentation using presentations.create in the Slides API.
- Update the permissions to allow the presentation recipients to read it using permissions.create in the Drive API.
- Update the permissions to allow template authors to write to it using permissions.create in the Drive API.
- Edit the template as required.
To create an instance of the presentation, perform the following steps with the user credentials:
- Create a copy of the template using files.copy in the Drive API.
- Replace values using presentation.batchUpdate in the Slides API.