The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub.

This is site is only technical specification for developers.

You'll find comprehensive guides and documentation to help you start working with Clerk.io at our Help Center

Get Started    

Template Language

Clerk.js's markup language is a subset of the Liquid markup language.

Here is a simple example of a template:

<h2>{{ headline }}</h2>
<ul class="clerk-slider">
{% for product in products %}
    <li class="clerk-product">
        <a href="{{ product.url }}">
            <img src="{{ product.image }}" />
            <div class="clerk-product-name">{{ product.name }}</div>
            <div class="clerk-price-wrapper">
            {% if product.is_on_sale %}
                <span class="clerk-old-price"><s>Price {{  product.list_price | money }}</s></span>
                <span class="clerk-new-price">Price {{  product.price | money }}</span>  
            {% else %}
                <div class="clerk-product-price">Price {{  product.price | money }}</div>
            {% endif %}
            </div>
            <div class="clerk-cta-button action primary">Buy Now</div>
       </a>
    </li>
{% endfor %}
</ul>

Everything within {{ and }} is processed by the template engine as a expression, everything with '{%' '%}' is a statement and everything else is used as raw text.

If a variable contains a deeper structure, like a dictionary, it can be accessed by dot syntax like so
`{{ customer.name }}ยด.

If/Else Statements

The Clerk.js template language supports the use of If/Else statements, to only show content based on whether a specific variable exists, has the value True or more advanced expressions such as checking if a price is above a certain limit.

The syntax is:
{%if Expression %}
Do something
{% else %}
Do something else
{% endif %}

An example (remember: The template variables may vary from shop to shop):

<a href="{{ url }}">
  <h2>{{ name }}</h2>
  <img src="{{ image }}" alt="{{ name }}" />
  {% if is_on_sale && in_stock > 0 %}
    <div class="old-price"><s>{{ list_price | money }}</s></div>
    <div class="special-price">{{ price | money }}</div>
  {% else %}
    <div class="price">{{ price | money }}</div> 
  {% endif %}
  <button>Buy Now</button>
</a>

This also works with the handlebar style of opening and closing if sentences.

An example:
{% #if variable_name <= value/variable_name %}
Do something
{% /if %}

Unlike handlebar you cannot open a statement with {{ as they are reserved for expressions.

Iterating over an array

Liquid support iterating over an array of values, with the {% for %} operator.

{% for element in itterable %}
{{ element }}
{% endfor %}

An example:

<a href="{{ url }}">
  <h2>{{ name }}</h2> 
  
  {% if variants %}
  <ul class="product-variants">
    {% for variant in variants %}
      <li>{{ variant.name }}</li>
    {% endfor %}
  </ul>
  {% endif %}
  
  <img src="{{ image }}" alt="{{ name }}" />
  <div class="price">{{ money price }}</div> 
  <button>Buy Now</button>
</a>

This also works with a handlebar style each like so.

{% #each itterable %}
{{ this }}
{% /each %}

Filters

A filter is a function that formats a variable before it is printed.

If you have a formatter filter and a variable variable then the filter is applied to the variable like so {{ variable | filter }}.

Clerk.js comes with these built-in filters:

Formatter
Function

round

Rounds to the nearest integer, like so {{ x | round }}.

pct

Gives you the percentage of two numbers, like so {{ x | pct y }}.

money

Formats a decimal number as currency using the US formatting rules.
Optional: The amount of decimals to be displayed can be altered by adding a number to the function. Usage: {{ price | money 2 }}

money_eu

Formats a decimal number as currency using the EU formatting rules.
Optional: The amount of decimals to be displayed can be altered by adding a number to the function. Usage: {{ price | money_eu 2 }}

nth

Returns a value from a list (x), based on the index given (y), like so {{ x | nth y }}

min

Returns the lowest value from a list

max

Returns the highest value from a list

You can add you own filter functions in the Clerk.js Configuration.
A filter function takes one or more arguments and returns a string or number. Here is an example of our round formatter:

function(x) {
  return Math.round(x).toString();
}