Introduction to Handlebars

Philosophy: Logic-Less Templates

Handlebars is a superset of Mustache created by Yehuda Katz in 2010. It enforces separation of concerns by keeping business logic out of templates. You write HTML with {{ }} expressions — no arbitrary JS in your views.

Simple Expressions

<!-- Property access -->
<h1>{{title}}</h1>

<!-- Nested property (dot notation) -->
<p>{{user.name}}</p>
<p>{{user.address.city}}</p>

<!-- Comments (not in output) -->
{{!-- This is a comment --}}
{{! Short comment }}

#if / else

{{#if isAdmin}}
  <div class="badge admin">Admin</div>
{{else if isEditor}}
  <div class="badge editor">Editor</div>
{{else}}
  <div class="badge member">Member</div>
{{/if}}

<!-- #if is falsy-aware:
     false, undefined, null, "",
     0, [] all evaluate to false -->

registerHelper — Inline Helpers

// Simple value helper
Handlebars.registerHelper(
  'uppercase', function(str) {
    return str.toUpperCase();
  }
);

// In template:
// {{uppercase user.name}}

// Multiple arguments
Handlebars.registerHelper(
  'currency', function(amount, curr) {
    return new Intl.NumberFormat('en-GB', {
      style: 'currency',
      currency: curr || 'GBP'
    }).format(amount);
  }
);

// {{currency product.price "USD"}}

registerPartial

// Register a named partial
Handlebars.registerPartial('nav',
  '<nav>{{#each links}}' +
  '<a href="{{url}}">{{label}}</a>' +
  '{{/each}}</nav>'
);

// Use in template:
// {{> nav}}

<!-- Pass data to partial -->
{{> userCard user}}

<!-- Pass hash parameters -->
{{> card title="Hello" body="World"}}

Handlebars.compile()

const source = '<h1>{{title}}</h1>';

// Compile to a reusable function
const template = Handlebars.compile(source);

// Execute with different data
template({ title: 'Page One' });
// => '<h1>Page One</h1>'

template({ title: 'Page Two' });
// => '<h1>Page Two</h1>'

Compile once, execute many times. The compiled function is a plain JS function.

Setup with Express

npm install express express-handlebars

const express = require('express');
const { engine } = require(
  'express-handlebars'
);

const app = express();

app.engine('hbs', engine({
  extname: '.hbs',
  defaultLayout: 'main',
  layoutsDir: 'views/layouts/',
  partialsDir: 'views/partials/'
}));
app.set('view engine', 'hbs');
app.set('views', './views');

Default Layout

<!-- views/layouts/main.hbs -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>{{title}} | {{siteName}}</title>
  <link rel="stylesheet" href="/css/style.css">
</head>
<body>
  {{> nav}}
  <main class="container">
    {{{body}}}
  </main>
  {{> footer}}
</body>
</html>

The {{{body}}} placeholder is where view content is injected (triple-stache because the body is pre-rendered HTML).

Parent Context with ../

<!-- Data: { title: "Books", items: [...] } -->

{{#each items}}
  <!-- Inside #each, context = current item -->
  <h3>{{this.name}}</h3>

  <!-- Access parent context -->
  <p>Part of: {{../title}}</p>

  <!-- Go up two levels -->
  <p>{{../../siteName}}</p>
{{/each}}

Subexpression Syntax: (helper arg)

<!-- Nest helpers with parentheses -->
{{uppercase (truncate title 30)}}

<!-- Equivalent to: -->
<!-- 1. truncate(title, 30) -->
<!-- 2. uppercase(result) -->

<!-- Use as argument to block helpers -->
{{#if (eq status "active")}}
  <span class="badge-active">Active</span>
{{/if}}

Rule of Thumb

What Are Decorators?

Decorators modify the template program itself before execution. Unlike helpers (which produce output), decorators transform behaviour. They run at compile time and can modify the program's internal state.

compile() vs precompile()

precompile() is faster at runtime because parsing + compilation happen at build time. The client only needs the 6 KB runtime.

Directory Layout

my-app/
├── app.js
├── package.json
├── .env
├── config/
│   └── db.js
├── routes/
│   ├── index.js
│   ├── auth.js
│   └── products.js
├── controllers/
│   ├── authController.js
│   └── productController.js
├── models/
│   ├── User.js
│   └── Product.js
├── middleware/
│   ├── auth.js
│   └── validate.js
├── helpers/
│   └── hbs-helpers.js
├── views/
│   ├── layouts/
│   │   ├── main.hbs
│   │   └── admin.hbs
│   ├── partials/
│   │   ├── nav.hbs
│   │   ├── flash.hbs
│   │   ├── footer.hbs
│   │   └── components/
│   │       ├── card.hbs
│   │       └── modal.hbs
│   ├── home.hbs
│   ├── about.hbs
│   ├── auth/
│   │   ├── login.hbs
│   │   └── register.hbs
│   ├── products/
│   │   ├── index.hbs
│   │   ├── show.hbs
│   │   └── edit.hbs
│   └── error.hbs
└── public/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/

app.js — Full Express + Handlebars App

const express = require('express');
const { engine } = require(
  'express-handlebars'
);
const path = require('path');
const app = express();

app.engine('hbs', engine({
  extname: '.hbs',
  defaultLayout: 'main',
  helpers: {
    eq: (a, b) => a === b,
    year: () => new Date().getFullYear()
  }
}));
app.set('view engine', 'hbs');
app.set('views',
  path.join(__dirname, 'views'));
app.use(express.urlencoded(
  { extended: true }
));
app.use(express.static('public'));

let books = [
  { id: 1, title: '1984',
    author: 'Orwell', year: 1949 },
  { id: 2, title: 'Dune',
    author: 'Herbert', year: 1965 },
];
let nextId = 3;

app.get('/', (req, res) => {
  res.render('home', {
    title: 'Home',
    siteName: 'BookShelf',
    books,
    hasBooks: books.length > 0
  });
});

app.get('/books/new', (req, res) => {
  res.render('books/new', {
    title: 'Add Book',
    siteName: 'BookShelf',
    form: {}, error: null
  });
});

app.post('/books', (req, res) => {
  const { title, author, year } = req.body;
  if (!title || !author) {
    return res.render('books/new', {
      title: 'Add Book',
      siteName: 'BookShelf',
      form: req.body,
      error: 'All fields required'
    });
  }
  books.push({
    id: nextId++, title, author,
    year: parseInt(year)
  });
  res.redirect('/');
});

app.listen(3000);