Creating Themes Long Version

From Zimbra :: Wiki

Jump to: navigation, search
Developer Article

Article Information

This article applies to the following ZCS versions.
  ZCS 4.5 Article  ZCS 4.5

For later release information about Themes (Skins), see ZWC 5.0, 6.0, and 7.0 Themes.

This gets into the gory details of how the theming mechanism works, probably explaining more than you'd really like to know, and definitely more than you need to know to create a theme.

Contents

Components of a ZCS Theme

A theme is composed of a single directory which contains a number of text and image files. Generally, the names of the text files are prefixed with the name of the theme. For example, for the theme named sand, you would use files sand.html, sand.xml, etc. In this document, whenever you see [theme] in a file name, substitute the name of your theme (e.g., [theme].xml in the sand theme would really mean file sand.xml).

All theme files live in the /opt/zimbra/tomcat/webapps/zimbra/skins/ directory. In general, each directory there corresponds with a single theme available to users of the ZCS. Note that the directories .../skin/_sample/ and .../skin/_base/ are special directories used to create themes -- these are not exposed as themes to the user.

To create a new theme, create a folder with the name of your theme in the .../skins/ directory. (The examples will use the theme name test). Note that currently, spaces are not allowed in the folder name. Within this folder you can have the following files:

  • [theme].xml (mandatory): This is the "manifest" for your theme, which details all of the other files that make up the theme. See The Theme Manifest below.
  • [theme]_subs.txt (mandatory): This sets up a number of substitutions which are performed in the other theme files that customizes their appearance. For example, this is where the background color of elements are set, where fonts are defined, etc. See Editing Theme Substitution Files below.
  • [theme].html (optional): This is the HTML responsible for drawing the theme, along with the javascript required to show or hide parts of the theme dynamically. In general, you will be pointing to an HTML file in the skins/_base directory rather than creating your own. See Editing Theme HTML and CSS files.
  • [theme].css (optional): This is CSS definitions that are paired with the elements in [theme].html. In general, you will be pointing to a CSS file in the skins/_base directory rather than creating your own. See Editing Theme HTML and CSS files.

Note that some of the files listed above are deemed (optional) -- for these files, some you can omit entirely, and for some you can set things up in the manifest to use the corresponding file in another theme. See The Theme Manifest section for details.

(Network Edition) For example, to fully create a theme named test, you might have the following directory structure:
.../skins/test/
test.xml
test_subs.txt
test.html
test.css
logo/
AppBanner.png
LoginBanner.png

The Theme Manifest

The theme manifest ([theme].xml) defines the location of the files that make up the theme. For a fully-specified theme named test, it would look like:

file: .../skins/test/test.xml

<skin>
<substitutions>
<file>test_subs.txt</file> </substitutions>
<css>
<file>test.css</file>
</css>
<html>
<file>test.html</file>
</html>
</skin>

Also, note that you can have more than one <file> entry per category, and that these file entries can refer to other themes by locating them in the directory structure. For example, if theme test wanted to simply provide a small set of changes from theme _base/light, you might have:

file: .../skins/test/test.xml

<skin>
<substitutions>
<file>../_base/base/base_subs.txt</file>
<file>../_base/light/light_subs.txt</file>
<file>test_subs.txt</file>
</substitutions>
<css>
<file>../_base/light/light.css
</file> </css>
<html>
<file>../_base/light/light.html</file>
</html>
</skin>

This indicates that the light theme files should be used in addition to or in place of the corresponding files in this theme. In particular:

  • for the substitutions, the file base_subs.txt will be loaded first, then light_subs.txt will be loaded (overriding any similarly-named entities in base_subs.txt), and then the entries in test_subs.txt will override the correspondingly named entries in both base files.
  • the theme does not specify its own CSS and HTML files, instead relying completely on the light theme for its HTML and CSS.

This is generally how you will set up your theme. Although it is possible to completely redefine the HTML and CSS files for your theme, it is strongly recommended that you use the base HTML and CSS files and simply change the substitutions that are performed in the css. This way you can be assured that your theme will survive upgrades to the ZCS application. Changes to the HTML and CSS files (as well as changes to private entries in the [theme]_subs file) are not guaranteed to survive upgrades.

Note that you can add extra <file> entries in any of the categories in your manifest -- the files will automatically be loaded in the order listed. Make sure you include a file of the corresponding type as its category. For example, to include a Javascript file, name it foo.html and make sure it has <SCRIPT language='JavaScript'>...</SCRIPT> tags around the actual Javascript content. CSS files do not need to be encoded in this way -- just list your CSS entries as if the file was @imported as a separate link.

Editing Theme Substitution Files

All of the CSS files that are used within the ZCS application, as well as those defined in your theme, use a special substitution syntax to allow the theming process to work. The ZCS server application uses the substitution file(s) supplied with a theme to process all of the CSS files and apply colors, fonts, borders, etc to the ZCS applications and widgets. This happens automatically when the server is running and is completely transparent to the browser.

If you were to look in the unprocessed css files that comprise the ZCS application, you would see a number of entries like so:

file: somefile.css

...
P, TD, DIV, SPAN, SELECT, INPUT, TEXTAREA, BUTTON, A {
@Text@
}
...
.DwtButton { @NormalButton@ }
...

The @xxx@ syntax there indicates that an entry in the substitution file(s) with that name should be placed at that spot in the CSS files. This gives us a very powerful way to apply different styles to the widgets within the application, while not slowing down the browser to perform these substitutions at runtime.

Looking at a sample [theme]_subs.txt file, you'll see entries like so:

file: .../skins/test/test_subs.txt

_SkinName_ = test
SkinImgDir = /zimbra/skins/test/img
...
# Base color of the app: note that this is designed for a monochrome interface.
_BaseColor_ = #e8dcc1
_BaseColorD10_ = #d0c6ad
_BaseColorL25_ = #efe7d4
...
# selection color: used for selected row, focus items and default buttons
_SelColor_ = #acc0dd
_SelColorD10_ = #9aacc6
_SelColorL20_ = #8a9ab1
...
# misc. colors

HilightColor = #e3da93
MatchedColor = @HilightColor@
...
# Logical zones in the theme
ChromeBg = background-color:@_BaseColor_@;
ChromeText = @Text@
InsetBg = background-color:@_BaseColorL75_@;
InsetText = @Text@
...
# fonts and sizes
FontFamily-default = font-family:Tahoma, Arial, Helvetica, sans-serif;
FontFamily-fixed = font-family:monospace;
FontFamily-html = font-family:Verdana,Arial,serif;
...
FontSize-normal = font-size:11px;
FontSize-big = font-size:13px;
...
# Text colors and styles (for use in widgets, app regions, etc)
Text = color: black;
Label = @Label-wrap@ white-space:nowrap; overflow:hidden;
...

Each line in the substitutions file represents a single substitution -- the entry on the left side is the variable name, and the text on the right of the equals sign is the value that will replace it. Lines that begin with a pound sign (#) are comments.

If more than one substitution file is specified in the manifest, an entry named foo in the second file listed will override an entry named foo in the first file, etc.

Note that before the substition file is run on the CSS files, substitutions are run on the substitution file itself, which is why you will sometimes see @foo@ entries on the right hand side of some lines. This is deliberate -- it allows us to define some logical entries within the substitution file and use them repeatedly within the rest of the subs file. The order in which the substitions are defined is not important.

Note that all substitutions that begin and end with an underscore (eg: _foo_) are only to be used within the substitution file itself -- consider them "private" variables. Although there is nothing preventing you from using the underscore substitutions in other files, they are not guaranteed to be there in future versions of the system.

What You Can Change

As a rule of thumb, it is safe for you to change anything in the [theme]_subs.txt that you copied from the .../skins/_sample/ directory. While there are literally hundreds of substitutions that can be used in the CSS files, we recommend that in this version of ZCS you limit yourself to only changing colors, fonts and logo images as indicated in the sample file. To see the other things that you can possibly change, take a look at the file .../skins/_base/base/base_subs.txt. You can change the other substitutions, but they may not survive upgrades to the system.

Most commonly, you will want to change the colors of the theme. The sample themes define a single _BaseColor_ that is used to give the theme a consistent color theme. The HTML, CSS, and substitution files are crafted to use subtle light and dark variants of this color to achieve effects like attractive buttons that look like they raise and lower, without the use of images. To define a _BaseColor_, use the ZCS Theme Color Picker to pick the colors interactively, then copy and paste the list of color variants into your [theme]_subs.txt file. See ZCS Theme Color Picker.

The themes also define a _SelColor_ which is the color used to show selected rows in lists, default buttons, etc. The ZCS Theme color picker will also help you set the _SelColor_ and its variants.

Browser-Specific Substitutions

You will occasionally see #IFDEF XXX in the substitution files. This is a way to ensure that certain substitutions only appear in certain browsers. The server will parse this at runtime and will eliminate any IFDEFed code that does not match the browser being served to. There are many variables you can IFDEF on, but the most commonly used are:

  • MSIE
  • GECKO (all netscape-based browsers)
  • SAFARI

This IFDEF logic also applies to the HTML and CSS files that make up your theme, and is also performed automatically before the server sends the files to the client.

Note that the themes take advantage of browser-specific CSS properties to make the theme more attractive when possible. Specifically, the sample themes use the -moz-border-colors and -moz-border-radius attributes to make the pieces of the theme look round in Firefox. IE and Safari do not support these attributes, so they have a more square look.

Editing Theme HTML and CSS files

The theme HTML and CSS files are what actually draws the borders of the theme, and exposes the interface that tells the application where to position different pieces of the ZCS interface, like the overview tree, the search toolbar, etc. The theme is responsible for laying out all of the pieces of the application, and for resizing the pieces of the theme automatically when the browser is resized. The theme HTML file is also responsible for exposing a simple interface for showing and hiding different parts of the theme dynamically. For example, sometimes the mini-calendar below the tree should be hidden. The theme exposes skin.showTreeFooter() and skin.hideTreeFooter() routines that the app manager uses to show or hide that region of the interface. The theme is responsible only for showing and hiding the outline of that portion of the UI an making sure that the rest of the theme reflows properly -- the app manager code will make sure that the components get placed properly and resized.

There are a number of
's that the theme must define in order for the application to know where to put the corresponding application element. These are identified by id within the [theme].html. The theme is free to put whatever other "chrome" around these elements that it wants to to make the theme look pretty. The [theme].css file is used to position the various pieces of the [theme].html file.

We strongly recommend that you use one of the standard sets of CSS and HTML files, rather than creating your own. This way you can be ensured that your theme survives upgrades to future versions of ZCS.

The Theme/ZCS API

The list of ID'd elements that the application looks for within the theme are listed below. Note that you must provide all of the named elements within your theme (even if they are hidden) or the application will generate an error on startup.

The theme and ZCS application use a simple API to show and hide various parts of the theme. It is completely up to your theme how it wants to show and hide these elements -- you can either use AjaxToolKit routines to do so, or you can create your own simple API for doing this.

The skin.showX() routine takes a single argument, which is a boolean indicating whether to show (true) or hide the element. The skin.hideX() routine takes no arguments, should always hide the element, and can just call skin.showX(false). For brevity, only the skin.showX() routines are noted below.

Name Description Show/Hide API
skin_outer Outer container of the entire skin skin.showSkin(<boolean>)
skin_container_logo Application logo (none)
skin_container_search Search toolbar (none)
skin_container_quota User name and quota area skin.showQuota(<boolean>)
skin_container_search_builder_toolbar Toolbar for the search builder. skin.showSearchBuilder(<boolean>)>
shows search builder and its toolbar
skin_container_search_builder Search builder area (see above)
skin_container_current_app Displays the current app and view menu (none)
skin_container_tree_app_sash Draggable vertical border between tree and app areas (none)
skin_container_app_top_toolbar Toolbar area for the main app skin.showTopToolbar(<boolean>)
skin_container_app_chooser Buttons that allow you to switch apps (none)
skin_container_tree Overview tree (none)
skin_container_tree_footer Mini-calendar shown below tree skin.showTreeFooter(<boolean>)
skin_container_app_main Main application area (none)
skin_container_status Status area -- shows time and transient status messages (none)

There is one other routine that your theme must implement: skin.setTreeWidth(newWidth) This is called by the application when the user drags the "sash" or split bar to resize the tree horizontally. newWidth is the absolute width in pixels for the current size of the tree.

Changing the Logo Images

One common reason to create a new theme is to change the logo images shown in the login and splash screen, as well as the small logo shown in the upper-left of the application screen. You can also change the URL that is linked to when the logo is clicked. See Network Edition - Adding Logos or Open Source - Adding Zimbra Inside Logo articles for details about changing logos.

Deploying a Theme

Deploying a theme is simple, but how you do it depends on if you are using a pre-packaged binary distribution of the application or building from the source code. In the instructions below, text in the code font is what you will type at the command line.

Deploying from a Pre-Packaged Binary Distribution

  1. Open a terminal or dos window.
  2. Log in as the Zimbra user:
    su - zimbra
  3. Tell the server about the new theme:
    zmprov mcf +zimbraInstalledSkin themeName
  4. Restart the server:
    zmcontrol stop
    zmcontrol start
  5. And you're done! You should now be able to log in and switch to the new theme in the Options screen.

Deploying from a Source Files

  1. Open a terminal or dos window.
  2. Tell the server about the new theme:
    /opt/zimbra/bin/zmprov mcf +zimbraInstalledSkin themeName
  3. Go to your ZimbraWebClient/ directory and re-build the source:
    ant clean deploy
  4. Restart the server:
    /opt/zimbra/bin/zmcontrol stop
    /opt/zimbra/bin/zmcontrol start
  5. And you're done! You should now be able to log in and switch to the new theme in the Options screen.
Personal tools