Integrations / Shopify

Jan. 09, 2023

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:

Copy
{% 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 Shopify integration uses a library called Hogan.

HTML strings with `html`

In the latest versions of the Algolia integration for Shopify widgets, 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:

Copy

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:

Copy

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:

Copy

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:

Copy

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:

Copy

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:

Copy

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:

Copy

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

Outputs: iPhone (64GB / Gold)

Example 2: Called with:

Copy

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:

Copy

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:

Copy

1
2
3
${algolia.helpers.sizedImage(64x32)}
${algolia.helpers.sizedImage(64x)}
${algolia.helpers.sizedImage(pico)}

Called with:

Copy

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

Outputs:

Copy

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:

Copy

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

Copy

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

Called with:

Copy

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:

Copy

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

Called with:

Copy

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

Outputs:

Copy

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:

Copy

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

Rendering the template:

Copy

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

Called with:

Copy

1
2
3
{
  helpers: algolia.helpers
}

Will output: 2.

Advanced example

Adding the lambda:

Copy

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:

Copy

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

Called with:

Copy

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.

Copy

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.

Copy

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.

Copy

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

Example 1: Called with:

Copy

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:

$90

Example 2: Called with:

Copy

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:

$70 - $110

`instantsearchPrice`

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

Copy

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

Example 1: Called with:

Copy

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:

Copy

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:

Copy

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: $70 - $110

`fullTitle`

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

Copy

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

Called with:

Copy

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:

Copy

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

Outputs: 2

`ceil`

Applies Math.ceil to the number passed as parameter

Template:

Copy

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:

Copy

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

Called with:

Copy

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

Outputs:

Copy

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:

Copy

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

Called with:

Copy

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

Outputs:

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

Custom InstantSearch implementation

Customizing InstantSearch

Did you find this page helpful?

Rendering and templating languages

Liquid

HTML strings with html

Logic helpers

Available helpers

formatNumber

displayPrice

displayStrikedPrice

displayDiscount

instantsearchLink

fullTitle

variantTitleAddition

Image helpers

Hogan

Variables

Conditions

Blocks

Enter an object

Example:

Iterate on a list

Example:

Hogan helpers

Example

Advanced example

Available helpers

formatNumber

formattedPrice

autocompletePrice

instantsearchPrice

fullTitle

fullHTMLTitle

floor

ceil

Image helpers

On this page

HTML strings with `html`

`formatNumber`

`displayPrice`

`displayStrikedPrice`

`displayDiscount`

`instantsearchLink`

`fullTitle`

`variantTitleAddition`

`formatNumber`

`formattedPrice`

`autocompletePrice`

`instantsearchPrice`

`fullTitle`

`fullHTMLTitle`

`floor`

`ceil`