search

Errorname / google-docs-mustaches

📝Interpolate Google Docs files using mustaches and formatters
MIT License
28 stars 15 forks source link
google-docs interpolation javascript mustaches pdf template typescript

readme

logo

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

new Mustaches(options: ConstructorOptions)

type AccessToken = string

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

AccessToken must have the following scopes:

See also: How to retrieve the Google token?

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

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
}

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'
}

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:

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:

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:

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.