Difference between revisions of "Creating Themes Long Version"

(Editing Theme HTML and CSS files)
Line 1: Line 1:
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.
===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:<br /> '''.../skins/test/'''<br />''' test.xml'''<br />'''test_subs.txt'''<br />'''test.html'''<br />'''test.css'''<br />'''logo'''/<br /> '''AppBanner.png'''<br />'''LoginBanner.png'''<br />
===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
<code><skin></code> <br /><code><substitutions></code> <br /><code><file></code>test_subs.txt<code></file></code>  <code></substitutions></code><br /><code><css></code><br /><code><file></code>test.css<code></file></code><br /><code></css></code><br /><code><html></code> <br /><code><file></code>test.html<code></file></code><br /><code></html></code>  <br /><code></skin></code>
Also, note that you can have more than one <code><file></code> 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
<code><skin></code> <br /><code><substitutions></code><br /><code><file></code>../_base/base/base_subs.txt<code></file></code><br /><code><file></code>../_base/light/light_subs.txt<code></file></code><br /><code><file></code>test_subs.txt<code></file></code>  <br /><code></substitutions></code><br /><code><css></code> <br /><code><file></code>../_base/light/light.css<br /><code></file></code>  <code></css></code><br /><code><html></code> <br /><code><file></code>../_base/light/light.html<code></file></code><br /><code></html></code>  <br /><code></skin></code>
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.
<span class="important">This is generally how you will set up your theme.</span> Although it is possible to completely redefine the HTML and CSS files for your theme, it is <span class="important">strongly</span> 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 <code><file></code> 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 <code><SCRIPT language='JavaScript'>...</SCRIPT></code> 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 <code>@import</code>ed 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'''
...<br /> P, TD, DIV, SPAN, SELECT, INPUT, TEXTAREA, BUTTON, A {<br /> '''@Text@''' <br /> }<br /> ...<br /> .DwtButton { '''@NormalButton@''' }<br /> ...
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:
{| width="78%" border="1"
| bgcolor="#EFEFEF" |
file: .../skins/test/test_subs.txt
<code>_SkinName_ = test </code><br /><code>SkinImgDir = /zimbra/skins/test/img </code><br /><code>... </code><br /><code><nowiki># Base color of the app: note that this is designed for a monochrome interface. </nowiki></code><br /><code>_BaseColor_ = #e8dcc1 </code><br /><code>_BaseColorD10_ = #d0c6ad </code><br /><code>_BaseColorL25_ = #efe7d4 </code><br /><code>... </code><br /><code><nowiki># selection color: used for se</nowiki></code><code>lected row, focus items and default buttons </code><br /><code>_SelColor_ = #acc0dd </code><br /><code>_SelColorD10_ = #9aacc6 </code><br /><code>_SelColorL20_ = #8a9ab1 </code><br /><code>... <br /> # misc. colors </code><br /><code>HilightColor = #e3da93 </code><br /><code>MatchedColor = @HilightColor@ </code><br /><code>... </code><br /><code><nowiki># Logical zones in the theme </nowiki></code><br /><code>ChromeBg = background-color:@_BaseColor_@; </code><br /><code>ChromeText = @Text@ </code><br /><code>InsetBg = background-color:@_BaseColorL75_@; </code><br /><code>InsetText = @Text@ </code><br /><code>... </code><br /><code><nowiki># fonts and sizes </nowiki></code><br /><code>FontFamily-default = font-family:Tahoma, Arial, Helvetica, sans-serif; </code><br /><code>FontFamily-fixed = font-family:monospace; </code><br /><code>FontFamily-html = font-family:Verdana,Arial,serif; </code><br /><code>... </code><br /><code>FontSize-normal = font-size:11px; </code><br /><code> FontSize-big = font-size:13px; </code><br /><code>... </code><br /><code><nowiki># Text colors and styles (for use in widgets, app regions, etc) </nowiki></code><br /><code>Text = color: black; </code><br /><code>Label = @Label-wrap@ white-space:nowrap; overflow:hidden; </code><br /><code>... </code>
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 (<code><nowiki>#</nowiki></code>) 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 <code>_BaseColor_</code> 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 <code>_BaseColor_</code>, 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 <code>_SelColor_</code> 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 <code>_SelColor_</code> and its variants.
====Browser-Specific Substitutions====
You will occasionally see <code><nowiki>#IFDEF XXX</nowiki></code> 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 <code>IFDEF</code>ed code that does not match the browser being served to. There are many variables you can <code>IFDEF</code> on, but the most commonly used are:
* <code>MSIE</code>
* <code>GECKO</code> (all netscape-based browsers)
* <code>SAFARI</code>
This <code>IFDEF</code> 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 <code>-moz-border-colors</code> and <code>-moz-border-radius</code> 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 <code>skin.showTreeFooter()</code> and <code>skin.hideTreeFooter()</code> 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 <nowiki><div></nowiki>'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 <code>skin.show<var>X</var>()</code> routine takes a single argument, which is a boolean indicating whether to show (true) or hide the element. The <code>skin.hide<var>X</var>()</code> routine takes no arguments, should always hide the element, and can just call <code>skin.show<var>X</var>(false)</code>. For brevity, only the <code>skin.show<var>X</var>()</code> routines are noted below.
{| class="smallTable" border="1"
! '''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>)><br /> 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:
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>code font</code> is what you will type at the command line.
====Deploying from a Pre-Packaged Binary Distribution====
# Open a terminal or dos window.
# Log in as the Zimbra user:<br /><code> su - zimbra</code>
# Tell the server about the new theme:<br /><code> zmprov mcf +zimbraInstalledSkin themeName</code>
# Restart the server:<br /><code> zmcontrol stop</code><br /><code> zmcontrol start</code>
# 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====
# Open a terminal or dos window.
# Tell the server about the new theme:<br /><code> /opt/zimbra/bin/zmprov mcf +zimbraInstalledSkin themeName</code>
# Go to your ZimbraWebClient/ directory and re-build the source:<br /><code> ant clean deploy</code>
# Restart the server:<br /><code> /opt/zimbra/bin/zmcontrol stop</code><br /><code> /opt/zimbra/bin/zmcontrol start</code>
# And you're done! You should now be able to log in and switch to the new theme in the Options screen.

Revision as of 17:18, 28 February 2007

Jump to: navigation, search