# koa-hbs
**Repository Path**: mirrors_leecade/koa-hbs
## Basic Information
- **Project Name**: koa-hbs
- **Description**: Koa Handlebars Templates
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-09
- **Last Updated**: 2026-02-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
koa-hbs
=======
[Handlebars](http://handlebarsjs.com) Templates via for
[Koa](https://github.com/koajs/koa/)
[![Build Status][travis-badge]][repo-url]
## Usage
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](#options) hash to #middleware. To render a template then, just `yield this.render('templateName');`. Here's a basic app demonstrating all that:
```javascript
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`.
### Registering Helpers
Helpers are registered using the #registerHelper method. Here is an example
using the default instance (helper stolen from official Handlebars
[docs](http://handlebarsjs.com):
```javascript
hbs = require('koa-hbs');
hbs.registerHelper('link', function(text, url) {
text = hbs.Utils.escapeExpression(text);
url = hbs.Utils.escapeExpression(url);
var result = '' + text + '';
return new hbs.SafeString(result);
});
```
`registerHelper`, `Utils`, and `SafeString` 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.
### Registering Partials
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.
### Layouts
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.
```html
{{title}}
{{{body}}}
```
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.
At this time, only a single content block (`{{{body}}}`) is supported.
### Block content
Reserve areas in a layout by using the `block` helper like so.
```html
{{#block "sidebar"}}
{{/block}}
```
Then in a template, use the `contentFor` helper to render content into the
block.
```html
{{#contentFor "sidebar"}}
{{/contentFor}}
```
### Options
The plan for koa-hbs is to offer identical functionality as express-hbs
(eventaully). These options are supported _now_.
- `viewPath`: [_required_] Full path from which to load templates
(`Array|String`)
- `handlebars`: Pass your own instance of handlebars
- `templateOptions`: Hash of
[handlebars options](http://handlebarsjs.com/execution.html#Options) to pass
to `template()`
- `extname`: Alter the default template extension (default: `'.hbs'`)
- `partialsPath`: Full path to partials directory (`Array|String`)
- `defaultLayout`: Name of the default layout
- `layoutsPath`: Full path to layouts directory (`String`)
- `contentHelperName`: Alter `contentFor` helper name
- `blockHelperName`: Alter `block` helper name
- `disableCache`: Disable template caching
## Example
You can run the included example via `npm install koa` and
`node --harmony app.js` from the example folder.
## Unsupported Features
Here's a few things _koa-hbs_ does not plan to support unless someone can provide really compelling justification.
### Async Helpers
_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.
### Disable template caching
Add a new option `disableCache` for support this feature, but for performance reasons remember turn off this option for production environment.
## Credits
Functionality and code were inspired/taken from
[express-hbs](https://github.com/barc/express-hbs/).
[travis-badge]: https://travis-ci.org/jwilm/koa-hbs.png?branch=master
[repo-url]: https://travis-ci.org/jwilm/koa-hbs