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 Bespoke documentation here.

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

The properties of the schema are:

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 customisations that a client can make. They provide the properties that are available when creating a campaign. More information is provided in the settings section below.

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. More information is provided in the block section

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

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. A block is only defined once in the schema. When creating a campaign, multiple instances of the same block can be used or they can be a mix of different blocks defined within the template. Some examples of what blocks can achieve:

Images in a slideshow
- The same block multiple times
A 2 column layout, one side text, the other a featured product
- 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. More information is provided in the sub block section below.

settings

The settings attribute defines the customisations that a client can make. They provide the properties that are available in the admin GUI. More information is provided in the settings section

Note: 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. This is shown on the "Add Sub-Block" button when creating a campaign

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. For example, you may have a template containing image and description block types that allows up to 3 blocks but only 1 instance of a description block. This would mean the remaining 2 blocks would need to be the image block type.

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.

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 customisations that a client can make. They provide the properties that are available in the admin GUI. More information is provided in the settings section

Note: 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 customise a template for a specific campaign. Settings are basic types provided by PureClarity, such as colour, select or text. Standard attributes are listed below but certain setting types will have extra attributes

type

The type attribute defines the setting type and consequently the GUI that appears in the admin for it. The GUI for a type may comprise of multiple options. See the Setting Types for more information on available types

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. It contains the following attributes:

Attribute	Description	Required
content_type	Whether this is a "header" or "paragraph"	Yes
content	The content to output as a string value	Yes

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. In addition to standard attributes it contains the following:

Attribute	Description	Required
placeholder	A placeholder value for the input	Yes

range

The range type outputs as a slider field in the GUI. Returns a number when referencing in the template HTML. In addition to standard attributes it contains the following:

Attribute	Description	Required
min	The minimum value of the range	Yes
max	The maximum value of the range	Yes
step	The increment size between steps of the slider	Yes
unit	The unit for the slider. For example, you could set px for font-size.	No

select

The select type outputs as a select field with options in the GUI. Returns a string when referencing in the template HTML. In addition to standard attributes it contains the following:

Attribute	Description	Required
options	An array of objects containing value and label string attributes for each option in the dropdown	Yes

text

The text type outputs as a single line text input field in the GUI. Returns a string when referencing in the template HTML. In addition to standard attributes it contains the following:

Attribute	Description	Required
placeholder	A placeholder value for the input	Yes

textarea

The textarea type outputs as a multi line textarea field in the GUI. Returns a string when referencing in the template HTML. In addition to standard attributes it contains the following:

Attribute	Description	Required
placeholder	A placeholder value for the input	Yes

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. In addition to standard attributes it contains the following:

Attribute	Description	Required
placeholder	A placeholder value for the input	Yes

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. The object contains:

Property	Type	Usage
src	string	The image URL
height	number	Height of the image (automatically determined)
width	number	Width of the image (automatically determined)
aspect_ratio	number	Aspect ratio of the image (automatically determined)
alt_text	string	Optional alt text for the image (if specified by user)

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. The object contains:

Property	Type	Usage
font_family	string	A font to use
font_size	string	Value of the font size (10, 24 etc)
font_size_unit	string	The unit to use for the font size (px, em, rem etc)
font_weight	string	Font weight, using the humanised values (bold, normal, thin etc)
text_transform	string	Option to transform text (Uppercase, lowercase, capitalise etc)
line_height	string	Value of the line height (10, 24 etc)
line_height_unit	string	The unit to use for the line height (px, em, rem etc)
letter_spacing	string	Value of the letter spacing (10, 24 etc)
letter_spacing_unit	string	The unit to use for the letter spacing (px, em, rem etc)

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