google-docs-mustaches

📝Interpolate Google Docs files using mustaches and formatters

How does this work?

google-docs-mustaches will execute requests to the Google Drive and Google Docs APIs to copy the file and interpolate its placeholders using the given data.

Installation

npm install google-docs-mustaches

Basic usage

Create a new Google Doc file and write the following text:

Hello {{ firstname }} {{ lastname | uppercase }}!

You have {{ accounts[0].money }}€ in you account...

Then execute the following code

import Mustaches from 'google-docs-mustaches'

const mustaches = new Mustaches({
  token: () => gapi.auth.getToken().access_token
})

// ID of the template
const source = '11rGORd6FRxOGERe7fh6LNQfyB48ZvOgQNH6GScK_FfA'

// ID of the destination folder
const destination = '18mcqwbaXS8NOqZjztB3OUQAc5_P8M6-l'

mustaches.interpolate({
  source,
  destination,
  data: {
    firstname: 'Thibaud',
    lastname: 'Courtoison',
    accounts: [{ money: 1500 }]
  }
})

Documentation

Constructor
Interpolate the file
Discovery of the placeholders
Export of the file
Read Doc

`new Mustaches(options: ConstructorOptions)`

type AccessToken = string

interface ConstructorOptions {
  token: () => Promise<AccessToken> | AccessToken
}

token will be called at every request to the Google apis.

AccessToken must have the following scopes:

https://www.googleapis.com/auth/drive

https://www.googleapis.com/auth/documents

`mustaches.interpolate(options: InterpolationOptions): ID`

This method will interpolate from the source file and put the generated file into the destination folder.

type ID = string

interface InterpolationOptions {
  source: ID
  destination?: ID
  name?: string
  data: Object
  formatters?: Formatters
  strict?: boolean
}

interface Formatters {
  [name: string]: Formatter
}

type Formatter = (value: any, ...params: any[]) => string

source is the ID of the file which will be interpolated.
destination is the ID of the destination folder where the new file will be put. If no destination is given, the new file will be put next to the source file.
name is the name of the newly created and interpolated google doc file.
data is the data given for the interpolation
formatters will be used for interpolation
strict indicates whether to use strict mode or not.

`mustaches.discovery(options: DiscoveryOptions): Placeholder[]`

This methods returns all the placeholders found in the source file. The placeholders will be interpolated to see what would have been the results if interpolate was called. This method will not mutate your source file, nor create a new one.

interface DiscoveryOptions {
  source: ID
  data?: Object
  formatters?: Formatters
  strict?: boolean
}

source is the ID of the file which will be interpolated.
data is the data given for the interpolation
formatters will be used for interpolation
strict indicates whether to use strict mode or not.

`mustaches.export(options: ExportOptions): ID`

This methods will copy a file into the mimeType given in argument. The method will return the id of the newly created file.

interface ExportOptions {
  file: ID
  mimeType: MimeType
  name?: string
  destination?: ID
}

enum MimeType {
  pdf = 'application/pdf',
  text = 'plain/text'
}

file is the ID of the file which will be exported.
mimeType is the type to export the file to.
name is the name of the newly exported file.
destination is the ID of the destination folder where the new file will be put. If no destination is given, the new file will be put next to the file to given in argument.

`mustaches.readDoc(file: ID): Promise<GDoc>`

This method will return the full content of the file.

This is simply a wrapper of the GDoc API to read the content of the document.

Interpolation

Mustaches

The double brackets notation (also known as mustaches) is used to define placeholders:

My name is {{ firstname }}. Nice to meet you!

During the interpolation, the placeholder will be replaced with the content of the options.data object.

{
  firstname: 'Thibaud'
}

My name is Thibaud. Nice to meet you!

Path notation

You can use nested objects and arrays for the interpolation:

{{ pokemons[1].name }}, I choose you!

With the following options.data

{
  pokemons: [
    {
      name: 'Eevee',
      level: 12
    },
    {
      name: 'Pikachu',
      level: 25
    }
  ]
}

Will become:

Pikachu, I choose you!

Warning: If you use an undefined variable as input, it will be resolved as an empty string. See Strict mode

Formatters

You can use formatters to print your data and more complex objects any way you want. In addition of the input variable, they can accept parameters which can be of the following primitive types: Number, Boolean, String or can be a variable which will be evaluated from options.data.

There is a number of available formatters, but you can also write your owns in options.formatters.

Hi {{ name | uppercase }}. Today is {{ today | printDay('en-US') }}, tomorrow is {{ tomorrow | printDay('en-US') }}.

With the following options:

{
  data: {
    name: "Courtoison",
    today: new Date(),
    tomorrow: new Date(new Date().setDate(new Date().getDate()+1))
  },
  formatters: {
    printDay: (date, locale) => date.toLocaleDateString(locale,{weekday: 'long'})
  }
}

Will become:

Hi COURTOISON. Today is Tuesday, tomorrow is Wednesday.

Available formatters:

lowercase: HeLLo => hello
uppercase: wOrLd => WORLD
capitalize: heLLO wOrlD => Hello World
money(locale, currencyISO, fractionDigits = 0): 1500 | money("us", "USD", 2) => $1500.00. (Currency ISO Codes)[https://en.wikipedia.org/wiki/ISO_4217#Active_codes]
image(width, height): Transform an url string to an image
More to come...

Warning: If you use an undefined formatter it will be simply ignored, which could lead to unexpected results if you're chaining them. See Strict mode

Strict mode

By default, google-docs-mustaches is failing safely, which means that you don't have to worry about using an undefined variable or an unknown formatter, the generated errors will be catched and treated by the program itself. However, you might face unexpected behaviour if for example, you chain several formatters and one of them is misspelled, it would be ignored and the output of your formatters pipeline won't match your expectations.

To avoid this, we provide a strict mode for .interpolate and .discovery. Instead of using an empty string or your fallback when encountering an undefined variable, it will throw an exception, aborting immediately the interpolation of your document.

How to retrieve the Google token?

If you are using google-docs-mustaches from inside a browser, you can follow this tutorial.

If you are using google-docs-mustaches in Node.js, you can follow this one.

Note: Your AccessToken must have the following scopes:

https://www.googleapis.com/auth/drive

https://www.googleapis.com/auth/documents

Limitations

google-docs-mustaches uses Google Drive and Google Docs apis. This means any limitation and changes to those APIs may affect this library.

Below is a list of the current known limitations:

There is a 10Mo limit to the export method of the Google Drive API. Trying to export a bigger file will result in an HTTP Error. Source

Want to help?

Great! If you want to contribute to google-docs-mustaches, go check out the Contributor documentation to get started!

Supported environments

We use cross-fetch for compatibility with most environment.

jk2K/google-docs-mustaches