2. Tutorials
  3. hapi — Create and Use Custom Handlebars Helpers

hapi — Create and Use Custom Handlebars Helpers

Hapi has great view support out of the box and ships with handlebars support by default. The framework offers multiple options to configure handlebars the way it fits perfectly into your project structure. Within earlier posts, we already guided you through the creation of a dynamic layout template and partial view support. This time, we use the helpersPath option and create our own custom handlebars helpers for views rendered by hapi.

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

File Structure

If you read the related posts, you will recognize the file structure used for this tutorial since we already used it for the previous ones. We place all our template files (ending on .html) into the views directory. Additionally, to keep the helpers close to the views, we put them in a separated helpers folder inside the views directory.

Besides the views, we have a single file server.js which describes the minimum functionality required to make this example work properly.

The following overview outlines the the file structure:

views/  
    helpers/
        isSparta.js
        isAdmin.js
    partials/
    layout/
        default.html
    index.html
server.js

Our helper files have their own directory called helpers and are javascript files ending on .js. The default layout is located within the layout folder. The index.html is a normal view showing information to the user :)

Hapi Server View Configuration

As with dynamic layouts and partial views, we use the same server code for this example about custom helpers with hapi. The important part is the view configuration for the server. This time, we define the helpersPath property to let hapi know where to find our custom handlebars helpers.

const Hapi = require('hapi')

// Create hapi server instance
const server = new Hapi.Server({  
    host: 'localhost',
    port: 3000
})


async function liftOff() {  
  await server.register({
    plugin: require('vision')  // add template rendering support in hapi
  })

  server.views({
    engines: {
        html: require('handlebars')
    },
    path: 'views',
    layoutPath: 'views/layout',
    layout: 'default',
    partialsPath: 'views/partials'
    helpersPath: 'views/helpers',
  })

  // create your routes
  server.route({
    method: 'GET',
    path: '/',
    handler: (request, h) => {
      // Render the view with the custom greeting
      const data = {
        title: 'This is Index!',
        message: 'Hello, World. You crazy handlebars layout',
        user: { role: 'user' }
      }

      return h.view('index', data)
    }
  })

  try {
    await server.start()
    // Log to the console the host and port info
    console.log('Server started at: ' + server.info.uri)
  } catch (err) {
    console.log(err)
    process.exit(1)
  }
}

liftOff()

The helpersPath property expects the directory path to your helper files. Hapi does not support sub-folders within the helpers directory. That’s why you need to put all your helpers into the defined directory.

Note: keep an eye on the path definition. The example above uses a relative path to the helper folder instead of an absolute path. Starting the node server from another location than the root folder of this example project will result in wrong paths. Node offers options like __dirname and the path module to create more robust paths.

Create Your Helper

Before we create a custom helper, we need to set you in the right context. The important thing to understand: the helpers we’re going to create extend the handlebars template engine, not hapi itself. Helpers can only be used in handlebars view templates, not as functions in your hapi server code.

Helpers are functions used within view templates. They can perform data manipulations and transformations using the template context. The name of each file within the helpers directory is used as the helper name.

Helpers must export a single method with signature function(context) and return a string value. Passing data to a helper extends the signature to function(options, context). We explain both method declarations in more detail in the following subsections.

Helper Definition: function(context)

Hapi expects a single function with signature function(context) for each helper. The following code snippet illustrates the isAdmin helper function which can be used to check whether a user has an admin role assigned.

// isAdmin Helper
// Usage: `{{#isAdmin}}`
// Checks whether the user has admin or owner role
const _ = require('lodash')

function isAdmin(context) {  
  if (_.isEmpty(context)) {
    return context.inverse(this)
  }

  const user = context.data.root.user

  if (_.includes([ user.role ], 'owner', 'admin')) {
    return context.fn(this)
  }

  return context.inverse(this)
}

module.exports = isAdmin

Data passed to a view in hapi is available within the helper’s context object. Hapi saves the data in the context.data.root object. Let’s dive into the code and have a look at each part.

Actually, the context object shouldn’t be empty, null or undefined. We just make sure you won’t run into type errors because of undefined is not a function. The user object within this helper is available because we passed data to the view within the handler method of the route definition. Further, we use lodash to verify whether the user has the admin or owner role assigned.

If the user is verified as admin or owner, we call return context.fn(this). The method encapsulates the view content while calling the helper. Use the isAdmin helper in your view with block definition and add further HTML markup which will be rendered if the helper returns true. The usage section provides a concrete example.

If the user doesn’t have admin access, the helper returns with return context.inverse(this). Your view will be transformed and the part between your isAdmin block won’t be rendered.

Helper Options: function(options, context)

Handlebars offers the ability to pass additional options to your helper function. Hapi supports this functionality as well and passes additional options from your view to your helper. The following code example describes the usage of options within your helper function.

// isSparta helper — for demonstration purposes
var _               = require('lodash'),  
    isSparta;

isSparta = function (options, context) {  
    options = options || {};

    if (_.isEqual(options, 'sparta')) {
      return 'This is sparta!';
    }

    return 'No sparta today';
};

module.exports = isSparta;

The next section shows the usage of the isSparta helper within a view. You pass options from a view to the helper by separating the helper call and its options with a space: {{isSparta 'sparta'}}. The isSparta helper returns a string which will be rendered in replace of your helper call within your view.

Helper With Multiple Options: function(option1, …, optionN, context)

You can pass multiple options from your view to the helper function. Hapi maps each option to the helpers signature which results in a separate variable for each option value.

Changing the isSparta helper from above to a helper with three options, changes the helper signature to: function(option1, option2, option3, context).

Helper Usage

Enough theory. Let’s look at code examples to get a better understanding which transformations can be made using handlebars helper functions.

The following snippet shows the usage of the isAdmin helper. The block definition starting with {{#isAdmin}} encapsulates additional HTML markup which is only rendered if the helper function returns with return context.fn(this).

<a href='/navigation/link1'>Navigation Link 1</a>  
<a href='/navigation/link2'>Navigation Link 2</a>

{{#isAdmin}}
    {{! show admin navigation}}
    <h2>Admin Navigation</h2>
    <a href='/super/secret/admin/link>Secret Link</a>
{{/isAdmin}}

Each block helper in handlebars ends with a slash followed by the helper name. In this case we need to end the encapsulating markup with {{/isAdmin}} to let handlebars know what will be rendered in case the helper returns successfully.

The example below illustrates the usage of options within handlebars helper functions. This time, we don’t define a block helper. Instead, we pass an additional option value to the helper. The helper returns a string value which replaces the helper definition within the view.

<h1>{{title}}</h1>  
<p>{{message}}</p>

{{! call test helper with option value}}
<p>{{isSparta 'sparta'}}</p>  
<p>{{isSparta 'option'}}</p>

Using the isSparta helper from above, the rendered HTML of the view depends on the passed option value.

<h1>{{title}}</h1>  
<p>{{message}}</p>

<p>This is sparta!</p>  
<p>No sparta today</p>

Both helper definitions within the view are replaced by the respective string returned from isSparta helper.

Please use the comments below or give us a shot @futurestud_io and let us know about any issues you’re having with handlebars helper functions in hapi.

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous