The Ghost Themes Developer Hub

Welcome to the Ghost Themes developer hub. You'll find comprehensive guides and documentation to help you start working with Ghost Themes as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

if

{{if}} Helper - Test for a conditional

Usage: {{#if featured}}{{/if}}

Type
Parameters
Attributes

conditional value (any type)

n/a

The {{#if}} block helper comes built in with Handlebars.

Description

{{#if}} allows for testing very simple conditionals, and executing different template blocks depending on the outcome.

The conditionals that can be tested are very simple, essentially only checking for 'truthiness'. The evaluation rules are explained in the section below.

Like all block helpers, {{#if}} supports adding an {{else}} block or using ^ instead of # for negation - this means that the {{#if}} and {{else}} blocks are reversed if you use {{^if}} and {{else}} instead. In addition, it is possible to do {{else if ...}}, to chain together multiple options like a switch statement.

Evaluation rules

The if helper takes a single value, and evaluates whether it is true or false. Any passed in value which is equivalent to false, 0, undefined, null, "" (an empty string) or [] (an empty array) is considered false, and any other value is considered true.

  • Any boolean value, like the featured flag on a post, will evaluate to true or false as you expect.
  • Any string value will be true, as long as it is not null or empty
  • All numerical values, with the exception of 0 evaluate to true, 0 is the same as false
  • Any property which doesn't exist or is not set will always evaluate false
  • Empty arrays or objects will be false

Example code

When in the scope of a post, featured is a boolean flag. The following code example will evaluate to true only if the post is marked as featured.

{{#post}}
  {{#if featured}}
   ...do something if the post is featured...
  {{/if}}
{{/post}}

You can also use this to test if any property is set. Strings, like image URLs will evaluate to true as long as one is present, and will be null (false) otherwise:

{{#post}}
  {{#if feature_image}}
     <img src="{{img_url feature_image}}" />
  {{else}}
		 <img src="{{asset "img/default-img.jpg"}}" />
  {{/if}}
{{/post}}

Note 1: There's no need to switch between double and single quotes when writing HTML with handlebars. Double quotes can be used for both because the handlebars is executed first.

Note 2: You don't need to use {{#if}} to test if a post exists in the previous example, because the {{#post}} block automatically does this for you and will support {{else}} or ^ syntax if needed:

{{#post}}
  {{#if feature_image}}
     <img src="{{img_url feature_image}}" />
  {{else}}
     <img src="{{asset "img/default-img.jpg"}}" />
  {{/if}}
{{else}}
<p>No posts to display!</p>
{{/post}}

If you want to negate the if statement, i.e. test that the conditional is false, rather than true, you can do so by using the ^ instead of # in the if helper, or you could use the unless helper if you prefer.

// This is identical to the `{{#unless}}` helper
{{^if featured}}
  ... the post is not featured...
{{/if}}

If you're looking to do more complex conditionals, E.g. testing for particular values of tags or authors, you need to check out the has helper instead of the if helper.

if

{{if}} Helper - Test for a conditional