Creating Theme

Epesi themes are built on the Smarty template engine. This page explains how theme files are organized, so you know what to copy and edit when you build your own.

Foreword

The essential part of a theme is its .tpl files, which define the HTML structure that holds and organizes page content. Styles usually live separately, in .css files.

All themes live under /data/Base/Theme/templates/. Each subfolder is one theme, and the folder name is the theme's identifier. The easiest way to build your own theme is to start from the default theme: copying it gives you every file the framework uses, and keeps the variables each file relies on already wired up correctly.

Note: the default theme shipped with the current version of Epesi is based on AdminLTE, replacing the older default theme this page's examples were originally written against. The mechanics described below (tpl/css file pairing, theme_dir, the compiled-cache gotcha) should still apply, but check your actual installed theme's folder name rather than assuming it's still called default.

Note: it's good practice to leave the original theme files untouched, and instead copy the files you need into a new folder under /data/Base/Theme/templates/.

If a .tpl file isn't provided by your custom theme, Epesi falls back to the default theme's copy. This also means that to customize just one part of the framework, you only need to copy the files you're actually changing.

Understanding the purpose of each theme file

Before you start building your own theme, it helps to know what each file in a template folder is for.

Every file belongs to one specific module. Its filename has two parts, separated by a double underscore: the first part is the module that uses the file, and the second describes what the file does. If a module uses only one .tpl file, the second part is usually default. For example, Apps_Forum__Boards.tpl belongs to the Apps/Forum module and renders its Boards view.

If it's not obvious what a module or description name refers to, looking at the file's contents is usually enough to figure out its purpose.

Loading CSS

Each .tpl file can have a matching .css file in the same theme folder — this is optional. The .css filename matches the .tpl filename, except for the extension.

Epesi's rule is simple: whenever a .tpl file loads, it looks for a matching .css file in the same theme folder the .tpl file was loaded from. If that file isn't there, nothing further happens. Two examples make this concrete:

  • If you add a new .tpl file to your theme but don't add a matching .css file, no CSS gets loaded for it.
  • If you only want to change the CSS for a module, you still need to copy its .tpl file into your theme folder — without it, Epesi falls back to the default theme's .tpl file, and loads that file's own CSS instead of yours.

In other words, you must supply your own .tpl file for a module before your CSS changes for that module will take effect.

Managing resource files

Besides .tpl and .css files, you can put any other files — mainly images — in your theme directory or its subdirectories. To reference them from a CSS file, use a relative path:

table#Base_Box__logged td.module_name {
    background-image: url("images/button-background-2.png");
    width: 286px;
    height: 20px;
    ...
}

To reference a resource file from a .tpl file, you need the path to your theme directory. Since theme folder names aren't fixed, Epesi provides a special theme variable for this: {$theme_dir}. For example:

<img src="{$theme_dir}/images/logo-small.png">

Using {$theme_dir} instead of a hardcoded path means your theme keeps working even if you rename its folder.

Note: don't rename the default theme's folder — Epesi needs to find it under its expected name, and renaming it can cause serious malfunctions.

Note: renaming the folder of your currently active theme will make Epesi's configuration invalid, and it will fall back to default files for every module.

Development issues

Here are the most common problems you'll hit while developing a theme. If nothing here solves your problem, ask on our forum.

Make sure there's no __cache.css file in your theme folder. Epesi generates this file each time you switch themes, to reduce bandwidth — if it's present while you're editing CSS, delete it, or you won't see your style changes take effect.

If your changes still aren't visible, check the following:

  • Is the theme you're working on actually set as active in Epesi?
  • Have you cleared your browser cache? (Usually necessary to see CSS changes.)
  • Try clearing out /data/Base/Theme/compiled/. This rarely helps, but when it does, it's usually because a .tpl file wasn't picked up.
  • Are you sure you're editing the right file?