for

Template engines

Description and usage of the template engines used in our code.


Liquid

All the files we're installing inside your theme are also .liquid templates.
The main benefit of this is for you to be able to access your settings or your translations.

To use liquid variables and helpers, just use your usual syntax:

{% if settings.use_logo %}
  {{ 'logo.png' | asset_url | img_tag: shop.name }}
{% else %}
  <span class="no-logo">{{ shop.name }}</span>
{% endif %}
Liquid is a back-end templating engine. This means it is only evaluated at page render time.
This means that for instance, you can't use {{ product.title }} to change the way a product has been rendered by Algolia because we're dynamically retrieving it without reloading the page.
Fortunately, the next section about Hogan templates will solve this issue.

Hogan

To have some templating logic for dynamically rendered elements, we're using a front-end templating library called Hogan.js.

This templating engine is using the mustache syntax (documentation), with a main tweak: Both Liquid and Hogan use curly braces ({}) as their templating delimiters by default.
To avoid those conflicts, we've set hogan to use brackets ([]) instead.

Variables

Use [[ abc ]] to render a string.
Use [[& abc ]] to render a string that contains HTML. (For security reasons, you should be sure you trust the value)

You can access object attributes using those syntax: [[ attr.abc ]] will work as you expect.

Conditions

Hogan's condition are using the same conditionals than in JavaScript:

  • false, 0 (zero), "" (empty string), null, undefined and NaN are falsey values
  • All the others are truthy

Use [[# abc ]]abc is truthy[[/ abc ]] to check if abc is truthy.
Use [[^ abc ]]abc is falsy[[/ abc ]] to check if abc is falsey.

Blocks

The block is the same than for truthy conditions: [[# abc ]]content[[/ abc ]]. A block can allow you to do two things:

Entering an object

When using a variable name, it will now look inside the object first, and go up the object tree if it doesn't find it:

Example:

Template Object passed Result
[[# product ]]
  [[ title ]]
  by
  [[ storeName ]]
[[/ product ]]
{
  product: {
    title: 'iPhone'
  },
  storeName: 'Apple'
}
iPhone by Apple

Iterating on a list

You can use blocks to display a list.
If the list is composed of objects, it automatically enters each of them.
If the list is composed of values, use [[ . ]] to access them.
As with conditions, you can also use [[^ abc ]] content [[/ abc ]] to check if the list is empty.

Example:

Template Object passed Result
[[# products ]]
  - [[ title ]]
[[/ product ]]
-----
[[# tags ]]
  * [[ . ]]
[[/ tags ]]
-----
[[^ prices ]]
  No price yet
[[/ prices ]]
{
  products: [{
    title: 'iPhone'
  }, {
    title: 'LG G5'
  }],
  tags: [
    'Electronics',
    'Phones'
  ],
  prices: []
}
- iPhone
- LG G5
-----
* Electronics
* Phones
-----
No price yet

Helpers

See the dedicated section.