Handlebars templates for Koa
koa-hbs is middleware. We stash an instance of koa-hbs for you in the library
so you don't have to manage it separately. Configure the default instance by
passing an options hash to #middleware. To render a template then,
just yield this.render('templateName');. Here's a basic app demonstrating all that:
var koa = require('koa');
var hbs = require('koa-hbs');
var app = koa();
// koa-hbs is middleware. `use` it before you want to render a view
app.use(hbs.middleware({
viewPath: __dirname + '/views'
}));
// Render is attached to the koa context. Call `this.render` in your middleware
// to attach rendered html to the koa response body.
app.use(function *() {
yield this.render('main', {title: 'koa-hbs'});
})
app.listen(3000);
After a template has been rendered, the template function is cached. #render
accepts two arguements - the template to render, and an object containing local
variables to be inserted into the template. The result is assigned to Koa's
this.response.body.
The plan for koa-hbs is to offer identical functionality as express-hbs (eventaully). These options are supported now.
viewPath requiredType: Array|String
Full path from which to load templates
handlebarsType:Object:Handlebars
Pass your own instance of handlebars
templateOptionsType: Object
Hash of handlebars options to
pass to template()
extnameType:String
Alter the default template extension (default: '.hbs')
partialsPathType:Array|String
Full path to partials directory
defaultLayoutType:String
Name of the default layout
layoutsPathType:String
Full path to layouts directory
contentHelperNameType:String
Alter contentFor helper name
blockHelperNameType:String
Alter block helper name
disableCacheType:Boolean
Disable template caching
Helpers are registered using the #registerHelper method. Here is an example using the default instance (helper stolen from official Handlebars docs:
hbs = require('koa-hbs');
hbs.registerHelper('link', function(text, url) {
text = hbs.Utils.escapeExpression(text);
url = hbs.Utils.escapeExpression(url);
var result = '<a href="' + url + '">' + text + '</a>';
return new hbs.SafeString(result);
});
Your helper is then accessible in all views by using, {{link "Google" "http://google.com"}}
The registerHelper, Utils, and SafeString methods all proxy to an
internal Handlebars instance. If passing an alternative instance of
Handlebars to the middleware configurator, make sure to do so before
registering helpers via the koa-hbs proxy of the above functions, or
just register your helpers directly via your Handlebars instance.
You can also access the current Koa context in your helper. If you want to have
a helper that outputs the current URL, you could write a helper like the following
and call it in any template as {{requestURL}}.
hbs.registerHelper('requestURL', function() {
var url = hbs.templateOptions.data.koa.request.url;
return url;
});
The simple way to register partials is to stick them all in a directory, and
pass the partialsPath option when generating the middleware. Say your views
are in ./views, and your partials are in ./views/partials. Configuring the
middleware via
app.use(hbs.middleware({
viewPath: __dirname + '/views',
partialsPath: __dirname + '/views/partials'
}));
will cause them to be automatically registered. Alternatively, you may register
partials one at a time by calling hbs.registerPartial which proxies to the
cached handlebars #registerPartial method.
Passing defaultLayout with the a layout name will cause all templates to be
inserted into the {{{body}}} expression of the layout. This might look like
the following.
<!DOCTYPE html>
<html>
<head>
<title>{{title}}</title>
</head>
<body>
{{{body}}}
</body>
</html>
In addition to, or alternatively, you may specify a layout to render a template
into. Simply specify {{!< layoutName }} somewhere in your template. koa-hbs
will load your layout from layoutsPath if defined, or from viewPath
otherwise. If viewPath is set to an Array of paths, the first path in the
array will be assumed to contain the layout named.
At this time, only a single content block ({{{body}}}) is supported.
As of version 0.9.0, it's possible to override the layout used for rendering,
using locals. For example:
router.get('/', function *() {
yield this.render('foo', {
layout: 'bar'
});
});
See the tests for more.
Reserve areas in a layout by using the block helper like so.
{{#block "sidebar"}}
<!-- default content for the sidebar block -->
{{/block}}
Then in a template, use the contentFor helper to render content into the
block.
{{#contentFor "sidebar"}}
<aside>
<h2>{{sidebarTitleLocal}}</h2>
<p>{{sidebarContentLocal}}</p>
</aside>
{{/contentFor}}
To disable the caching of templates and partials, use the disableCache option.
Set this option to true to disable caching. Default is false.
Remember to set this option to false for production environments, or performance
could be impacted!
Application local variables ([this.state](https://github.com/koajs/koa/blob/master/docs/api/context.md#ctxstate)) are provided to all templates rendered within the application.
app.use(function *(next) {
this.state.title = 'My App';
this.state.email = 'me@myapp.com';
yield next;
});
The state object is a JavaScript Object. The properties added to it will be exposed as local variables within your views.
<title>{{title}}</title>
<p>Contact : {{email}}</p>
Koa2 is supported via the @next module version. It is considered experimental
and requires Node v7 or higher. You can obtain this version by running:
npm install koa-hbs@next --save
For information on using this version, please read the branch's
README. We recommend using
harmonica to enable the --harmony
flags, which allows for native async/await.
If you'd rather not use an experimental version, or you need to use an older
version of Node, you can reference this example
repo that demonstrates how to use koa-hbs with Koa2:
koa-hbs-koa2-howto
Credit to @chrisveness for the initial investigation.
You can run the included example via npm install koa and
node --harmony app.js from the example folder.
Here's a few things koa-hbs does not plan to support unless someone can provide really compelling justification.
koa-hbs does not support asynchronous helpers. No, really - just load your data before rendering a view. This helps on performance and separation of concerns in your app.
As of koa-hbs@0.9.0, the version of the Handlebars dependency bundled with this module has been updated to 4.0.x. If this causes conflicts for your project, you may pass your own instance of Handlebars to the module, or downgrade to the last 0.8.x version.
Functionality and code were inspired/taken from express-hbs. Many thanks to @jwilm for authoring this middleware.
FAQs
Handlebars Templates via Generators for Koa
The npm package koa2-hbs receives a total of 1 weekly downloads. As such, koa2-hbs popularity was classified as not popular.
We found that koa2-hbs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.