File Structure

The Evance Theme Engine requires a specific file structure. The following illustration highlights the folder/file hierarchy described below:

 

Layouts

Each page of your website is rendered within a layout, which will include your site's header, navigation and footer. Layout files should be placed within the ~/theme/layouts directory. The filename for your default layout file should be index.evml. All templates within your website will automatically use the default layout file, unless set otherwise in your templates.json file. This means that you are able to have different layouts for various sections of your site, including marketing/landing pages. All layouts have access to the Layout EVML Object.

Templates

Templates are rendered within a layout. Your theme should contain a minimum of three template files:

These are the default templates for Categories, CMS Web Pages and Products respectively. Templates are only usable once described within your templates.json config file and Evance does not limit the number of templates you can create. You'll immediately find that you'll want to create several new Page templates. For example templates for your home and contact pages might be named:


CSS & JavaScript Files

Evance automatically includes CSS and JavaScript files into your site based on the following naming convention and order. 

common/js/common.js
common/css/common.css

or

js/common.js
css/common.css

Common Files

If present common CSS and JavaScript files will be included on all pages of your website. You should only choose one of these methods. If you use both only one set will be included into your site. 

NOTE: These are included for the sake of choice. The preferred method of including Common Files is now to use Common Layout Files (below). 

layouts/js/common.js
layouts/css/common.css

Common Layout Files

The common JS and CSS files for layouts are included on all pages of your website if available. 

layouts/js/[layout].js
layouts/css/[layout].css

Specific Layout Files

Evance attempts to load CSS and JS files specific to a layout if available. The name of the JS or CSS file must be the same as the EVML file for the layout. For example a page using the the default index.evml layout will attempt to load both layouts/js/index.js and layouts/css/index.css if available. 

Why is this useful?

Let's say you want to create landing pages on your site specifically for a PPC campaign. The pages can have a different layout and colour set, whilst inheriting all the usual styles from your Common Layout Files.

[controller]/js/common.js
[controller]/css/common.css

Common Controller Files

All templates on your site are based on controllers. Web pages built in the CMS utilise the Page controller, product pages utilise the Product controller, and so on. Common Controller Files are included into pages that use the same controller. For example both page/index.evml and page/home.evml would attempt to load page/css/common.css and page/js/common.js if available. 

Why is this useful?

There are circumstances where sections of your website may require significant amounts of CSS or JavaScript that are only applicable to that controller, such as CSS layouts shared only amongst various information pages on your site. 

[controller]/js/[template].js
[controller]/css/[template].css

Specific Controller Files

These are loaded on all pages using a specific controller and template combination. For example your blog posts might have a unique set of styles not applicable anywhere else on the site and your page/blog-entry.evml will attempt to load both page/css/blog-entry.css and page/js/blog-entry.js files if available. 

Why is this useful?

Templates individually have different styling and different interactive functionality usually requiring their own JavaScript files. 


You should not need to explicitly include CSS or JavaScript files in the HTML head of your layout files unless you require a library on a remote address. 

File extensions should always be in lower case. Files with extensions in upper case may fail to load.

Inventory Files

You may have noticed in the image at the top of this page three files grouped under a common.json Inventory File (generic.css, layout.css and reset.css). Inventory files are used to combine multiple files into a single compressed file. They're also compatible with all of the CSS and JavaScript auto-loading naming conventions above, but instead of a CSS or JS file you create a JSON file instead. This means, for example, instead of creating a css/common.css file you create a css/common.json file. 

Example of an inventory file:


{
    "files": [
		"~/theme/common/css/reset.css",
        "~/theme/common/css/generic.css",
		"~/theme/common/css/layout.css"
	]
}

Why is this useful?

If you've been creating websites for some time, you'll already be familiar with the joy of being able to re-use code. Inventory files give you the opportunity to drop code into your site within their original files and dramatically improves efficiency in maintaining your code. 

Configuration

There are three configuration files required per theme. These are:

config/templates.json

Templates Config

The Templates Config file describes the templates available for use within the CMS for your theme and the various settings that go with them. 

Learn more about this file

config/style.json

Style Config

Describes style variables used within your CSS files that may be adjusted within the Theme Customiser.

Learn more about this file

config/theme.json

Theme Information

This file is used for information purposes and contains information about the theme and its author. 

Learn more about this file


Other Static Files

These include images and fonts used by your theme. There is no specification for the location of these files.