Block: Clerk

The Clerk block allows you to place a Clerk element — for example, product recommendations, a content banner, or a campaign list — wherever you want in the design. You paste the embedded code from your Clerk account, and the block displays the element on the pages where it is located.

Before you start

The block is only displayed if the Clerk.io extension is active in the store. If it is not, the Clerk block will not appear in the list of blocks in the Design Builder.

You activate Clerk under Extensions > Your extensions, by turning on Activate Clerk.io. You also need a Clerk account with public and private keys entered, and the product feed must be connected to Clerk.

In short: without an active Clerk extension, this block is invisible, and even if you add it, it will not display anything until the Clerk element is set up in the Clerk account.

What the block does

The block is a container for Clerk's own code. It has no ready-made display itself — it is Clerk that determines what is actually displayed (recommendations, search, banners, etc.) based on the element you connect.

How to add the block

The Clerk block is added like all other blocks in the Design Builder: open the section you want it in, add a new block, and select Clerk from the block list. Then paste the code from Clerk into the content field (see next section).

You can have multiple Clerk blocks on the same page — for example, one with recommendations at the top and another further down.

The block is available in these sections:

• Product lists
• Shopping cart
• Blog pages

Inserting the embedded code from Clerk

The element itself — its appearance, which products are displayed, and the underlying logic — is set up within Clerk. What you retrieve from there is a short code snippet that you paste into the block.

How to retrieve the code in Clerk (also see Clerk's own guide at help.clerk.io):

• Log in to Clerk and go to Recommendations in the menu.
• Select Element, and open the element you want to use — or create a new one.
• Click Edit ElementUnder
• Insert into website, select Using embedded codeCopy the code snippet.

The code from Clerk is often an empty <span> tag. There must be at least one character between <span ...> and </span> — otherwise, the store will remove the entire code when you save, and the block will be empty. For example, type a period or a space between the tags. Clerk overwrites this character with the element itself when the page loads, so it is never visible to the customer.

The code typically looks like this after you've inserted a character (here, a period):

<span class="clerk"
  data-template="@home-page-popular">.</span>

Paste this into the Clerk block's content field in the Design Builder, and save.

For more info about setup at Clerk, see a separate article:

Placeholders for product, category, and shopping cart ID

Some Clerk elements need to know which page the customer is on — for example, «show similar products to this product» or «others also bought» in the shopping cart. In such cases, the Clerk code must contain the correct ID.

You should not enter a number yourself. Paste the placeholder exactly as it appears, and the integration will automatically replace it with the correct ID in the store when the page is displayed. Use the placeholders below within the code:

Example of a code that recommends similar products on a product page:

<span class="clerk"
  data-template="@product-page-alternatives"
  data-products="[{{ product.id }}]">.</span>

You leave {{ product.id }} in the code. When the customer is on a product with ID 1234, the store automatically sends data-products="[1234]" to Clerk.

Tip

• Check that the correct placeholder matches the page. {{ product.id }} is only filled in on product pages — if you place it in a block on the front page, it will remain empty.
• The name after data-template (for example, @product-page-alternatives) must exactly match the name of the element in Clerk. A typo here will result in an empty field without an error message.
• If you want to test if the block works, open the page in your browser and look for the Clerk content. If nothing is displayed, the error is most often in the Clerk setup, not in the block.

Common pitfalls

• The block is missing from the list. The Clerk extension is not active. Activate it under Extensions first.
• The entire code disappeared when you saved.<span>-tag was empty. Place a character (a period or space) between <span ...> and </span>, and the code will remain.The block is empty on the website.
• Most common reasons: the element is not fully set up in Clerk, the code snippet is pasted incorrectly, or data-template-name does not match Clerk.Recommendations that require an ID do not work.
• Check that you have used the correct placeholder ("{{ product.id }}{{ category.id }} etc.) and that the block is on the page type the placeholder applies to.The results look incorrect. The quality of what Clerk displays depends on the product feed and the setup in the Clerk account. If the products or their order look incorrect, check the feed and the element in Clerk — not the block.