Rendering and templating languages
Liquid
All files installed by the Algolia Search and Discovery app 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 backend 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 Algolia Search and Discovery app uses a library called Hogan.
HTML strings with html
In the latest versions of the widgets included in the Algolia Search and Discovery app, Hogan.js templates are replaced with function-form templates using the html
function. For more information, see Using HTML strings with html
for InstantSearch.js templates and Returning HTML for Autocomplete templates.
For details on how to customize the widget’s UI with the html
function, see each widget’s reference page. For example, the Hits widget templates).
Logic helpers
Helpers are functions that add logic to your templates.
They’re defined in the assets/algolia_helpers.js.liquid
file, and are available in all the templates (for example snippets/algolia_autocomplete_product.liquid
).
The helper functions are JavaScript functions that are stored in the algolia.helpers
object. You can insert them in your templates using string interpolation:
${algolia.helpers.functionName(parameter)}
Your helper functions can take one or many parameters.
Available helpers
formatNumber
Takes a number as a parameter and returns it formatted in the locale string of the user.
${algolia.helpers.formatNumber(2300.43)}
Outputs (depending on your Shopify’s settings):
2,300.43
displayPrice
Outputs the price formatted with currency of an Algolia product. If the search uses distinct, show the price range instead.
${algolia.helpers.displayPrice(item, distinct)}
Example 1: Called with:
1
2
3
4
5
6
{
item.price: 90,
item.variants_min_price: 70,
item.variants_max_price: 110,
distinct: false
}
Outputs:
$90
Example 2: Called with:
1
2
3
4
5
6
{
item.price: 90,
item.variants_min_price: 70,
item.variants_max_price: 110,
distinct: true
}
Outputs:
$70 - $110
displayStrikedPrice
Outputs the price formatted with currency of an Algolia product to be crossed out.
${algolia.helpers.displayStrikedPrice(price, compare_at_price)}
Example: Called with:
1
2
3
4
{
price: 90,
compare_at_price: 100
}
Outputs:
$100
displayDiscount
Outputs the discount of an Algolia product.
${algolia.helpers.displayDiscount(price, compare_at_price, price_ratio)}
Example: Called with:
1
2
3
4
5
{
price: 90,
compare_at_price: 100,
price_ratio: 0.9
}
Outputs:
-10%
instantsearchLink
Returns the URL link of an Algolia product. If the search doesn’t use distinct, add the variant information to the link.
${algolia.helpers.instantsearchLink(hit)}
Example 1: Called with:
1
2
3
4
5
6
{
hit._distinct: false,
hit.objectID: 43210820649188,
hit.id: 7741800808676,
hit.handle: "4732719"
}
Outputs:
"/products/4732719?variant=43210820649188"
Example 2: Called with:
1
2
3
4
5
6
{
hit._distinct: true,
hit.objectID: 43210820649188,
hit.id: 7741800808676,
hit.handle: "4732719"
}
Outputs:
"/products/4732719"
fullTitle
Prints the title of an Algolia product. If the search doesn’t use distinct, prints the title with the variant information.
${algolia.helpers.fullTitle(title, _distinct, variant_title)}
Example 1: Called with:
1
2
3
4
5
{
_distinct: false,
title: 'iPhone',
variant_title: '64GB / Gold'
}
Outputs:
iPhone (64GB / Gold)
Example 2: Called with:
1
2
3
4
5
{
_distinct: true,
title: 'iPhone',
variant_title: '64GB / Gold'
}
Outputs:
iPhone
Doesn’t print the variant_title
if it equals "Default Title"
or "Default"
variantTitleAddition
Prints the variant title of an Algolia product.
${algolia.helpers.variantTitleAddition (item, distinct)}
Example 1: Called with:
1
2
3
4
{
distinct: false,
item.variant_title: '64GB / Gold'
}
Outputs:
(64GB / Gold)
Image helpers
Images URLs helper for an Algolia product.
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
${algolia.helpers.sizedImage(64x32)}
${algolia.helpers.sizedImage(64x)}
${algolia.helpers.sizedImage(pico)}
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:
${algolia.helpers.picoImage(item)}
Called with:
1
2
3
{
image: 'https://i.myshopify.com/abc.jpeg'
}
Outputs:
https://i.myshopify.com/abc_pico.jpeg
Hogan
Hogan.js is a frontend templating library.
Hogan uses the mustache syntax. Since because both Liquid and Hogan use curly braces ({}
) as their templating delimiters, the Algolia Search and Discovery app 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 let you 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