Effortless registration of Handlebars data, partials, helpers, and decorators.
$ npm install --save handlebars-wax
┣━ index.js
┣━ data/
┃ ┣━ site.js
┃ ┗━ locale.json
┣━ decorators/
┃ ┣━ currency.js
┃ ┗━ i18n.js
┣━ helpers/
┃ ┣━ link.js
┃ ┗━ list.js
┗━ partials/
┣━ footer.js
┗━ header.hbs
var handlebars = require('handlebars');
var handlebarsWax = require('handlebars-wax');
var wax = handlebarsWax(handlebars)
// Partials
.partials('./partials/**/*.{hbs,js}')
.partials({
boo: '{{#each boo}}{{greet}}{{/each}}',
far: '{{#each far}}{{length}}{{/each}}'
})
// Helpers
.helpers(require('handlebars-layouts'))
.helpers('./helpers/**/*.js')
.helpers({
foo: function () { ... },
bar: function () { ... }
})
// Decorators
.decorators('./decorators/**/*.js')
.decorators({
baz: function () { ... },
qux: function () { ... }
})
// Data
.data('./data/**/*.{js,json}')
.data({
lorem: 'dolor',
ipsum: 'sit amet'
});
console.log(handlebars.partials);
// { footer: fn(), header: fn(), boo: fn(), far: fn() }
console.log(handlebars.helpers);
// { link: fn(), list: fn(), foo: fn(), bar: fn(), extend: fn(), ... }
console.log(handlebars.decorators);
// { currency: fn(), i18n: fn(), baz: fn(), bat: fn() }
console.log(wax.context);
// { site: { ... }, locale: { ... }, lorem: 'dolor', ipsum: 'sit amet' }
var template = wax.compile('{{lorem}} {{ipsum}}');
console.log(template({ ipsum: 'consectetur' }));
// "dolor consectetur"
You may use handlebars-wax
to require and register any modules that export a register
factory, an object, or a function as partials, helpers, and decorators.
In cases where a direct reference to the instance of Handlebars in use is needed, modules may export a register
factory function. For example, the following module will define a new helper called foo-bar
:
module.exports.register = function (handlebars) {
handlebars.registerHelper('foo-bar', function (text, url) {
var result = '<a href="' + url + '">' + text + '</a>';
return new handlebars.SafeString(result);
});
};
If a module exports an object, that object is registered with Handlebars directly where the object keys are used as names. For example, the following module exports an object that will cause baz
and qux
to be registered:
module.exports = {
baz: function () {
// do something
},
qux: function () {
// do something
}
};
If a module exports a function, that function is registered based on the globbed portion of a path, ignoring extensions. Handlebars' require.extensions
hook may be used to load .handlebars
or .hbs
files.
module.exports = function () {
// do something
};
┣━ index.js
┗━ partials/
┣━ components
┃ ┣━ link.js
┃ ┗━ list.js
┗━ layouts
┣━ one-column.hbs
┗━ two-column.hbs
handlebarsWax(handlebars)
.partials('./partials/**/*.{hbs,js}');
// registers the partials:
// - `components/link`
// - `components/list`
// - `layouts/one-column`
// - `layouts/two-column`
handlebarsWax(handlebars)
.partials('./partials/components/*.js')
.partials('./partials/layouts/*.hbs');
// registers the partials:
// - `link`
// - `list`
// - `one-column`
// - `two-column`
handlebarsWax(handlebars)
.partials([
'./partials/**/*.{hbs,js}',
'!./partials/layouts/**'
])
.partials('./partials/layouts/*.hbs');
// registers the partials:
// - `components/link`
// - `components/list`
// - `one-column`
// - `two-column`
Helpers and decorators are handled similarly to partials, but path separators and non-word characters are replaced with hyphens to avoid having to use segment-literal notation inside templates.
┣━ index.js
┗━ helpers/
┣━ format
┃ ┣━ date.js
┃ ┗━ number.round.js
┗━ list
┣━ group-by.js
┗━ order-by.js
handlebarsWax(handlebars)
.helpers('./helpers/**/*.js');
// registers the helpers:
// - `format-date`
// - `format-number-round`
// - `list-group-by`
// - `list-order-by`
You may customize how names are generated by using the base
option, or by specifying a custom parsePartialName
, parseHelperName
, or parseDecoratorName
function.
handlebarsWax(handlebars)
.partials('./partials/components/*.js', {
base: __dirname
})
.partials('./partials/layouts/*.hbs', {
base: path.join(__dirname, 'partials/layouts')
});
// registers the partials:
// - `partials/components/link`
// - `partials/components/list`
// - `one-column`
// - `two-column`
handlebarsWax(handlebars)
.helpers('./helpers/**/*.{hbs,js}', {
// Expect these helpers to export their own name.
parseHelperName: function(options, file) {
// options.handlebars
// file.cwd
// file.base
// file.path
// file.exports
return file.exports.name;
}
});
// registers the helpers:
// - `date`
// - `round`
// - `groupBy`
// - `orderBy`
When data is registered, the resulting object structure is determined according to the default rules of require-glob
.
┣━ index.js
┗━ data/
┣━ foo/
┃ ┣━ hello.js
┃ ┗━ world.json
┗━ bar/
┣━ bye.js
┗━ moon.json
handlebarsWax(handlebars)
.data('./data/**/*.{js,json}');
// registers the data:
// {
// foo: {
// hello: require('./data/foo/hello.js'),
// world: require('./data/foo/world.json')
// },
// bar: {
// hello: require('./data/bar/bye.js'),
// world: require('./data/bar/moon.json')
// }
// }
You may customize how data is structured by using the base
option, or by specifying a custom parseDataName
.
handlebarsWax(handlebars)
.data('./data/**/*.{js,json}', {
base: __dirname,
parseDataName: function(options, file) {
// options.handlebars
// file.cwd
// file.base
// file.path
// file.exports
return file.path
.replace(file.base, '')
.split(/[\/\.]/)
.filter(Boolean)
.reverse()
.join('_')
.toUpperCase();
}
});
// registers the data:
// {
// JS_HELLO_FOO_DATA: require('./data/foo/hello.js'),
// JSON_WORLD_FOO_DATA: require('./data/foo/world.json'),
// JS_BYE_BAR_DATA: require('./data/bar/bye.js'),
// JSON_MOON_BAR_DATA: require('./data/bar/moon.json')
// }
Registered data is exposed to templates that are compiled by handlebars-wax
as the @root
context and as a parent frame of data passed to the template function. You may compile strings, or recompile template functions.
var compiledTemplate = handlebars.compile('{{foo}} {{bar}}');
var waxedTemplate = wax.compile(compiledTemplate);
// or: var waxedTemplate = wax.compile('{{foo}} {{bar}}');
wax.data({ foo: 'hello', bar: 'world' });
console.log(compiledTemplate());
// " "
console.log(waxedTemplate());
// "hello world"
console.log(waxedTemplate({ bar: 'moon' }));
// "hello moon"
var accessTemplate = wax.compile('{{bar}} {{_parent.bar}} {{@root.bar}} {{@root._parent.bar}}');
console.log(accessTemplate({ bar: 'moon' }, { data: { root: { bar: 'sun'} } }));
// "moon world sun world"
handlebars
{Handlebars}
An instance of Handlebars to wax.options
{Object}
(optional) Passed directly torequire-glob
so check there for more options.bustCache
{Boolean}
(default:true
) Force reload data, partials, helpers, and decorators.cwd
{String}
(default:process.cwd()
) Current working directory.compileOptions
{Object}
Default options to use when compiling templates.templateOptions
{Object}
Default options to use when rendering templates.parsePartialName
{Function(options, file): String}
See section on registering a function.parseHelperName
{Function(options, file): String}
See section on registering a function.parseDecoratorName
{Function(options, file): String}
See section on registering a function.parseDataName
{Function(options, file): String}
See section on registering data.
Provides a waxed API to augment an instance of Handlebars.
The instance of Handlebars in use.
An object containing all registered data.
pattern
{String|Array.<String>|Object|Function(handlebars)}
One or moreminimatch
glob patterns patterns, an object of partials, or a partial factory.options
{Object}
Passed directly torequire-glob
so check there for more options.parsePartialName
{Function(options, file): String}
See section on registering a function.
Requires and registers partials en-masse from the file-system or an object. May be called more than once. If names collide, newest wins.
pattern
{String|Array.<String>|Object|Function(handlebars)}
One or moreminimatch
glob patterns patterns, an object of helpers, or a helper factory.options
{Object}
Passed directly torequire-glob
so check there for more options.parseHelperName
{Function(options, file): String}
See section on registering a function.
Requires and registers helpers en-masse from the file-system or an object. May be called more than once. If names collide, newest wins.
pattern
{String|Array.<String>|Object|Function(handlebars)}
One or moreminimatch
glob patterns patterns, an object of decorators, or a decorator factory.options
{Object}
Passed directly torequire-glob
so check there for more options.parseDecoratorName
{Function(options, file): String}
See section on registering a function.
Requires and registers decorators en-masse from the file-system or an object. May be called more than once. If names collide, newest wins.
pattern
{String|Array.<String>|Object}
One or moreminimatch
glob patterns patterns, or a data object.options
{Object}
Passed directly torequire-glob
so check there for more options.parseDataName
{Function(options, file): String}
See section on registering data.
Requires and registers data en-masse from the file-system or an object into the current context. May be called more than once. Results are shallow-merged into a single object. If keys collide, newest wins. See Context and Rendering.
template
{String|Function(Object)}
options
{Object}
See theHandlebars.compile
documentation.
Compiles a template that can be executed immediately to produce a final result. Data provided to the template function will be a child frame of the current context. See Context and Rendering.
Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.
$ npm test
© Shannon Moeller [email protected] (shannonmoeller.com)
Licensed under MIT