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    

Pure HTML Integration

We have created 3 different ways to show a clerk content what template to use. To create a slider in clerkjs v2 the root element of the target needs to have the class 'clerk-slider´

Clerk Templates

Front end Templates

A my.clerk.io template annotated by data-template="@my-clerk-io-content-id", is used by creating a Design and a Content within my.clerk.io and then use the embed code given. Note that a my.clerk.io content also includes a limit and an api, so when using a content id you do not need to include these attributes, so it can look like this:

<span
  class="clerk"

  data-template="@my-clerk-io-content-id"
</span>

Inline html

if a content has no data-template attribute it will look for a template within its element. So we can also include a template as such:

<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="16">
  <ul class="product-list clerk-slider">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>

        <img src="{{ product.image }}" title="{{ product.name }}" />

        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
</span>

Selector targeted

If we have multiple contents using the same HTML, and for some reason don't want to use my.clerk.io, then we can create an HTML element with a template inside as such:

<script id="clerk-template" type="text/template">
  <ul class="product-list clerk-slider">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>

        <img src="{{ product.image }}" title="{{ product.name }}" />

        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
</script>

Then our contents would need data-template="#clerk-template" to include the template as such.

<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="16"
  data-template="#clerk-template">
</span>

Example

The core feature of Clerk.js is the ability to embed any Clerk.io result into any website using nothing but HTML!

The easiest way to explain how is just with an example. The following code lists the store's 3 most popular products:

<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">

  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
</span>
<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">
	<!--
  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        <div class="price">{{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
  -->
  <ul class="product-list">
    <li class="product">
      <h2 class="product-name">Product Name #1</h2>
      
      <img src="/product/image/1.jpg" title="Product Name #1" />
      
      <div class="price">$111,11</div>
      <a href="/product/1">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #2</h2>
      
      <img src="/product/image/2.jpg" title="Product Name #2" />
      
      <div class="price">$222,22</div>
      <a href="/product/3">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #3</h2>
      
      <img src="/product/image/3.jpg" title="Product Name #3" />
      
      <div class="price">$333,33</div>
      <a href="/product/3">Buy Now</a>
    </li>
  </ul>
</span>

Thats all there is to it! No code! Easy!

Let's break down how Clerk.js renders this embed code:

  1. All the magic above is initiated by the span element having the class clerk. Immediately after being loaded, Clerk.js will scan the page source for any element with the class clerk.
  2. Then it reads the data- attributes of the element. An attribute can be a special attribute and will thus have the effect described in the list of special attributes below. All other data- attributes will be sent to the Clerk.io API as request parameters.
  3. When the Clerk.io API responds, the resulting products will be rendered using the template in the block body and be injected into the DOM where the block is placed.
  4. In this process, click-tracking is automatically added to each product.
  5. In case of an error, a report will be made to the console with all error details.

Below is the list of special attributes. All other attributes will be sent as request parameters.

Attribute
Behaviour

data-api

The API endpoint to be requested.

data-template

CSS selector for the template to be used (to avoid duplicating templates). If not present, the element body will be used.

If the starting character is @, the template will be loaded from Clerk.io using the remainder of the value as the template id.

data-target

CSS selector for where the products should be rendered. If not present, the products will be added to the DOM where the current element is.

data-limit

The maximal number of elements to return.