All Projects → koajs → Koa Hbs

koajs / Koa Hbs

Licence: mit
Handlebars templates for Koa.js

Programming Languages

javascript
184084 projects - #8 most used programming language

Projects that are alternatives of or similar to Koa Hbs

Koatty
Koa2 + Typescript = Koatty. Use Typescript's decorator implement IOC and AOP.
Stars: ✭ 67 (-57.05%)
Mutual labels:  middleware, koa, koa2
polix
🚀 Node.js Web Framework
Stars: ✭ 32 (-79.49%)
Mutual labels:  middleware, koa, koa2
Koa Helmet
Important security headers for koa
Stars: ✭ 595 (+281.41%)
Mutual labels:  middleware, koa, koa2
Service Tools
Prepare your Node.js application for production
Stars: ✭ 89 (-42.95%)
Mutual labels:  middleware, koa
Koach Javascript
Production ready Koa2 boilerplate.
Stars: ✭ 79 (-49.36%)
Mutual labels:  koa, koa2
Koa Ts
koa2+typescript
Stars: ✭ 82 (-47.44%)
Mutual labels:  koa, koa2
Vue Socket.io Chat
💬 TypeScript + Vue + Express/Koa + Socket.io
Stars: ✭ 61 (-60.9%)
Mutual labels:  koa, koa2
Chatroom
vue2聊天室,图灵机器人,node爬虫
Stars: ✭ 103 (-33.97%)
Mutual labels:  koa, koa2
Koa Sslify
Enforce HTTPS in node.js koa apps
Stars: ✭ 100 (-35.9%)
Mutual labels:  koa, koa2
Strapi
🚀 Open source Node.js Headless CMS to easily build customisable APIs
Stars: ✭ 41,786 (+26685.9%)
Mutual labels:  koa, koa2
Awilix Koa
Awilix helpers/middleware for Koa 2
Stars: ✭ 121 (-22.44%)
Mutual labels:  middleware, koa
Nodejs Koa Blog
基于 Node.js Koa2 实战开发的一套完整的博客项目网站
Stars: ✭ 1,162 (+644.87%)
Mutual labels:  koa, koa2
Trafficlight
🚦 Flexible NodeJS Routing Decorators for API Routing
Stars: ✭ 69 (-55.77%)
Mutual labels:  koa, koa2
Koa Starter
🐨 A starter kit for a slightly opinionated koa project.
Stars: ✭ 87 (-44.23%)
Mutual labels:  koa, handlebars
Koalerplate
Simple Koa Boilerplate for APIs
Stars: ✭ 118 (-24.36%)
Mutual labels:  koa, koa2
Koa Proxies
a [email protected] proxy middleware
Stars: ✭ 125 (-19.87%)
Mutual labels:  koa, koa2
Koa Mobx React Starter
A straightforward starter for Node javascript web projects. Using Koa, MobX and ReactJS (with universal / isomorphic server rendering)
Stars: ✭ 102 (-34.62%)
Mutual labels:  koa, koa2
Sactive Web
🚀 A dependency injection web framework for Node.js.
Stars: ✭ 143 (-8.33%)
Mutual labels:  koa, koa2
Egg Authz
egg-authz is an authorization middleware for Egg.js based on Casbin
Stars: ✭ 50 (-67.95%)
Mutual labels:  middleware, koa2
Koa Useragent
Koa user-agent middleware
Stars: ✭ 54 (-65.38%)
Mutual labels:  middleware, koa

koa-hbs Build Status

Handlebars templates for Koa

 

🚀   Are you ready to tackle ES6 and hone your JavaScript Skills?   🚀
Check out these outstanding ES6 courses by @wesbos


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 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 arguments - 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.

Options

The plan for koa-hbs is to offer identical functionality as express-hbs (eventaully). These options are supported now.

viewPath required

Type: Array|String
Full path from which to load templates

handlebars

Type:Object:Handlebars
Pass your own instance of handlebars

templateOptions

Type: Object
Hash of handlebars options to pass to template()

extname

Type:String
Alter the default template extension (default: '.hbs')

partialsPath

Type:Array|String
Full path to partials directory

defaultLayout

Type:String
Name of the default layout

layoutsPath

Type:String
Full path to layouts directory

contentHelperName

Type:String
Alter contentFor helper name

blockHelperName

Type:String
Alter block helper name

disableCache

Type:Boolean
Disable template caching

Registering Helpers

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;
});

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.

<!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.

Overriding Layouts using Locals

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.

Block content

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}}

Disable Template Caching

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!

Locals

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 = '[email protected]';
  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

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 [email protected] --save

For information on using this version, please read the branch's README. If using a version of node older than v7.6, we recommend using harmonica to enable the --harmony flags, which activates native async/await support.

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.

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.

Handlebars Version

As of [email protected], 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.

Credits

Functionality and code were inspired/taken from express-hbs. Many thanks to @jwilm for authoring this middleware.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].