Implementing custom helpers

You can register custom Handlebars by adding .js files to the helpers directory. These files must be valid JavaScript files and export two properties: name and fn. The former is the name for the helper, and the latter is the actual helper function.

Example

If the helpers directory contains a file named to-upper-case.js with following contents:

helpers/to-upper-case.js
module.exports = {
  name: "to-upper-case",
  fn: (str) => str.toUpperCase(),
}

Then, it could be used in a configuration file like so:

Resources:
  User:
    Type: AWS::IAM::User
    Properties:
      UserName: {{ to-upper-case 'Roger Moore' }}

And the final rendered template contents would look like this:

Resources:
  User:
    Type: AWS::IAM::User
    Properties:
      UserName: ROGER MOORE

Publishing helpers to NPM

You can share your custom Handlebars helper with others by publishing them to NPM. The published NPM package must export a helper object described above.

Example

Here's an example of how to publish a simple custom helper that calculates an MD5 checksum of the given value. The project file structure looks like this:

.
├─ index.js
└─ package.json

The index.js file contains the helper object:

index.js
const crypto = require('crypto')
module.exports = {
  name: "md5",
  fn: str => crypto.createHash('md5').update(str).digest("hex"),
}

The package.json file contains minimum configuration that is needed to publish the helper to NPM:

package.json
{
  "name": "takomo-md5-helper",
  "version": "0.0.1",
  "description": "My md5 helper",
  "files": [
    "index.js"
  ],
  "main": "index.js",
  "license": "MIT",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

Refer to official NPM documentation for more information about publishing NPM packages.

Using helpers from NPM

To use custom helpers published to NPM, you need to install the helper's NPM package to your project and then register the helper in your project's takomo.yml file.

Example

Let's see how we would include the md5 helper from the previous example to our own project.

First of all, we need to install and save the resolver package to our project's dependencies.:

npm install [email protected] --save-dev 

Then, we need to register the helper to our Takomo project by modifying the takomo.yml file. There are three ways to register a helper:

takomo.yml
# Add helpers section
helpers:
​
  # 1) Use just the package name
  - takomo-md5-helper
​
  # 2) Give the package name with 'package' property
  - package: takomo-md5-helper
​
  # 3) Give the package name with 'package' property and
  #    override the helper name with 'name' property.    
  - package: takomo-md5-helper
    name: my-md5

When registering the helper using option 1 or 2, Takomo registers the helper using the name exposed by the helper provider object - in this case that is md5.

It's possible that our project already has a helper registered with the same name. Takomo requires that all helper names are unique and will throw an error if more than one helper has the same name. To work around this problem, you can use the third way to register a helper, which let's you specify a new name for it. In our example, we have set the helper name to be my-md5.

Once the helper is registered, you can use it like any helper.