Handlebars Templates

Contents

• Handlebars Templates
• Handlebars Helpers
• Handlebars Partials

Handlebars Templates

Handlebars is a powerful template engine that was developed to support dynamic HTML generation in web applications.

A Handlebars template is driven by a data object (like your expanded config object) and can generate ANY kind of text... including Terraform code!

In a Metastructure project, Metastructure's job is to generate this expanded data object from your project config file and present it to your templates. YOUR job is to write DRY, compact Handlebars templates that consume this data object & generate the code you need!

Handlebars Helpers

Vanilla Handlebars expresses only a limited set of logical and data operations, FAR less capability than Metastructure requires!

Fortunately, Handlebars is easily extensible, so Metastructure includes an enhanced handlebars variant with a VERY powerful set of helper functions!

Note that Handlebars helpers are composable, so you can use them together to create complex logic in your templates.

Here are some examples:

• lodash exposes the entire Lodash library to your templates.

• params converts a set of Handlebars parameters into an array that can be consumed by a lodash helper.

• logic provides the boolean logic functions that are missing from vanilla Handlebars and can easily be combined with lodash comparison function like eq and isEqual.

• ifelse provides a ternary operator.

• json2tf converts a JSON object into a Terraform literal. The Metastructure Template Repo's global module outputs template uses this function to expose your entire project config directly to your Terraform code!

• namify transforms a string to force it into compatibility with a given naming convention (e.g. an S3 bucket name).

• throwif will throw an exception if its condition is met, halting template generation & presenting an error message in your console.

Handlebars Partials

A Partial is a Handlebars template that you can include in other templates. This is a powerful feature that allows you to create reusable components in your templates.

Partials take arguments as key-value pairs.

You can declare partials at two levels in your Metastructure config:

• The partials key at your configuration root defines global partial you can use anywhere in your project.

• The workspaces.<workspace>.partials key defines partials that are specific to a single workspace. A partial defined at this level will override a global partial of the same name.

Either way, a key in the partials object is the name with which you will reference the partial in your templates, and the corresponding value is the path to the partial file relative to the project root.

For example, the Metastructure Template Repo defines a global partial that renders a Terraform provider block. The definition looks like this:

partials:
  provider: src/partials/provider.hbs

This partial is invoked several times within the global providers template. Here's one of the invocations:

{{> provider accountKey=this config=../../.}}

The following global partials are currently defined in the Metastructure Template Repo:

• header_generated - Renders a comment block warning developers not to edit a generated file.

• provider - Renders a Terraform provider block.