Creating Custom Templates

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.

​

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 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.

​

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.

​

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.

​

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.