config/templates.json
This file is how you tell Evance about your theme and its templates. Whilst a minimum schema must be met, you're free to extend your theme with any number of page, category and product templates.
File format
Your file must be a valid JSON format and follow the following structure:
{
"page": {
"index": {
"title": "Default",
"path": "~/theme/page/index.evml"
}
},
"category": {
"index": {
"title": "Default",
"path": "~/theme/category/index.evml"
}
},
"product": {
"index": {
"title": "Default",
"path": "~/theme/product/index.evml"
}
},
"assets": {}
}
Adding additional templates
You'll instantly want to add additional templates, particularly for the page controller. Let's say you want to add a template for your website's homepage.
{
"page": {
"index": {
"title": "Default",
"path": "~/theme/page/index.evml"
},
"home": {
"title": "Homepage",
"path": "~/theme/page/home.evml"
}
},
...
}
As you can see we have added a new "home" property to the page controller. The "home" property name itself is used by Evance to identify the template and must therefore adhere to the following rules when creating a new identifier:
- Identifiers should be in lowercase.
- Less than 40 characters long.
- May only contain characters a-z, numbers and underscores.
- Avoid using dashes (-) in your identifier names.
- Should not start with a number.
- Must be unique to the parent controller property.
Page, category and product controllers must have at least an "index" property. The "index" property represents the default template should Evance encounter an unknown. Most themes have only one category/product template but the ability to specify more than one template can be useful for stores wishing to have different layouts or styles per department for example.
Template Format
The following describes the available format for Page, Product and Category templates. However, some of the properties below are not applicable to all templates and most of the properties below are optional - you only need to declare them if different from their default values.
assets
Optional Array. Each element of the Array should contain an Object that describes the asset required. Note that the object does not describe the asset properties, this can be found in the Asset Properties below.
The Assets are currently only applicable to Page templates. |
children
Optional property may be set to any of the following:
Applicable to the Page templates only. |
description
An optional string describing the template and its use. |
layout
Optional layout property allows you to change the layout used by a template. By default the value of the
layout property is set to " |
parents
Optional property may be set to any of the following:
Applicable to the Page templates only. |
path
The path to the template file. The path supports Theme Url formats and
we recommend using the |
perpage
Applicable to Category and Page templates, but is not used by Product templates. Defines how many pages or products to display per page on a page or category respectively. Oddly there are two defaults to this property subject to the controller:
|
properties
Currently only applicable to Page templates. An Array of properties available to the user for either for all pages using the template or individual pages. See Page.properties Format below. |
sort
Defines the sort order of child pages. Note that this is not applicable to Category templates since sort is defined from within the Evance user interface per Category. The sort property is a string and may be any of the following values:
|
tags
Applicable to Page templates only. Optional array containing the references of tags available to the Page. This property allows you to have different tags, or categorisations of Blog Posts for example. |
thumbnail
Optional path to a thumbnail image used to represent the template. This is applicable to Page, Category and Product templates. Custom thumbnail images should be included within your theme and should not be a remote image. |
title
The title displayed to the user within Evance. Your "index" category object should have a title of Default. |
type
The type of document may be one of the following:
|
url
Defines the URL format for a Page template. This property is only applicable to Page templates. The URL format may be any of the following:
This property modifies the URL of your pages. The URL modifier is usually only found in pages using a Blog Post template. The year, month and day placeholders above are replaced with the relevant data from the publish date. |
Assets
Page templates support Assets. This allows you to define any number of repeatable configurations for a page. Defining assets is very similar to how Page properties are defined. Assets are not yet available for Category or Product templates.
One of the more common assets is the ability to offer a slideshow and we're using a common configuration as an example below:
{
...
"assets": {
"slideshow": {
"title": "Slideshow",
"description": "A slideshow consists of one or more images.",
"properties": [
{
"title": "Image",
"description": "Description or helpful information about image size",
"id": "image",
"type": "image"
},
{
"label": "Link (optional)",
"id": "url",
"type": "url",
"required": false
}
]
}
}
}
Note that the property name (e.g. slideshow above) is used as the identifier for the asset type.
description
Optional description of the asset type. This is currently for your own reference as it is not currently used within the Evance UI. However this may change in future. |
properties
The properties of each asset follow the same format as Page.properties (see Asset.properties Format below). |
title
The title for your Asset type. |
Page.properties & Asset.properties Format
The following properties are currently only applicable to Page templates.
description
Optional string describes the setting to users within Evance. |
id
Required identifier for your property. The best way to visualise this is with an excerpt:
...and then the resulting Page setting object:
|
label
Required string the describes the setting field within Evance. |
options
An Object containing key value pairs of options for the setting. Required for select and radio field types. The value of each property will be displayed to the user for selection, for example:
|
required
Defaults to false. This may only be overwritten for Asset.properties.
required is currently only applicable to Asset properties. |
scope
May be one of the following values:
Scope is currently only applicable to Page templates. |
title
Optional heading, sometimes helpful for heading a section of settings. |
type
Settings may have one of the following types:
|
value
Required String default value for the property. This is the global default for this property, but may be overwritten within presets. |