How to build a theme
From EFrontWiki
Starting from version 3.6 eFront supports the creation of themes through a standardized and user-friendly process. In this small tutorial I will guide you through the concepts and the tools you need in order to customize the visual appearance for your eFront environment.
Contents |
[edit] Themes infrastructure
You can find eFront themes under the folder <efront>/www/themes. Each directory beneath this folder corresponds to a theme. The main eFront theme is under the special directory default. This is a special theme that you should not modify or remove.
On default directory you can find the following files and subdirectories:
|-templates |-css |-images |-external theme.xml
The only file in the main folder is the special file theme.xml. This includes an xml description of your theme and we will analyze it in detail later. The theme directories are logically separated depending on their content. The templates folder includes the smarty templates for the theme, the css folder includes the css files for the theme and the images folder the theme's images. The external folder is used to keep theme-specific external files. This will be populated from inside eFront and we will not analyze it in this tutorial.
A theme may include only a part of the folders/files on the above structure. Each time we need to access a file that is not present on the active theme, eFront will fetch it from the default theme. This offers opportunities to build partial themes by just altering a few theme ingredients.
For the shake of this example I will create a simple theme and enrich it through an iterative process to offer more functionality.
To do so, I will create a new theme under <efront>/www/themes and copy the themes.xml from the default theme. I will name the new directoy mytheme.
 creating myTheme |
With an editor (I prefer to use notepad++) I will open the themes.xml under mytheme directory to modify its settings. Here is what a theme.xml looks like
<?xml version="1.0" ?>
<!-- This file contains theme properties that affect its display.
All elements are optional, except for the <name> -->
<theme>
<!--The name of the theme, only latin and no special characters. It must match the name of the folder it contains the theme-->
<name>mytheme</name>
<!--The title of the theme, as it displays in the themes list-->
<title>my first theme</title>
<!--The author of the theme, that will be displayed in the themes list-->
<author>Me</author>
<!--The date of the theme good for reference-->
<date>2009/11/12</date>
<!--The version of the theme, displays in the themes list-->
<version>1.0</version>
<!--Put here any additional description for the theme-->
<description>My first theme</description>
<!--The default layout, for the index page only, that the theme will be applied with. It can be overriden from within the environment-->
<layout>
<positions>
<!--layout:simple, left, right, three-->
<layout>three</layout>
<!--columns boxes. Available boxes are: login, online, lessons, news, selectedLessons-->
<leftList>login</leftList>
<leftList>online</leftList>
<centerList>lessons</centerList>
<rightList>news</rightList>
<rightList>selectedLessons</rightList>
</positions>
</layout>
<!--Additional theme properties (that can't be overriden from within the environment)-->
<options>
<!--Whether to hide the index page header.
0 means hide header, 1 means show header on index page, 2 means show header all pages.
The header shows up in inside pages when there is no left sidebar. Defaults to 1-->
<show_header>1</show_header>
<!--Whether to hide the footer throughout the system.
0 means 'hide everywhere'. 1 means 'display everywhere'. 2 means 'display only in inside pages'. Defaults to 1-->
<show_footer>1</show_footer>
<!--Whether to show the left vertical sidebar or the horizontal menu bar.
0 is for left bar (default), 1 is for horizontal menu, 2 is for limited horizontal menu. Defaults to 0-->
<sidebar_interface>0</sidebar_interface>
<!--The width of the left sidebar, in pixels, appearing when logged into the system
(applicable only when "sidebar_interface" is set to 0). It defaults to 175-->
<sidebar_width>175</sidebar_width>
<!--Whether to display images throughout the system.
0 means "all images", 1 means "all images except sidebar images", and 2 means "hide sidebar and block images". Defaults to 0-->
<images_displaying>0</images_displaying>
</options>
</theme>
We need to make sure that the name of the theme folder is exactly the same with the name attribute on theme.xml. Otherwise, when this theme is selected it might crash our eFront installation.
Our new theme have just one file in it - the themes.xml file. When we go to the Themes options inside the Administration area of eFront we can already see and select the new theme. However, since it has no templates or css files it's functionality is actually zero. In practice, eFront will fetch all needed files directly from the default theme when we activate the new theme.
 Selecting myTheme as the active theme |
[edit] Needed tools
Now that we have created a basic theme lets proceed to modify it. We will need Firebug (http://www.getfirebug.com) and Web-Developer (https://addons.mozilla.org/en-US/firefox/addon/60) two FireFox plugins that can be used to inspect the page elements. They will help us determine the exact CSS elements that we need to change and their position inside the CSS. For the rest of this tutorial I will assume that you have downloaded and installed them.
[edit] Changing the theme's CSS
To make our theme a bit exciting we will alter its CSS. I start by copying the CSS folder and the images folder from the default theme and then I open the css_global.css using notepad++.
 The final structure for myThemes folder |
Check the following series of images for a brief visual guide to how to modify your css. Note that all the changes with Firebug are lost when you reload the page. You have to copy the changes to the notepad++ window to save them permanently.
 Disable cache from the web developer menu |
 Spot the firebug option to inspect the page css |
 Go to a form element |
 You should see the related input elements CSS |
 Modify an element to preview its effect |
 The html page changes accordingly to your CSS changes |
 The final border and input fields |
 The final first page |
[edit] Changing theme's images
eFront uses CSS sprites to load images. This technique speeds up the process of loading pages since all images are fetched through a minimum number of requests. For more info on CSS sprites check: http://www.alistapart.com/articles/sprites
In this section I will show you how to modify images and how to create your own sprites using a simple web-service.
eFront uses 2 main types of images - one set of small 16x16 images and one set of bigger 32x32 images. It also uses a few other images (background images etc). All 16x16 and 32x32 images are bundled together into two sprites named 16x16map.png and 32x32map.png.
In order to change the sprite images you need to alter the initial set of images that can be found only on the default theme under the folder <themes>/default/images/16x16 and <themes>/default/images/32x32 respectively. You may copy these folders to another place for the replace process.
When you are done with replacing images you need to create a zip with all the images on each folder. We will use the service at: http://spritegen.website-performance.org/ to create the final sprite.
On the sprites generator web site you need to do the following:
- Upload the zipped file.
- Check the compress option to minimize the final image size
- On class-prefix use sprite32- or sprite16- (depending on the type of images)
 Sprites processing parameters |
 The results of the images processing |
The final result of the process will be a sprite image and several css rules as text. You need to replace the 32x32map.png (or 16x16map.png) of your theme with this file and at the same time replace the sprite rules part on css_global.css with the css rules on this page. Just clear your cache and reload an efront page to see if it works :)
 A slightly modified sprite images (modified maintenance icon) |
[edit] Changing theme's templates
Generally speaking, you can do almost anything through CSS and Sprites . However, eFront allows you to modify core system templates directly and make these changes part of a theme.
This is great power however you need to make sure you absolutely need to modify a template. Modified templates may corrupt your installation if done poorly and are usually not upgradable to newer eFront editions. On the other hand by modifying templates you can achieve anything visually even the most fancy interface.
In this part of the tutorial I will show you how you can modify the template that corresponds to the system's header.
I create the folder <themes>/mytheme/templates/includes and I copy in it the file header_code.tpl from the default theme. I can open the copied file now with notepad++ and change its structure (all eFront templates are based on Smarty). For example in our case I will just comment a few lines on top of it that are responsible for showing the system's logo:
<!--<div id = "logo">
<a href = "index.php">
<img src = "{$T_LOGO}" title = "{$T_CONFIGURATION.site_name}" alt = "{$T_CONFIGURATION.site_name}" border = "0"></a>
</div>-->
Just save and reload eFront's first page - bye-bye logo!
 A modified theme without a logo |
[edit] Distributed themes using Amazon S3
[Work in progress...]
