Integrations / Shopify

Rendering and templating languages

Liquid

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

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

Did you find this page helpful?