> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pureclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Custom Templates
> Comprehensive guide to building custom templates using Handlebars templating engine, schemas, blocks, and advanced configuration options
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](https://handlebarsjs.com/guide/). PureClarity templates can use the [built-in helpers](https://handlebarsjs.com/guide/builtin-helpers.html#if), as well as helpers provided by [Just Handlebars](https://github.com/leapfrogtechnology/just-handlebars-helpers).
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](https://pureclarity.stoplight.io/docs/bespoke-docs/c2NoOjE4MjI0NzE-product-recommender-model).
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](mailto: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.
| **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.
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.