handlebars-registrar
Effortless wiring of Handlebars helpers and partials. Used internally by gulp-hb
and grunt-hb
.
Install
$ npm install --save-dev handlebars-registrar
Api
Helpers are registered by passing in your instance of Handlebars. This allows you to selectively register the helpers on various instances of Handlebars.
registrar(handlebars[, options])
handlebars
{Handlebars}
- An instance of Handlebars.options
{Object}
var handlebars = registrar = ; ; console;console;
Options
bustCache
{Boolean}
(default:false
)cwd
{String}
helpers
{String|Array.<String>|Object|Function}
parseHelperName
{Function(Object):String}
partials
{String|Array.<String>|Object|Function}
parsePartialName
{Function(Object):String}
bustCache
{Boolean}
(default: false
)
Whether to force a reload of helpers and partials by deleting them from the cache. Useful inside watch tasks.
cwd
{String}
Current working directory. Defaults to process.cwd()
.
helpers
{String|Array.<String>|Object|Function}
A glob string matching helper files, an array of glob strings, an object of helpers, or a function returning any of these. Globbed helper files are JavaScript files that define one or more helpers.
helpers: './src/assets/helpers/**/*.js'
helpers: './node_modules/handlebars-layouts/index.js' './src/assets/helpers/**/*.js'
helpers: { return Stringtext; } { return Stringtext; }
When including helpers using globs, modules may export a single helper function. These helpers will be named by calling parseHelperName
.
// lower.jsmodule { return Stringtext;};
Helpers may also export an object of named functions.
// helpers.jsmoduleexports = { return Stringtext; } { return Stringtext; };
If you need a reference to the handlebars instance inside of a helper, you may expose a factory register
method.
// helpers.jsmoduleexports { handlebars;};
parseHelperName
{Function(Object):String}
By default, standalone helpers will be named according to the shortest unique file path without the extension. So a helper with a path of string/upper.js
will be named string-upper
. Note that path separators are replaced with hyphens to avoid having to use square brackets. You may optionally provide your own name parser. This is helpful in cases where you may wish to exclude the directory names.
parseHelperName: = { // this.handlebars <- current handlebars instance // file.path <- full system path with extension // file.shortPath <- shortest unique path without extension // file.exports <- result of requiring the helper // Ignore directory names return path;};
partials
{String|Array.<String>|Object|Function}
A glob string matching partial files, an array of glob strings, an object of partials, or a function returning any of these. Globbed partial files are either standalone Handlebars files, or JavaScript files that define one or more helpers.
partials: './src/assets/partials/**/*.{hbs,js}'
partials: './src/assets/vendor/some-theme/partials/**/*.hbs' './src/assets/partials/**/*.hbs'
partials: link: '<a href="{{url}}">{{text}}</a>' people: '<ul>{{#people}}<li>{{> link}}</li>{{/people}}</ul>'
When including paritals using globs, partials may be standalone handlebars files. Each partial will be named by calling parsePartialName
.
{{!-- link.hbs --}}<a href="{{url}}">{{text}}</a>
Partials may also be modules that export an object of named partials.
// partials.jsmoduleexports = link: '<a href="{{url}}">{{text}}</a>' people: '<ul>{{#people}}<li>{{> link}}</li>{{/people}}</ul>';
If you need a reference to the handlebars instance when defining a partial, you may expose a factory register
method.
// partials.jsmoduleexports { handlebars;};
parsePartialName
{Function(Object):String}
By default, standalone partials will be named according to the shortest unique file path without the extension. So a partial with a path of component/link.hbs
will be named component/link
. You may optionally provide your own name parser. This is helpful in cases where you may wish to exclude the directory names.
parsePartialName: = { // this.handlebars <- current handlebars instance // file.path <- full system path with extension // file.shortPath <- shortest unique path without extension // file.exports <- result of requiring the partial // Ignore directory names return path;};
Contribute
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.
Test
$ npm test
© 2015 Shannon Moeller me@shannonmoeller.com
Licensed under MIT