Core themes
Themes are responsible for the final presentation of markup to a user, excluding those scenarios where you want a module to send raw JSON / XML (e.g. it is an API).
Themes are structured around some key concepts:
- Themes should be self-contained and self-describing.
- Themes will be based around layouts, with a default layout that can be copied by other layouts.
- Layouts are made up of sections, where each section can include pre-rendered blocks (from modules), or retrieve content directly from the CMS for display.
Themes must be structured as follows:
theme.json :: the theme configuration file
/templates :: the folder that contains template sections described in the theme configuration
Within the templates folder, files need to be placed based on the following convention based on the layout names specified in the theme configuration file, so lets visit that first.
The theme.json file is the core configuration file that describes the theme and controls the way the theme renders output. The theme.json file for cleanslate (the current default) is:
{
"name": "cleanslate",
"type": "full",
"description": "Not intended to be used directly, but as a starting point for other themes",
"version": "0.2.1",
"author": "Dennis Hall <dennishall@github.com>",
"layouts": {
"default": {
"layout": {
"template": "default.html",
"sections": {
"scripts": {"template": "scripts.html"},
"styles": {"template": "styles.html"},
"admin": {"menu": "admin", "template": "adminMenu.html"},
"primary": {"menu": "primary", "template": "primaryMenu.html"},
"secondary": {"template": "secondaryMenu.html"},
"messages": {"template": "messages.html"},
"body": {"template": "body.html"},
"sidePanel": {"template": "sidePanel.html"},
"footer": {"template": "footer.html"}
}
}
},
"home": {
"layout": {
"copyFrom": "default",
"sections": {
"body": {"template": "body.html"}
}
}
},
"blogLanding": {
"layout": {
"copyFrom": "default",
"sections": {
"body": {"template": "body.html"}
}
}
},
"admin": {
"layout": {
"template": "admin.html",
"sections": {
"scripts": {"template": "scripts.html"},
"styles": {"template": "styles.html"},
"admin": {"menu": "admin", "template": "adminMenu.html"},
"primary": {"menu": "primary", "template": "primaryMenu.html"},
"secondary": {"template": "secondaryMenu.html"},
"messages": {"template": "messages.html"},
"body": {"template": "body.html"},
"footer": {"template": "footer.html"}
}
}
},
"preview": {
"layout": {
"template": "preview.html",
"sections": {
"scripts": {"template": "scripts.html"},
"styles": {"template": "styles.html"},
"body": {"template": "body.html"}
}
}
}
}
}
This file has some key sections:
- Theme properties:
- Name: Name of the theme (required)
- Type: Type of theme (full, frontend, admin) (required)
- Description: Optional - describe the theme.
- Version: Version
- Author: Your name :)
- Layouts
- Default: This is the default layout, is required as it is the fallback if no specific layout is specified.
- Other layouts: Other layouts defined here.
So layouts are really important, and best to think of a layout as a definition of a complete page, with all of it's sections. Lets walk through default first so you understand what is in it:
"default": {
"layout": {
"template": "default.html",
"sections": {
"scripts": {"template": "scripts.html"},
"styles": {"template": "styles.html"},
"admin": {"menu": "admin", "template": "adminMenu.html"},
"primary": {"menu": "primary", "template": "primaryMenu.html"},
"secondary": {"template": "secondaryMenu.html"},
"messages": {"template": "messages.html"},
"body": {"template": "body.html"},
"sidePanel": {"template": "sidePanel.html"},
"footer": {"template": "footer.html"}
}
}
}
Valid children of a layout are:
The layout itself can contain the following properties:
This is the template file to be used to render the output, where the base path is relative to the theme/templates folder:
"template": "default.html" >> theme/templates/default.html
Examples:
- Layout template
The sections describe the various parts of the layout that will be rendered separately and then included in the overall site layout, these are all relative now to the theme/templates/ folder within the theme:
"scripts": {"template": "scripts.html"} >> theme/templates/default/scripts.html
Additionally, a section template can include a 'backing file' that can be processed prior to the template being executed to allow the section template to do more pre-processing prior to rendering. This file must have exactly the same name, but be a javascript file.
theme/templates/default/scripts.html
theme/templates/default/scripts.js
Templates are automatically exposed to all of the helpers exposed via the Helpers, though it is very important to note that you cannot use the asynchronous helpers directly within the template file.
If you want to use an asynchronous helper you must put it in the backing file and use step to control execution, returning the results to the template once all are completed. Dealing with asynchronous functions is the primary purpose of the template backing file.
Examples:
- Section template
- Section backing file
Setting the copyFrom property allows a layout to copy all of its sections from another layout, and then over-ride the ones it wants to change. Given that most pages share common sections (header, footer, sidebar) it doesn't make any sense to duplicate these elements, hence the most common setting for this is:
"copyFrom":"default"
modules : allows over-ride of module templates from the theme (only valid against the default layout).
An example of this in the calipso-site-theme (on cliftonc/calipso-site-theme), it has an extra section in the default layout:
"modules":{
"user":{
"login":"modules/user/login.html"
},
"elastic":{
"results":"modules/elastic/results.html"
}
This allows the theme to over-ride the default module template, so the module now uses the specified file when rendering it's own results. This avoids you needing to bypass the module completely (as some of the other landing page layouts do in the calipso site theme).
The folder path provided is relative to the base theme folder, so the examples above would map to:
"modules/user/login.html" >> theme/modules/user/login.html
"modules/elastic/results.html" >> theme/modules/elastic/results.html