Fractal Handlebars Helpers

A collection of Handlebars helpers for Fractal projects.

You must be using the (default) Handlebars adapter for your components and/or pages to make use of these helpers.

Installation and Usage

Loading all helpers

If you wish to load all helpers into the template engine instance, you can auto-load them via the adapter:

// fractal.js
const fractal = require('@frctl/fractal');

fractal.engine('handlebars', '@frctl/handlebars-adapter', {
    loadHelpers: true
});

Loading individual helpers

If you want to load individual helpers, you will first need to install this library:

npm i @frctl/handlebars-helpers --save

You can then initialise the helpers and pick the the ones you want to use

// fractal.js
const fractal = require('@frctl/fractal');
const helpers = require('@frctl/handlebars-helpers'); // require the helpers

helpers.use(fractal); // initialise the helpers with the fractal instance

fractal.engine('handlebars', '@frctl/handlebars-adapter', {
    helpers: {
        'render': helpers.require('helpers/render') // use the 'render' helper
    }
});

Helpers

{{ render }}

The render helper renders a component (referenced by it's handle) using the context data provided to it. If no data is provided, it will use the context data defined within the component's configuration file, if it has one.

This can be very useful as an alternative to using the regular partial {{> @name }} helper to import sub-components. Partials do not pull in their own context so using the render helper instead can help prevent repetition of context data in the configuration files of components that include sub-components.

<!-- pass in data for rendering -->
{{render '@example' someData}}
{{render '@example--variant' otherData}}

<!-- use the config file data for rendering -->
{{render '@example'}}
{{render '@example--variant'}}

You can also pass in a partial data object (i.e. containing only some of the properties the component expects) and then set the merge property to true to populate the missing items from the default context data. This allows you to override only the items you need to for this instance of the rendered component.

{{render '@example' partialData merge=true}}

{{ context }}

Outputs the resolved context data for a component.

{{context '@example'}}

<!-- Outputs:
{
    "foo": "bar",
    "baz": "bar"
}
-->

{{ view }}

Outputs the raw view template contents for the specified component.

{{view '@example'}}

<!-- Outputs:
<p>{{ text }}</p>
-->