handlebars-layouts
Handlebars helpers which implement layout blocks similar to Jade, Jinja, Nunjucks, Swig, and Twig.
Install
With Node.js:
$ npm install handlebars-layouts
With Bower:
$ bower install shannonmoeller/handlebars-layouts
API
Helpers are generated by passing in your instance of Handlebars. This allows you to selectively register the helpers on various instances of Handlebars.
layouts(handlebars) : Object
-
handlebarsHandlebars- An instance of Handlebars.
Generates an object containing the layout helpers suitible for passing into registerHelper.
var handlebars = require('handlebars'),
layouts = require('handlebars-layouts');
handlebars.registerHelper(layouts(handlebars));
layouts.register(handlebars) : Object
-
handlebarsHandlebars- An instance of Handlebars.
Both generates an object containing the layout helpers and registers them with Handlebars automatically.
var handlebars = require('handlebars'),
layouts = require('handlebars-layouts');
layouts.register(handlebars);Helpers
{{#extend [partial] [context] [key=value ...]}}
-
partialString- Name of partial to render. -
contextObject(Optional) - A custom context for the partial. -
attributesObject(Optional) - Arbitrary values that will be added to the partial data context.
Loads a layout partial of a given name and defines block content.
The {{#extend}} helper allows you to reason about your layouts as you would class extension where the above is equivalent to the following psuedo code:
class Page extends Layout {
constructor() {
this.foo = 'bar';
}
title() {
return 'Example - ' + super();
}
}
{{#embed [partial] [context] [key=value ...]}}
-
partialString- Name of partial to render. -
contextObject(Optional) - A custom context for the partial. -
attributesObject(Optional) - Arbitrary values that will be added to the partial data context.
Allows you to load a partial which itself extends from a layout. Blocks defined in embedded partials will not conflict with those in the primary layout.
The {{#embed}} helper allows you to reason about your partials as you would class instantiation where the above is equivalent to the following psuedo code:
class Page extends Layout {
body() {
var gallery = new Gallery();
gallery.replaceBody('<img src="1.png" alt="" />\n<img src="2.png" alt="" />');
var modal = new Modal({
foo: 'bar',
name: this.user.fullName
});
modal.prependTitle('Image 1 - ');
modal.replaceBody('<img src="1.png" alt="" />');
return gallery.toString() + modal.toString();
}
}
{{#block [name]}}
-
nameString- Block identifier.
Defines a named block, with optional default content. Blocks may have content appended, prepended, or replaced entirely when extending or embedding. You may append and prepend to the same block multiple times.
{{#content [name] mode="(append|prepend|replace)"}}
-
nameString- Identifier of the block to modify. -
modeString(Optional) - Means of providing block content. Default:replace.
Sets block content, optionally appending or prepending using the mode attribute.
Layout:
Page:
Output:
Conditional Blocks
There are times where you need to wrap a block with an element or use a different class depending on whether content has been provided for a block. For this purpose, the content helper may be called as a subexpression to check whether content has been provided for a block.
For example, you may wish to have an optional column in a grid layout:
For a page that only needs a left column, you may omit defining content for the right block:
Resulting in:
<div class="grid">
<div class="grid-col grid-col_full">
<p>Left</p>
</div>
</div>For a page with two columns, simply define content for both blocks:
Resulting in:
<div class="grid">
<div class="grid-col grid-col_2of3">
<p>Left</p>
</div>
<div class="grid-col grid-col_1of3">
<p>Right</p>
</div>
</div>Example
layout.hbs
page.html
Putting Them Together
var handlebars = require('handlebars');
var layouts = require('handlebars-layouts');
// Register helpers
handlebars.registerHelper(layouts(handlebars));
// Register partials
handlebars.registerPartial('layout', fs.readFileSync('layout.hbs', 'utf8'));
// Compile template
var template = handlebars.compile(fs.readFileSync('page.html', 'utf8'));
// Render template
var output = template({
title: 'Layout Test',
items: [
'apple',
'orange',
'banana'
]
});
console.log(output);Output (prettified for readability)
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
