hbs

What is hbs?

The hbs package is a Handlebars view engine for Express. It allows you to use Handlebars templates to render HTML pages in your Express applications.

What are hbs's main functionalities?

Registering Partials

This feature allows you to register partials, which are reusable components that can be included in other templates. The code sample demonstrates how to register partials located in the 'views/partials' directory.

const hbs = require('hbs');
hbs.registerPartials(__dirname + '/views/partials');

Using Helpers

Helpers are functions that can be used within your templates to perform specific tasks. The code sample shows how to register a helper named 'scream' that converts text to uppercase.

const hbs = require('hbs');
hbs.registerHelper('scream', function(text) {
  return text.toUpperCase();
});

Rendering Views

This feature allows you to render views using Handlebars templates. The code sample demonstrates setting up an Express application to use hbs as the view engine and rendering an 'index' view with a title.

const express = require('express');
const hbs = require('hbs');
const app = express();
app.set('view engine', 'hbs');
app.get('/', (req, res) => {
  res.render('index', { title: 'Home Page' });
});
app.listen(3000);

Other packages similar to hbs

express-handlebars

express-handlebars is another Handlebars view engine for Express. It offers more features and flexibility compared to hbs, such as layout support and advanced configuration options.

pug

Pug is a high-performance template engine heavily influenced by Haml and implemented with JavaScript for Node.js and browsers. Unlike hbs, which uses Handlebars syntax, Pug uses its own unique syntax that is more concise.

ejs

EJS (Embedded JavaScript) is a simple templating language that lets you generate HTML markup with plain JavaScript. It is similar to hbs in that it integrates well with Express, but it uses a different syntax and offers different features.

README

hbs

Express.js view engine for handlebars.js

Installation

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

$ npm install hbs

Use

Using hbs as the default view engine requires just one line of code in your app setup. This will render .hbs files when res.render is called.

app.set('view engine', 'hbs');

To use a different extension (i.e. html) for your template files:

app.set('view engine', 'html');
app.engine('html', require('hbs').__express);

Helpers and Partials

hbs exposes the registerHelper and registerPartial method from handlebars.

var hbs = require('hbs');

hbs.registerHelper('helper_name', function (options) { return 'helper value'; });
hbs.registerPartial('partial_name', 'partial value');

For convenience, registerPartials provides a quick way to load all partials from a specific directory:

var hbs = require('hbs');

hbs.registerPartials(__dirname + '/views/partials', function (err) {});

Partials that are loaded from a directory are named based on their filename, where spaces and hyphens are replaced with an underscore character:

template.html      -> {{> template}}
template 2.html    -> {{> template_2}}
login view.hbs     -> {{> login_view}}
template-file.html -> {{> template_file}}

See the handlebars.js documentation for more information.

The way the file is renamed to a partial name can be adjusted by providing a rename option. The function will recieve the file path relative to the registered directory and without the file extension. If the returned value contains any whitespace, those characters are replaced with a corresponding underscore character.

var hbs = require('hbs')

hbs.registerPartials(path.join(__dirname, '/views/partials'), {
  rename: function (name) {
    // all non-word characters replaced with underscores
    return name.replace(/\W/g, '_')
  }
})

Note: This method is async; meaning that the directory is walked in a non-blocking manner to app startup.

Exposing locals as template data

hbs has the ability to expose the application and request locals within any context inside a view. To enable this functionality, simply call the localsAsTemplateData method and pass in your Express application instance.

var hbs = require('hbs');
var express = require('express');

var app = express();
hbs.localsAsTemplateData(app);

app.locals.foo = "bar";

The local data can then be accessed using the @property syntax:

top level: {{@foo}}
{{#each items}}
  {{label}}: {{@foo}}
{{/each}}

Note: In partials and templates, local data can be accessed without using @ prefix.

handlebars

The handlebars require used by hbs can be accessed via the handlebars property on the hbs module.

If you wish to use handlebars methods like SafeString please do so on this property. Do not register helpers or partials in this way.

// hbs.handlebars is the handlebars module
hbs.handlebars === require('handlebars');

Recipes

more than one instance

You can create isolated instances of hbs using the create() function on the module object.

var hbs = require('hbs');

var instance1 = hbs.create();
var instance2 = hbs.create();

app.engine('html', instance1.__express);
app.engine('hbs', instance2.__express);

Each instance has the same methods/properties as the hbs module object. The module object is actually just an instance created for you automatically.

extra scripts or styles

Sometimes it is useful to have custom scripts or stylesheets on your pages. Handlebars does not provide a way to import or extend a template, but through the use of helpers you can create a similar result.

We can take advantage of the fact that our body template is processed before the layout template. Knowing this, we can create two helpers block and extend which can be used to 'inject' custom stylesheets or scripts into the layout template. The block helper will act as a placeholder for values specified in earlier extend helpers.

See examples/extend for a working example. Note how the index.hbs file defines extra stylesheets and scripts to be injected into the layout. They are put into the head section and at the end of the body respectively. If this was not done, the stylesheet would be in the body and the script would print foo bar too soon.

Helpful Modules

• hbs-utils: A small utility library that provides helpers for registering and compiling partials including automatic updates when partials are changed.