Skip to main content
Templates consist of 2 parts: the HTML template (written in Handlebars) and the schema that defines the properties of a template (what you can configure when you create a campaign).

​
Handlebars

A good introduction to creating templates is to read up on Handlebars. PureClarity templates can use the built-in helpers, as well as helpers provided by Just Handlebars. The model that gets used when the template is rendered depends on what the campaign is showing. If it is a recommender, then the properties you can use are defined in our Custom documentation.
You will almost always start with a template created by PureClarity, and then adapt it to suit the styling and functionality on your site. You can also start a new template from scratch if that’s preferred.
We are always available to help - drop us a message at support@pureclarity.com and we will help you create your template.

​
Schema

The schema defines the properties you can set in the campaign. Each template must have a schema, and is defined between the {{#schema}} and {{/schema}} parts of the template - usually at the end.
The best way to learn about how to create a schema is to create a new template and base it on one of our default templates. You can then look to see how we have set it up.
The schema is a JSON object, and is composed of 4 key components: the schema, blocks, sub_blocks and settings.

​
Schema Properties

​
id

The id attribute determines the title shown in the admin when selecting the template.

​
name

The name attribute determines the title shown in the admin when selecting the template.

​
description

The description attribute determines the description shown in the admin when selecting the template.

​
preview_image_url

The preview_image_url attribute determines the preview image shown in the admin when selecting the template. This helps users to visually see what your template will look like.

​
type

The type attribute determines whether the template is for content or recommendations. This affects which part of the template picker the template appears in.
  • content - The template will be used for content (not recommendations)
  • recommender - The template can only be used to show recommendations

​
settings

The settings attribute defines the customizations that a client can make. They provide the properties that are available when creating a campaign.

​
Blocks

The blocks attribute defines an array of block, reusable content available in a template. Blocks are reusable modules of content within a template that can be added, removed, and reordered when creating a campaign.

​
Block Configuration

​
max_blocks (optional)

The max_blocks attribute defines the maximum number of blocks that can be added when creating a campaign with the template. This is shown on the “Add Block” button when creating a campaign.

​
min_blocks (optional)

The min_blocks attribute defines the minimum number of blocks that must be added when creating a campaign with the template.

​
default (optional)

The default attribute defines default values that will be displayed when creating a campaign from a template. This is an array of block types, such as ["image", "description", "button"].

​
Block Properties

Blocks are reusable modules of content within a template that can be added, removed, and reordered when creating a campaign. A block represents the contents and settings of a single block in an array of schema blocks. Examples of what blocks can achieve:
  • Images in a slideshow: The same block multiple times
  • A 2 column layout: Two different blocks, each taking up 50% of the space

​
type

The type attribute is a user defined value, useful when looping over blocks in the template to specify different HTML for the different blocks.

​
name

The name attribute determines the title shown in the admin when selecting the block type.

​
sub_blocks

The sub_blocks attribute defines an array of sub_block. Sub-blocks are reusable modules of content within a block within a template that can be added, removed, and reordered when creating a block.

​
settings

The settings attribute defines the customizations that a client can make. They provide the properties that are available in the admin GUI.
All settings at the block level must have a unique ID within that particular block. Having duplicates will result in an error.

​
max_blocks (optional)

The max_blocks attribute on a block defines the maximum number of sub-blocks that can be added when creating a campaign with the template.

​
min_blocks (optional)

The min_blocks attribute on a block defines the minimum number of sub-blocks that must be added to the block when creating a campaign with the template.

​
max_instances (optional)

The max_instances attribute defines the maximum number of this type of block that can be added when creating a campaign with the template. This is distinct from the top level max_blocks as it applies only to this specific block.

​
min_instances (optional)

The min_instances attribute defines the minimum number of this type of block that must be added when creating a campaign with the template.

​
Sub Blocks

Sub-blocks are reusable modules of content within the block HTML that provide an extra layer of flexibility. An example of this would be a block that holds a list of links. Each link would be represented by a sub block that could contain a setting for the link text and a setting for the link URL.

​
Sub Block Properties

​
type

The type attribute is a user defined value, useful when looping over sub blocks in the template to specify different HTML.

​
name

The name attribute determines the title shown in the admin when selecting the sub block type.

​
settings

The settings attribute defines the customizations that a client can make. They provide the properties that are available in the admin GUI.
All settings at the sub block level must have a unique ID within that particular sub block. Having duplicates will result in an error.

​
max_instances (optional)

The max_instances attribute defines the maximum number of this type of sub block that can be added when creating a block within the campaign with the template.

​
min_instances (optional)

The min_instances attribute defines the minimum number of this type of sub block that must be added when creating a block within the campaign with the template.

​
Settings

Settings are the way in which clients can customize a template for a specific campaign. Settings are basic types provided by PureClarity, such as colour, select or text.

​
Standard Setting Attributes

​
type

The type attribute defines the setting type and consequently the GUI that appears in the admin for it.

​
id

The id attribute defines the ID used to reference the setting in the template HTML. It must be unique within its current scope.
All the settings in a particular block must have a unique ID, but two different blocks in the same template can have the same setting ID. All the settings at the level of the schema must have a unique ID, but as blocks are in a different scope, they can have a setting with the same ID as a schema level setting.

​
name

The name attribute defines the label shown for the setting in the GUI.

​
description (optional)

The description attribute defines informational text for the setting in the GUI.

​
default (optional)

The default attribute defines the default value for the setting in the GUI.

​
Setting Types

This lists the available types provided by PureClarity to use for settings.

​
info

The info type outputs as either a header or paragraph in the GUI and is purely informational. Useful for grouping several settings or providing more detailed information.

​
checkbox

The checkbox type outputs as a checkbox field in the GUI. Useful for toggling features on and off. Returns a boolean when referencing in the template HTML.

​
number

The number type outputs as a number input field in the GUI.

​
range

The range type outputs as a slider field in the GUI. Returns a number when referencing in the template HTML.

​
select

The select type outputs as a select field with options in the GUI. Returns a string when referencing in the template HTML.

​
text

The text type outputs as a single line text input field in the GUI. Returns a string when referencing in the template HTML.

​
textarea

The textarea type outputs as a multi line textarea field in the GUI. Returns a string when referencing in the template HTML.

​
colour

The colour type outputs as a dropdown in the GUI. Theme colours can be selected, and if a value of “Custom” is selected, a colour picker is presented to the user. Returns a string when referencing in the template HTML.

​
category_picker

The category_picker type outputs as a category picker in the GUI, allowing you to select a category from the information uploaded to PureClarity in the Category feed. Returns a category object when referencing in the template HTML.

​
product_picker

The product_picker type outputs as a product picker in the GUI, allowing you to select a product from the information uploaded to PureClarity in the Product feed. Returns a product object when referencing in the template HTML.

​
html

The html type outputs as a multi-line textarea in the GUI, allowing you to enter HTML markup. Returns a string when referencing in the template HTML.

​
image_picker

The image_picker type outputs as an image picker in the GUI, allowing you to select an image that has been uploaded to PureClarity, or an external URL. Also allows the alt text to be specified. Returns an object when referencing in the template HTML.

​
font

The font type outputs as a selection of font related options in the GUI, such as font family to use, font size and font size unit options, line height etc. Returns an object when referencing in the template HTML.

​
rich_text

The rich_text type outputs as a multi-line text area with text formatting options in the GUI, allowing you to enter formatted text content. Returns a string when referencing in the template HTML.

​
url

The url type outputs as a single line input field in the GUI, allowing you to enter a URL. Returns a string when referencing in the template HTML.

​
video_url

The video_url type outputs as a single line input field in the GUI, allowing you to enter a URL or ID of a YouTube or Vimeo video. Returns a full URL string when referencing in the template HTML.
Start with existing PureClarity templates as a foundation, then customize them to match your site’s styling and functionality requirements. This approach saves time and ensures you follow best practices.