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. 

{
    ...
    "assets": [
        {
            "title": "Header Banner",
            "description": "This page supports one or more banner images at the top of the page.",
            "asset": "slideshow",
            "id": "header_banner"
        }
    ]
}

The "asset" property above references the identifier of an asset, whilst the "id" value becomes a the property name of a page.assets object. In the example above this would become page.assets.header_banner.

Assets are currently only applicable to Page templates.

children

Optional property may be set to any of the following:

  • true (default)
    Page allows users to add child pages.

  • false
    Page should not have child pages. Blog posts for example should not have children.

  • array
    Allow child pages from a list of template identifiers.
    For example a Blog template may have a children settings such as:
    children: ["blog_post"]

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 "~/theme/layouts/index.evml"

parents

Optional property may be set to any of the following:

  • true (default)
    Allow use from any parent.

  • false
    For use at the root level only.

  • array
    May only be a child of pages using specific templates.
    For example, a Blog Post template may only be added to pages using a Blog template:
    parents: ["blog"]

Applicable to the Page templates only.

path

The path to the template file. The path supports Theme Url formats and we recommend using the ~/theme format. Category templates should reside within a category folder.

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:

  1. Defaults to 0 for page controllers to view all. 
  2. Defaults to 25 for category controllers. 
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:

  • sequence:asc (default)
    Show pages in the order represented within Evance's page hierarchy.

  • sequence:desc
    Show pages in reverse order represented within Evance's page hierarchy. 

  • published:asc
    In order of oldest to newest - oldest document first. 

  • published:desc
    In order of newest to oldest - newest document first. 

  • modified:asc
    Show the oldest modified page first. 

  • modified:desc
    Show the most recently modified page first. 

  • title:asc
    Sort alphabetically by page title A-Z. 

  • title:desc
    Sort alphabetically by page title Z-A. 

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:

  • page (default)
    the default document type if none is set.

  • page/blog
    reserved for templates that host blog posts. May also be associated with news.

  • page/blogpost
    reserved for articles posted as a child of pages with a template of type page/blog.

  • page/events
    reserved for event directories/calendars that host events from the courses/events system. Pages with this type of template are modified with functionality/data specific to the Events system.

  • page/event
    reserved for an event posted as a child of pages with a template of type page/events. Pages with this type of template are modified with functionality/data specific to the Events system.

  • page/storelocator
    reserved for pages that require Store Locator functionality. Pages with this type of template are modified with functionality/data specific to the Store Locator system.

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:

  • "" (default)
  • "{{year}}/{{month}}"
  • "{{year}}/{{month}}/{{day}}"

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:


{ 
    ...
    "properties": [
        {
            "title": "Property 1",
            "id": "PROPERTY1",
            "type": "text",
            "value": "VALUE 1 (DEFAULT)"
        }
    ]
    ...
}

...and then the resulting Page setting object:


The setting is {{ page.settings.PROPERTY1 }}
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: 

...
    {
        "label": "Display children?",
        "id": "DISPLAY_CHILDREN",
        "type": "select",
        "options": {
            "Y": "Yes",
            "N": "No"
        },
        "value": "Y"
    }
...
required

Defaults to false. This may only be overwritten for Asset.properties.

  • false (default)
    The setting is not required to have a value.

  • true
    The setting is required to have a value.

required is currently only applicable to Asset properties.

scope

May be one of the following values:

  • page (default)
    The setting is applicable to an individual Page.

  • template
    The setting is applicable to all Pages using this template, including pages already created.

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:

  • color
    Rendered as a colour selection button. Your value property (below) should be a hexadecimal colour reference including the hash prefix.
  • file
    Adds a text field with a browse button allowing you to select any file within the Media Library. See the image type for images.
  • form
    Allows the user to select a Form/Survey to show on the page from a drop-down list of available forms.
    This must be be implemented within the template utilising the <ev:form /> tag. It is preferable to only use the 'form' property type with 'page' templates within settings and not for assets.
  • image
    Rendered as a image preview and browse button, which utilises the Media Library to allow users to select an image.
  • radio
    Rendered as a list of radio buttons where the user may select a single option (see options).
  • select
    Rendered as a select box where the user may select a single option (see options).
  • text (default)
    Rendered as a text field.
  • textarea
    For when a single line of text just isn't enough.
  • url
    Allows the user to enter the URL of an internal page. This will present a searchable drop-down that search pages as the user types.
value

Required String default value for the property. This is  the global default for this property, but may be overwritten within presets.