Rendering and Templating Languages

Liquid# Found an issue? Edit this guide A Edit this guide

All the files the Shopify integration installs inside your theme are .liquid templates. The format provides direct access to your Shopify settings and your translations.

To access Liquid variables and helpers, use syntax resembling the following:

1
2
3
4
5
{% if settings.use_logo %}
  {{ 'logo.jpeg' | asset_url | img_tag: shop.name }}
{% else %}
  <span class="no-logo">{{ shop.name }}</span>
{% endif %}

Liquid is only evaluated at page render time because it’s a back-end templating engine. Hence, you can’t use Liquid to render dynamically retrieved objects (for example, results returned by Algolia’s real-time search). To render dynamically retrieved objects, the Shopify integration uses a library called Hogan.

Hogan# Found an issue? Edit this guide A Edit this guide

Hogan.js is a front-end templating library.

Hogan uses the mustache syntax. Since because both Liquid and Hogan use curly braces ({}) as their templating delimiters, the Shopify integration has changed Hogan’s templating delimiters to brackets ([]).

Variables#

Use [[ abc ]] to render a string. Use [[& abc ]] to render a string that contains HTML: for security reasons, be sure you trust the value.

You can access object attributes with the same syntax: [[ attr.abc ]].

Conditions#

Hogan uses the same conditionals as JavaScript:

false, 0, "", null, undefined, [], and NaN resolve to false.

Everything else resolves to true.

Use [[# abc ]]abc is true[[/ abc ]] to check if abc is true. Use [[^ abc ]]abc is false[[/ abc ]] to check if abc is false.

Blocks#

Blocks are composed of an open tag and a close tag. They have the same syntax as true conditionals ([[# abc ]]content[[/ abc ]]) and allow you to do two things: look into objects, and iterate on lists.

Enter an object#

When using a variable name, blocks look inside the object first, and go up the object tree if it doesn’t find it.

Example:#

Template:

1
2
3
4
5
[[# product]]
  [[title]]
  by
  [[storeName]]
[[/ product]]

Called with:

1
2
3
4
5
6
{
  product: {
    title: 'iPhone'
  },
  storeName: 'Apple'
}

Outputs:

iPhone by Apple

Iterate on a list#

You can use blocks to display a list.

• If the list is composed of objects, each object is directly accessible.
• If the list is composed of values, use [[ . ]] to access them.
• As with conditions, you can also use [[^ emptylist ]] content [[/ emptylist ]] to check if the list is empty.

Example:#

Template:

1
2
3
4
5
6
7
8
9
10
11
[[# products ]]
  - [[ title ]]
[[/ product ]]
-----
[[# tags ]]
  * [[ . ]]
[[/ tags ]]
-----
[[^ prices ]]
  No price yet
[[/ prices ]]

Called with:

1
2
3
4
5
6
7
8
9
10
11
12
{
  products: [{
    title: 'iPhone'
  }, {
    title: 'LG G5'
  }],
  tags: [
    'Electronics',
    'Phones'
  ],
  prices: []
}

Outputs:

1
2
3
4
5
6
7
- iPhone
- LG G5
-----
* Electronics
* Phones
-----
No price yet

Hogan helpers#

Helpers are functions to add a bit of logic to your templates.

They’re defined in the assets/algolia_helpers.js.liquid file, and are available in the Hogan templates (for example snippets/algolia_product_autocomplete.hogan.liquid).

The helper functions are Mustache lambdas, so you can call them like a block in your templates:

[[# lambda ]] parameter [[/ lambda]] Your helper functions have one parameter: the text between the lambda tags.

Every Hogan template has access to all the lambdas you write.

Example#

First, define a lambda:

1
2
3
4
5
algolia.helpers = {
  printer: function (text, render) {
    return render(text);
  }
};

Rendering the template:

1
2
3
[[# helpers.printer ]]
  2
[[/ helpers.printer ]]

Called with:

1
2
3
{
  helpers: algolia.helpers
}

Will output: 2.

Advanced example#

Adding the lambda:

1
2
3
4
5
6
7
8
algolia.helpers = {
  image_tag: function (text, render) {
    return '<img ' +
        'src="' + render(text) + '" ' +
        'alt="' + this.default_alt + '" ' +
      '/>';
  }
}

Rendering the template:

1
2
3
[[# helpers.image_tag ]]
  [[ image ]]
[[/ helpers.image_tag ]]

Called with:

1
2
3
4
5
{
  image: 'https://www.google.com/images/srpr/logo11w.jpeg',
  default_alt: 'Image',
  helpers: algolia.helpers
}

Outputs: <img src="https://www.google.com/images/srpr/logo11w.jpeg" alt="Image" />

Available helpers#

formatNumber#

Takes a number as a parameter and returns it formatted in the locale string of the user.

1
2
3
[[# helpers.formatNumber ]]
  2300.43
[[/ helpers.formatNumber ]]

Outputs (depending on your Shopify’s settings):

2,300.43

formattedPrice#

Takes a number as a parameter and returns it formatted with currency.

1
2
3
[[# helpers.formattedPrice ]]
  200
[[/ helpers.formattedPrice ]]

Outputs (depending on your Shopify’s settings):

$200

autocompletePrice#

Prints the price of an Algolia product (this). If the search uses distinct, show the price range instead.

1
2
[[# autocompletePrice ]]
[[/ autocompletePrice ]]

Example 1: Called with:

1
2
3
4
5
6
7
8
{
  price: 90,
  compare_at_price: 100
  price_ratio: 0.9,
  variants_min_price: 70,
  variants_max_price: 110,
  _distinct: false
}

Outputs:

<b>$90</b>

Example 2: Called with:

1
2
3
4
5
6
7
8
{
  price: 90,
  compare_at_price: 100
  price_ratio: 0.9,
  variants_min_price: 70,
  variants_max_price: 110,
  _distinct: true
}

Outputs:

<b>$70 - $110</b>

instantsearchPrice#

Prints the price and its discount of an Algolia product (this). If the search uses distinct, show the price range instead.

1
2
[[# instantsearchPrice ]]
[[/ instantsearchPrice ]]

Example 1: Called with:

1
2
3
4
5
6
7
8
{
  price: 90,
  compare_at_price: 100
  price_ratio: 0.9,
  variants_min_price: 70,
  variants_max_price: 110,
  _distinct: true
}

Outputs:

1
2
3
<b>$90</b>
<span class="ais-hit--price-striked">$100</span>
<span class="ais-hit--price-discount" style="font-weight: 100;">-10%</span>';

Example 2: Called with:

1
2
3
4
5
6
7
8
{
  price: 90,
  compare_at_price: 100
  price_ratio: 0.9,
  variants_min_price: 70,
  variants_max_price: 110,
  _distinct: true
}

Outputs: <b>$70 - $110</b>

fullTitle#

Prints the title with the variant information of an Algolia product (this).

1
2
[[# fullTitle ]]
[[/ fullTitle ]]

Called with:

1
2
3
4
{
  title: 'iPhone',
  variant_title: '64GB / Gold'
}

Outputs: iPhone (64GB / Gold)

Doesn’t print the variant_title if it equals "Default Title" or "Default"

fullHTMLTitle#

Same as fullTitle, but with search highlighting tags included.

floor#

Applies Math.floor to the number passed as parameter

Template:

1
2
3
[[# helpers.floor ]]
  2.43
[[/helpers.floor ]]

Outputs: 2

ceil#

Applies Math.ceil to the number passed as parameter

Template:

1
2
3
[[# helpers.ceil ]]
  2.43
[[/helpers.ceil ]]

Outputs: 3

Image helpers#

Images URLs helper for an Algolia product (this).

You can use the sizedImage helper to specify a size for your image. You can use all the available size options of img_url in liquid. It also works with named sizes.

Template:

1
2
3
4
5
6
7
8
9
[[# sizedImage ]]
  64x32
[[/ sizedImage ]]
[[# sizedImage ]]
  64x
[[/ sizedImage ]]
[[# sizedImage ]]
  pico
[[/ sizedImage ]]

Called with:

1
2
3
{
  image: 'https://i.myshopify.com/abc.jpeg'
}

Outputs:

1
2
3
https://i.myshopify.com/abc_64x32.jpeg
https://i.myshopify.com/abc_64x.jpeg
https://i.myshopify.com/abc_pico.jpeg

For backward compatibility, you can also use named sizes helpers (deprecated by Shopify):

• picoImage
• iconImage
• thumbImage
• smallImage
• compactImage
• mediumImage
• largeImage
• grandeImage
• originalImage

Template:

1
2
[[# picoImage ]]
[[/ picoImage ]]

Called with:

1
2
3
{
  image: 'https://i.myshopify.com/abc.jpeg'
}

Outputs:

https://i.myshopify.com/abc_pico.jpeg