Learn Handlebars in 10 Minutes or Less

January 28th 2015

JavaScript | Quick Learn

Handlebars.js is a popular templating engine that is powerful, simple to use and has a large
community. It is based on the Mustache template language, but improves it in several important
ways. With Handlebars, you can separate the generation of HTML from the rest of your
JavaScript and write cleaner code.

This quick article is an attempt to teach you almost everything you need to know about
Handlebars in 10 minutes or less. It may seem a bit overwhelming in the beginning, but just like
riding a bike (pun intended), after you get the hang of it, it becomes the easiest thing in the
world.

0. Adding it to your project

Adding handlebars to your project is pretty straightforward. Just go to http://handlebarsjs.com/ ,
and click the download button to get the latest version. At the moment of writing, this is version
2.0.0. Now all you have to do is to include the library in your html with a regular <script> tag.

You can also use a CDN-hosted version, which has the added benefit that the same file might be
cached already in the visitor's browser, if it has been used by another website.

// From File
<script src="handlebars-v2.0.0.js"></script>

// From CDN
<script
src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/2.0.0/handlebars.js
"></script>

1. Templates
Once you have the library in place, you can start writing templates. The recommended way of
adding templates to your page is by including them in <script> tags with a special type. The type
attribute is important, otherwise the browser will attempt to parse them as JavaScript (which they
are not).

The templates have an easy to grasp syntax. They can contain HTML and text, mixed with
Handlebars expressions. Expressions are wrapped in double or triple curly braces {{}}.
Expressions tell Handlebars to include the value of variables or to execute helper functions.
Templates need to be compiled to a JavaScript function before use. You can see an example
below. Note that we are using jQuery to make working with the DOM easier, but Handlebars can
work perfectly without it.
htmljs

2. Expressions
To build up from the previous example, any data that you print out in an {{ }} expression, will
automatically get HTML escaped by handlebars. This is a great security feature, but some times
you might wish to print raw HTML. In this case you will use the triple curly brace expression
{{{ }}}.

Also, notice that the handlebars expressions support nested values which enables us to easily
access any data from a JavaScript object.

htmljs

3. Context
Handlebars builds on the best features of Mustache. And one these is the concept of context - the
object where properties you include in curly braces are looked up. Every template you write has
a context. On the top level, this is the JavaScript object that you pass to the compiled template.
But helpers like #each or #with modify it, so that you can access the properties of the iterated
object directly. The next example will make things clearer.

htmljs

4. Helpers
Handlebars doesn't allow you to write JavaScript directly within templates. Instead, it gives you
helpers. These are JavaScript functions that you can call from your templates, and help you reuse
code and create complex templates. To call a helper, just use it as an expression -
{{helpername}}. You can pass parameters as well - {{helpername 12345}}, which are passed
as parameters to your helper function.
To create a helper, use the registerHelper function. See the example below, which demonstrates a
creating a helper, and a number of Handlebars' built-in ones:

htmljs

5. Block helpers
Block helpers are just like the regular ones, but they have an opening and a closing tag (like the
#if and #each built-ins). These helpers can modify the HTML and content they are wrapped
around. They are a bit more complicated to create, but are very powerful. You can use them to
reuse functionality or to create large blocks of HTML in a reusable way (for example lists of
items that you use on many places in your app).

To create a block helper, you again use Handlebars.registerHelper(). The difference is that
this time we will use the second parameter of our callback function - options. It exposes a few
useful properties that we will need. See the example below, which turns text uppercase.

htmljs

Resources and further reading

You now know enough to start using Handlebars in your web apps! But it never hurts to know a
bit more, so here are a few more resources and articles if you wish to dig deeper in the library:

 Handlebars.js - Handlebars' home is full of great documentation and examples.

 Try Handlebars.js - try out different Handlebars scenarios in your browser (it is for an
older version of handlebars, unfortunately, but the basics are pretty much the same).
 Handlebars Helpers - a collection of 130+ handlebars helpers in ~20 categories.
 SWAG - more handlebars helpers.
 Handlebars API Reference.