This package has been deprecated

Author message:

WARNING: This project has been renamed to 'handlebars-wax'. Install that instead.

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 = require('handlebars'),
    registrar = require('handlebars-registrar');
 
registrar(handlebars, {
    helpers: './helpers/**/*.js',
    partials: [
        './partials/**/*.{hbs,js}',
        './layouts/**/*.hbs'
    ]
});
 
console.log(handlbars.helpers);
console.log(handlbars.partials);

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: {
    lower: function (text) {
        return String(text).toLowerCase();
    },
 
    upper: function (text) {
        return String(text).toUpperCase();
    }
}

When including helpers using globs, modules may export a single helper function. These helpers will be named by calling parseHelperName.

// lower.js
module.exports = function (text) {
    return String(text).toLowerCase();
};

Helpers may also export an object of named functions.

// helpers.js
module.exports = {
    lower: function (text) {
        return String(text).toLowerCase();
    },
 
    upper: function (text) {
        return String(text).toUpperCase();
    }
};

If you need a reference to the handlebars instance inside of a helper, you may expose a factory register method.

// helpers.js
module.exports.register = function (handlebars) {
    handlebars.registerHelper('link', function(text, url) {
        text = handlebars.Utils.escapeExpression(text);
        url  = handlebars.Utils.escapeExpression(url);
 
        var result = '<a href="' + url + '">' + text + '</a>';
 
        return new handlebars.SafeString(result);
    });
};

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: = function (file) {
    // 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.basename(file.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.js
module.exports = {
    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.js
module.exports.register = function (handlebars) {
    handlebars.registerPartial({
        item: '<li>{{label}}</li>',
        link: '<a href="{{url}}">{{label}}</a>'
    });
};

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: = function (file) {
    // 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.basename(file.shortPath);
};

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 [e-mail]

Licensed under MIT