Designing a theme for The Secretary is very straightforward. Themes consist of a CSS file, layout files and templates, which are a mix of HTML and PHP template tags.
The best way to design a theme is to copy the default theme, Aplonis, and begin editing from there.
Themes are created by uploading a folder to the themes folder (../site/themes/). The name of the theme folder should be the same as the theme name, in “simple” form (lowercase letters, dashes instead of spaces). The file tree for a basic theme looks like this:
- css
main.css
- templates
- projects_list.html
-projects_view.html
- layout_projects.php
- layout_default.php
- info.php
A more intricate theme may look like this:
- css
- main.css
- ie
- ie6.css
- js
- actions.js
- img
- logo.jpg
- background.jpg
- templates
- projects_list.html
- projects_view.html
- layout_projects.php
- layout_default.php
- info.php
- plugin.php
Additional files and folders can be created and included in the theme folder - that is entirely up to the designer, and the behaviour of the theme can be totally customised in this way.
Each theme must have a file called info.php which contains information about it that will be displayed on the Themes page in the back-end. It also recommended to create a preview image (470×200) so it looks pretty and informative. Info.php is simply a PHP array:
<?php $info= array( 'name' => 'Aplonis', 'designer' => 'Mikael Stær', 'website' => 'http://www.secretarycms.com', 'date' => 'October 2009', 'about' => 'A stylish theme.', 'preview' => 'aplonis.jpg' ); ?>
Layout files define how the site looks when viewing different kinds of content. Each theme must contain at least two layouts: one for how the site looks when viewing a page, and another for how the site looks when viewing a project. Each additional module, if there are more installed, must have its own layout file. This is done to increase flexibility, as often a layout will change when viewing different types of content.
Layouts are created by writing HTML and the usage of template tags pulls content in from The Secretary and displays it on the page. Layouts can contain HTML, PHP, Javascript - anything that the designer sees fit.
The layout for pages is also the default layout used, when no module-specific content (ie. projects) is being viewed. This file is called layout_default.php.
The layout for projects is defined by the file layout_projects.php.
Layout files reside in the root of the theme folder (ie. /secretary/site/themes/theme-name/).
Templates are used to control the appearance of module-specific content. The Projects module, for example, requires two templates: projects_list.html, which controls how projects are listed on a projects page for example, and projects_view.html which controls how a project should be displayed when being viewed.
Templates, like layouts, are a mix of HTML and PHP. The majority of template tags are meant to be used in templates.
This layer of separation between layouts and templates helps to keep themes organised and easier to manage, and also adds to the overall flexibility and customisability of the front-end.
Each theme is required to have a CSS file named main.css in the css folder of the theme. The system will automatically include it, so there is no need to write a <style> tag to include it.
A smart feature is the ability to automatically include Internet Explorer specific CSS. If your theme requires IE fixes, create a folder named “ie” in the “css” folder and create one or all of the following: ie.css, ie6.css or ie7.css. Conditional tags are generated for you.
Javascript needs to be included manually, and can be done using the requireJs() function or with the help of the themUrl() function.