@frctl/consolidate

Consolidate Adapter

Generic template engine adapter for Fractal, powered by consolidate.js.

If a specific Fractal template engine adapter for your desired language is available then it is recommended to use that instead as it will likely be easier to use and configure than this generic handler.

Currently specific template engine adapters have been implemented for:

• Handlebars
• Nunjucks
• Mustache

Note: Due to the way that Consolidate handles loading of templates, this engine cannot be used for rendering pages, only components.

Usage

1. Install the consolidate engine adapter

npm i @frctl/consolidate --save

2. Install the template language parser

As an example, to use Swig templates, first you need to install Swig:

npm i swig --save

2. Add configuration details

You then need to configure Fractal to use Swig via the Consolidate adapter:

const consolidate = require('@frctl/consolidate');
const swigAdapter = consolidate('swig');

fractal.engine(swigAdapter);  // use the consolidate/swig adapter

fractal.components.set('ext', '.swig'); // look for files with a .swig file extension

You can see a full list of supported template languages on the Consolidate documentation.

Template Engine Instances

You can customise the template engine instance once it has been if you want to add filters, globals, mixins etc.

For example, to extend the above example to use a customised instance of Swig you could do the following:

const swig        = require('swig');
const consolidate = require('@frctl/consolidate');

// Add a custom Swig filter
swig.setFilter('join', function (input, char) {
    return input.join(char);
});

const swigAdapter = consolidate('swig', swig); // pass in the customised swig instance to use instead of the default one

fractal.components.engine(swigAdapter); // set it to use as the template engine for components

fractal.components.set('ext', '.swig');

Special variables

The Consolidate adapter also makes a few special variables available to your templates. They all have names prefixed with an underscore to help prevent clashes with any context data variables that are set by the user.

Note that using these may tie your templates a little more tightly into Fractal so you may choose not to use them for that reason.

The actual syntax for accessing these variables will depend on the template engine that you use - Handlebars style variables are shown in the examples below.

_config

Contains the full Fractal configuration object. Useful for when you want to refer to a configuration item in your documentation (or components).

{{ _config.project.title }} <!-- outputs the project title -->
{{ _config.components.ext }} <!-- outputs the extension used for components -->

_self

Contains a simple data object representation of the top-level item (i.e. component or page) being rendered.

{{ _self.title }} <!-- outputs 'Button' -->

_target

This variable is only set in component preview layouts, and contains a simple data object representation of the item (i.e. component or page) being rendered within the preview layout.

{{ _target.title }} <!-- outputs 'Button' -->