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):
picoImageiconImagethumbImagesmallImagecompactImagemediumImagelargeImagegrandeImageoriginalImage
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
