Knowledgebase

How does the Skin System work ?

Introduction
==========
The skin system of Hivemail can be accessed under "Skins & Templates" in the administrator section. You need to go there in order to make any layout changes. There are no files to edit in the filesystem.

Note: for the Default skin we have used special techniques like css sprites in order to reduce the server calls the browser needs to make while parsing the html source: certain images are included through background container image files and positioned via CSS.

A Hivemail skin basically consists of 2 parts / aspects:
- The skin definition (skin variables (text, font and color settings) and the template set being used by a skin) -> menu "Skins Manager"
- A template set containing templates -> menus "Template Sets" & "Templates Manager"

Note: templates are to be edited via menu "Templates Manager". Menu "Template Sets" lets you create, delete or rename template sets.

And there's another aspect of importance: your users can choose between the different skins you have made available for them. It's by changing the skin that the outlook of the application is changed (menu "Preferences" -> "General Options").

Note: You may not want to grant your users access to every skin you have. As admin you can define which usergroups have access to what skins (see "Usergroup Manager").

Skins Manager
============
Each skin has a set of skin variables you can change. These variables control text colors, font face, table borders and other options. You can also make use of custom skin variables.

Each skin also defines a set of templates that is used to display content.
This way, two or more skins can use the same template set, but different skin variables. All skins using a particular template set would have the same basic look, but colors, fonts, etc. could be different per skin.

This menu lets you control both the skin variables and the template set being used by a particular skin.

Note1 : if you want your users to be able to choose from different font sizes or types you would simply create a couple of new skins (and name them accordingly) and adapt the variables in the skin's "Text and Fonts" section. You don't need to create new template sets, you can use the same set (eg. Default) for all skins.

Note 2: skin variables are actually used in the templates. If you open up css_main via "Templates Manager" you're going to spot a lot of $skin[xyz] elements, which are in fact the variables you have defined in "Skins Manager".

Template Sets
============
A template set is a set of templates that can be used by a particular Skin. Every set has its own templates, so you can have more than one set and edit each one individually without causing any collision with the others.

Each template set you have can be used for one or more skins. To change the template set a skin uses goto "Skins Manager" and edit the appropriate skin.

This menu allows you to create new template sets based upon copies from already existing sets. When you are making vast changes to the site's templates, it's recommended that you create another template set and work on it. It's also a good practice to not change the default template set. First create a new one based upon a copy of the default one, link it with a new skin and start working on it via "Templates Manager".

Templates Manager
=================
Templates are the skeleton, so to speak, of the program and are grouped into template sets. A skin makes use of a particular template set and a template set contains the templates. The templates finally provide the HTML to output to the browser. While you can 1. define certain variables resp. link a template set with a particular skin via "Skins Manager" and 2. create new template sets (copied from already existing sets) via "Template Sets" the actual work to change the HTML output of Hivemail is to be done 3. via "Templates Manager".

Note 1: the templates header, footer, css_main & css_login are of special importance. They are located in Design folder (Templates Manager). Header contains everything except the main content area (in other words: the information which does not change while browsing the pages -> the header menu and left folder / notes pane). The css_main contains all css markup used by the program.

Note 2: Hivemail writes css files based on the content of the css_main / css_login templates (each skin's css_main / css_login templates are written to the filesystem). Make sure that the css/ directory has write permissions.

Note 3: Besides HTML templates contain control mechanisms (<%if%> ... <%else%> ... <%endif%>) to deliver different parts of HTML under different conditions and PHP variables which again hold variable HTML data (eg. the message list table which is inserted into index template through the variable $mailbits). Pay attention to preserve those things while working on your templates. You can always click on "revert to original" to reset a template in case you get stuck.

Customization Examples
=====================
Now lets briefly look into 2 examples on how to customize Hivemail:

1. Say you want to change the background colors used eg. in the email message list / table. If you click on a row you notice that it changes from a very light gray to a darker gray.

If you hover over the message list with your mouse using tools like firebug for Firefox or Chrome code inspector you discover that we have 2 alternating colors defined via "high Row" and "normal Row" class selectors.

Note: the background colors for the message lists are defined via table row class selectors, eg. tr class="highRow"

If you now go to css_main in order to look up the css rules being responsible for these alternating colors you'll discover 2 array elements (variables) $skin[firstalt resp. secondalt]. These elements hold the value being set in Skins Manager:

Code:

/***** Normal Rows *****/
.normalRow {
background-color: $skin[firstalt];
}
.highRow {
background-color: $skin[secondalt];
}

All that needs to be done is to go to "Skins Manager" and to change the colors in section "first and second alternating color". You are done !

2. Say you want to use different colors for the rendering of the Calendar tables. How can you achieve this ?

Note: the background colors for the Calendar are defined via table cell class selectors, eg. td class="normalCell"

If we look up the rules in css_main we are going to find a couple of normal[xyz]Cell and high[xyz]Cell rules which have background colors set. 2 of them are listed below:

Code:

.normalCell {
.....
background-color: $skin[firstalt];
}
.highCell {
.....
background-color: $skin[secondalt];
}

You notice that the same colors are used both in the message list and the Calendar !

Again, you want to use different colors for the Calendar. That's why we have introduced "Custom Values". Goto "Skins Manager" and set 2 of those custom values, eg. $skin[custom1] + $skin[custom2], according to your liking and finally change the rules in css_main accordingly:

Code:

.normalCell {
.....
background-color: $skin[custom1];
}
.highCell {
.....
background-color: $skin[custom2];
}

You're pretty done ! Now call the frontend by clicking on the "App Home" button at the top (this is a quick way to enter the admin frontend).