Handlebars Helpers for Custom Templates

Jake Peters Updated by Jake Peters

If you're building a custom HTML template for your HelpDocs, you'll eventually need to use some of our helpers and partials.

Helpers

Helpers are extensions to the regular Handlebars syntax that allow you to manipulate data, loop through arrays, show HTML conditionally, and more. We've made a number of helpers to help you with common tasks.

Using Helpers

There's a few different ways to use helpers:

  1. Inline helpers
    The simplest way to use helpers is inline. e.g. 
    <<fallback article.title "Untitled Article">>
    ...will render literally to the article's title if it exists, falling back to "Untitled Article" if not. 
  2. Block helpers
    Block helpers can help you do conditional statements and loops. You prefix the helper name with a hash, and write extra HTML (or even more Handlebars) inside. Then use an else block for when the condition is not true. e.g. 

    <<#if article.is_featured>>
    This article is featured!
    <<else>>
    Not featured, sorry :(
    <</if>> 
    ...will render to "This article is featured!" if the article is featured, "Not featured, sorry :(" if not.
  3. Combining helpers
    Need to combine more than one helper? Use brackets! This is super helpful if you wanna display something conditionally, e.g.
    <<#if (gt category.meta.num_articles 1)>>
    This category has more than one article
    <</if>>
    ...will only show "This category has more than one article" if the category does in fact have more than one article.

Bundled Helpers

Helper Name

Description

Example Usage

if

Only show the content of the block if the condition is true, else show the content of the else block (if it exists)

<<#if article.is_featured>>
<p>Article is featured</p>
<<else>>
<p>Article is not featured</p>
<</if>>

unless

Opposite of if. Only show the content of the block if the condition is false, else show the content of the else block (if it exists)

<<#unless article.is_private>>
<h1>This is a public article</h1>
<</unless>>

each

Loop through an array. The current item is provided as this, you can access the root scope with @root, the current index with @index, and use @first and @last to see if this is the first or last item.

<<#each category.articles>>
<p><<this.title>></p>
<small><<this.description>></small>
<</each>>

eq

Checks if the two numbers passed are equal

<<#if (eq this.meta.num_articles 1)>>
There's one article in this category
<</if>>

gt

Checks if the first number is greater than the second

<<#if (gt this.meta.num_articles 1)>>
There's more than one article in this category
<</if>>

lt

Checks if the first number is less than the second

<<#each this.articles>>
<<#if (lt @index 5)>>
<img src="<<this.author.profile_image>>">
<</if>>
<</each>>

multiply

Multiplies two numbers together

<div class="margin-left:<<multiply @index 0.5>>em;"</div>

divide

Divides the first number by the second

<<#unless (gt (divide @index 2) 5)>>
<p>Some text</p>
<</unless>>

add

Adds two numbers together

This is loop number <<add @index 1>>

subtract

Subtracts the second number from the first

2 - 1 = <<subtract 2 1>>

hasPrefix

Checks if a string starts with a string prefix

<<#if (hasPrefix category.icon "fa-")>>
<i class="fa <<category.icon>>"></i>
<<else if (hasPrefix category.icon "http")>>
<img src="<<category.icon>>">
<</if>>

hasSuffix

Checks if a string ends with a string suffix

Suffix ends in fix:<<hasSuffix "Suffix" "fix">>

deepLookup

Behaves like the built-in Handlebars lookup helper, but returns an object of the original type rather than converting to a string.

The first category title is <strong><<deepLookup (deepLookup category.articles 0) "title">>

formatDate

Show a date in a format of your choice. Supports D, DD, M, MM, YY and YYYY tokens.

<<formatDate article.updated_at "DD.MM.YYYY">>

fallback

If the first value exists, returns that. If not, returns the second.

<<fallback meta.home_path "/">>

filterCategoriesByParentId

Used to find all subcategories of a given category ID

<<#each (filterCategoriesByParentId @root.meta.sidebar_categories this.category_id)>>
<h3><<this.title>></h3>
<</each>>

categoryById

Find a category by its ID

This title of the category of this article is <<(categoryById meta.sidebar_categories article.category_id).title>>

categoryIsAscendent

Checks if a category is ascendent of another. Useful when working with subcategories and sidebars.

<<#if (categoryIsAscendent @root.meta.sidebar_categories @root.category this)>>
<p>This is a parent of the displayed category</p>
<</if>>

In the example here the second parameter this is also a category. It's checking if the second category is ascendent of the first.

i18n

Find the current language version of a given internationalization key, falling back to the second string

This category has <<category.meta.num_articles>> <<i18n "articles" "docs">>

page

Only display the contents of a block if the page is equal to the given page. Possible values: home (can also be called categories), categoryarticlesearch.

<<#page "home">>
<<> superFancySearchBar>>
<<else>>
<<> boringOlSearchBar>>
<</page>>

isPermissioned

Shows content of a block if the article has any permissions on it. Requires article to be passed through.

<<#isPermissioned article>>
<div class="has_permissions_message">
<span>This article has Permissions and so can't be shared publicly.</span>
</div>
<</isPermissioned>>

Partials

Partials in Handlebars are snippets of HTML we provide for your convenience. Just like the partials you write yourself for the header and footer, these let you use reusable code that we maintain, without the effort.

Using Partials

You can use partials with the Handlebars partial syntax. For instance to create a contact button you can use <<> contactLink>>. That will render a clickable contact link your users can use to contact you. 

Because we maintain it, a) you don't have to worry about it, and b) it'll respect any integrations you have set up in your account.

Bundled Partials

Partial Name

Description

Example Usage

contactLink

Contact link that respects any connected integrations and your contact preferences in Settings. The class parameter will add a CSS class to the button of your choice, overriding the default button class applied.

<<> contactLink class="btn btn-secondary">>

categoryBreadcrumbs

Breadcrumbs that lead to your current page. This should be used in the category.hbs and article.hbs content partials only. The linkify parameter indicates whether the last category in the list should be wrapped in a hyperlink (like for an article page) or not (like for a category page).

<<> categoryBreadcrumbs linkify=true>>

hdFooter

Renders the HelpDocs footer according to your preferences in Settings > Brand. We require this to be present on all accounts, but you can include it anywhere you like.

<<> hdFooter>>

Custom Partials

We support the Handlebars 4 inline partial syntax, so you can make your own partials. This is super handy if you need to do anything recursive (like nesting categories) or repetitive (so you don't have to maintain two lots of the same code).

You can create a custom partial like this:

<<#*inline "myArticle">>
<h3><<article.title>><h3>
<p><<article.description>></p>
<</inline>>

Then invoke it just like you'd invoke any other partial, passing parameters if you like:

<<#each category.articles>>
<<> myArticle article=this>>
<</each>>

Easy as that!

Inline partials must be at the top level, not indented, and not nested inside any other markup. A good place to declare these would be header.hbs

What did you think of this doc?

Getting Started with a Custom HTML Template

Get in touch