Table of Contents

Skins in ZWC 5.0

About Skins

The skinning system allows you to easily change the appearance of ZWC, for example, to use the logo and colors of your company or institution. You can create many different skins to provide your users with choices for the appearance of the application, or you can restrict users to a single skin to enforce brand identity.

At a fundamental level, the skinning system all comes down to HTML and CSS files, since that is how the browser styles elements on a web page. The main purpose of the skinning system is to simplify working with the large number of CSS files in the ZWC app. We try to follow the DRY (Don't Repeat Yourself) Principle -- by specifying the appearance of the app logically and then making that work throughout the CSS. By changing a few settings, you can easily change many details in the ZWC's appearance.

What this means in practice is that your skin specifies a number of Skin Variables (in Skin Property Files) which are then compiled into the HTML and CSS files that make up the application.

The default ZWC installation comes with several themes, which you can use as the basis of your own themes. As of the time of this writing, they are:

• bare
• beach (the default skin)
• bones
• hotrod
• lavendder
• lemongrass
• sand
• sky
• steel
• waves

What can be customized

• Logos (see Changing Logos)
• Color and border of the Skin Zones
• Color and border of various widgets such as Buttons, Tabs, etc (see Widget Appearance)
• Text fonts, colors and sizes (see Working with Fonts)
• Appearance and size of Ad Zones (see Working with Ads)
• Basic appearance of the Standard (HTML) client (see Working with the Standard Client)

• Layout of the Skin Zones
• Appearance of the Splash Screen (see Custom Splash Screen)
• HTML templates for the various widgets and many application screens (see Working with Templates)

What cannot be customized

• Changing the behavior of something (rather than its appearance)
• Order of application tabs
• Order of toolbar buttons
• Adding toolbar buttons
• Adding buttons to the Search toolbar

Audience Experience

See Getting Help for help in accomplishing these tasks if necessary.

Quick Reference

Creating a Simple Skin

1. Find a ZCS skin that is similar to the one you want to customize. We'll assume that you're starting with the "sand" skin (one of the default skins shipped with ZWC 5.0).
2. Locate the Skin Directory for the skin you want to customize. In our case, this will be .../zimbra/skins/sand/. (see Locating the Skin Files and Anatomy of a Skin for more info)
3. Duplicate the entire skin directory and give it a new name. We'll use "pumpkin" as the name of our sample skin.
4. Edit the file .../zimbra/skins/pumpkin/skin.properties with your favorite text editor. (see Skin Property Files).
5. Change the "SkinName" variable to "pumpkin" (or whatever you called your skin -- this must be exactly the same as the name of the skin directory and the name is case sensitive).
6. Pick new Skin Colors for the AppC, AltC and SelC Skin Variables:
   • AppC is the base color of the background and most of the application. The skin framework will automatically generate lighter and darker shades of this color to make a pleasing appearance for the application.
   • AltC is the base color for toolbars and highlighted buttons. If you want a single color (monochromatic) theme, you can leave this as @darken(AppC,20)@, which will be a darker shade of the AppC.
   • SelC is the highlight color for lists, such as the list of messages.

   For example, to create our pumpkin theme, we'll use the following values:

   New colors in our sample skin.properties file

   			AppC				=	#fec855
   			AltC				=	#ddbc76
   			SelC				=	#ffffcc
   			

7. To change the logo for the application, create a folder called .../zimbra/skins/pumpkin/logos/ and place the following files in it. Transparent PNG images are encouraged for this (see Use of PNGs).
   1. LoginBanner.png, a PNG image sized at 450px wide by 100px tall that will be displayed in the "splash screen" shown when the application is loading.
   2. AppBanner.png, a PNG image sized at 120px wide by 35px tall that will be displayed in the upper-left corner of the application window.
   ZCS licensing rules govern who can change the logos and who must use the Zimbra logo, see Changing Logos.
8. Change the LogoImgDir and LogoURL Skin Variables in your skin.properties file as shown below. Set LogoURL to the URL where you would like to send users when they click the logo graphic:
   Custom logos in our sample skin.properties file

   			LogoImgDir		= /zimbra/skins/@SkinName@/logos
   			LogoURL			= http://www.yourcompany.com
   			

9. Use the zmskindeploy tool to install your skin. Type the following on the command line:

   			cd /opt/zimbra/jetty/webapps/zimbra/skins/
   			zmskindeploy pumpkin/
   			

10. To test your new skin, add the url parameter "skin=<skinname>" to the normal URL you use to access ZWC:
    http://your.server.com/zimbra/?skin=pumpkin
    

Anatomy of a Skin

All of the skins for your install of ZWC live inside the .../zimbra/skins/ directory, each skin in a separate sub-directory. For example, the "beach" skin lives in the directory .../zimbra/skins/beach/. We will refer to this below as the skin directory. See Locating the Skin Files for how to find this in your system.

Note that some skins reference files in other skin directories to avoid duplication of files -- in particular, many skins reference the .../zimbra/skins/_base/base2 directory, where the common files for most skins live.

A skin is composed of some or all of the following files:

File Type	Example	Purpose
Skin Manifest	manifest.xml	tells the application which files comprise this skin
Skin Property Files	skin.properties	the primary controller of the appearance of the skin
Skin CSS Files	skin.css	(optional) overrides standard application CSS definitions
Skin HTML Files	skin.html	(optional) used to lay out the Skin Zones
	splash.html	(optional) Splash Screen, shows when app first launches
Skin JS Files	skin.js	(optional) provides custom javascript for the skin.
logo images	logos/AppBanner.png logos/LoginBanner.png	(optional) Logos for the splash screen and "banner" graphic at the top-left of the application. See Changing Logos.
custom icons and graphics	img/...	(optional) Custom images, for example, background graphics for the different skin zones or custom icons. See Applying Background Images and Changing Icons.
skin templates	templates/widget.template	(optional) Custom HTML templates for widgets or many application screens. See Working with Templates.
message files	messages/ZmMsg.properties	(optional) 'Messages' are labels and prompts that are shown in the application. See Working with Message Files.

Skin File Details

Skin Manifest

Below is the manifest for the default beach skin:

				
					
						
							../_base/base2/skin.properties
							skin.properties
						
						
							../_base/base2/skin.css
						
					  
					
						
						
							../_base/base2/skin.html
							../_base/base2/splash.html
						
					
					
						
							../../css/zhtml.css
						
					
				 
			

• common -- This section lists files for both the Advanced (Ajax) and Standard (HTML) clients
• advanced -- This section lists files for the Advanced client only
• standard -- This section lists files for the Standard client only

• substitutions -- Skin Property Files
• css -- Skin CSS Files
• html -- Skin HTML Files
• templates -- Skin Templates

Skin Property Files

You specify your skin properties file in your manifest like so:

				
					
						...
						
							../_base/base2/skin.properties
							skin.properties
						
						...
					
					...
				
			

1. the base properties file (.../zimbra/skins/_base/base2/skin.properties), which sets up most skin variables, and
2. a custom properties file (skin.properties) in your skin directory, which overrides definitions in the base file as needed.

A skin properties file looks something like this:

				# I am a Property File Comment
				SkinName                    = MySkin
				SkinVersion                 = 2
				
				TreeColor                   = #f9f6f0
				TreeStyle                   = background-color:@TreeColor@;
				ToolbarColor                = @darken(TreeColor,30)@
				
				# Fix non-standard IE syntax
				#IFDEF MSIE
					DisabledOpacity         = filter:alpha(opacity=40);
				#ELSE
					DisabledOpacity         = opacity:0.4;
				#ENDIF
			

• Lines that begin with # are Property File Comments.
• Lines that begin with #IFDEF, #IFNDEF, #ELSE, or #ENDIF are Property File Directives.
• All other lines (for example, SkinName = MySkin above) define Skin Variables. Most skin variables are used to output CSS properties or values.

• Text that begins and ends with an @ character (for example, @AppColor@) are Skin Replacements.
• Functions inside @ characters (e.g. @darken(AppColor,30)@) are Skin Functions.

Also, note that it is possible to define the same variable more than once in two properties file, or even within the same properties file using Property File Directives -- in this case, the definition that is loaded last will "win" or override. This ensures that definitions in your skin will take precedence over the standard ones in the base properties file.

Skin Variables

For a concrete example, say we wanted to set the background color for the Tree on the left side of the application, we'd set the following:

				TreeColor  =  #f9f6f0	
				TreeStyle  =  background-color:@TreeColor@;	
			

Note in this example that the replacement value in TreeStyle has the TreeColor replacement in it -- this is a common pattern, to define a value once and then use it in other skin variables later within the same properties file.

The tree color would manifest in your application via a CSS file, in this case skin.css where a CSS definition would reference the TreeStyle variable:

				...
				
				.skin_container_tree 	{	@TreeStyle@		}	
				
				...		
			

Why would you want to use skin variables, why wouldn't you just hard-code the value of #f9f6f0?

Looking again at the expanded example above, note that we define:

							...
							TreeColor                   = #f9f6f0
							...
							ToolbarColor                = @darken(TreeColor,30)@
							....
			

This indicates that the toolbars in the application should be a darker shade of the TreeColor defined above. The skinning system is set up so that you can change a couple of variables (TreeColor in this case) in the skin.properties file and have that change ripple out through the rest of the application. You are free to break this pattern as you like, for example if you wanted your Toolbars to be a shade of blue, you could define:

							...
							TreeColor                   = #f9f6f0
							...
							ToolbarColor                = #bccbd6
							....
			

A few more notes on properties files:

						TreeStyle  =  background-color:@TreeColor@; \
						              border:1px solid black;	
					

Skin Replacements

Remember that Skin Variables can be defined more than once (e.g. in different files) and that the last occurance of the skin variable is the one that will be displayed. This ensures, for example, that your definition of a Skin Variable will override the one defined in the base properties file.

Skin Functions

Note that a color variable below can be in any of the following forms:

• a literal color, e.g.: #fff or #ab321c
• the name of a netscape named browser color, e.g.: red, blue or goldenrod
• the name of a Skin Variable, e.g.: TreeColor, ToolbarColor

Note that the skin replacement function names are NOT case sensitive, so the following are all equivalent:

• @lighten(black,20)@
• @Lighten(black,20)@
• @LIGHTEN(black,20)@

Property File Comments

Property File Directives

This is useful because small differences in the way that browsers display web pages can mean that the same CSS will show different results in different browsers. This is a fallback which allows the skin designer to specify different behavior for each browser, rather than ripping their hair out.

The meaning of the directives is as follows:

• #IFDEF variable -- do the following if variable is defined (eg: there is a non-empty skin variable defined for that name)
• #IFNDEF variable -- do the following if variable is NOT defined
• #ELSE -- do the following if the previous #IFDEF or #IFNDEF was not followed
• #ENDIF -- ends a directive

• MSIE -- some version of Microsoft Internet Explorer
• GECKO -- some version of Mozilla Firefox or Netscape Explorer (or another browser that uses the 'Gecko' rendering engine)
• SAFARI -- some version of Apple's Safari or another WebKit browser

					#IFDEF MSIE
						ToolbarMargin		= margin:5px;
					#ELSE
						ToolbarMargin		= margin:10px;
					#ENDIF
				

Note that the example above could also have been written like so:

					ToolbarMargin           = margin:10px;
					#IFDEF MSIE
					    ToolbarMargin       = margin:5px;
					#ENDIF
				

If you need to do more than a simple #ELSE, nest two declarations:

					#IFDEF MSIE
					    ToolbarMargin           = margin:10px;
					#ELSE
						#IFDEF GECKO
					        ToolbarMargin       = margin:5px;
					    #ELSE
					        ToolbarMargin       = margin:0px;
					    #ENDIF
					#ENDIF
				

Skin CSS Files

• CSS selectors for the skin and splash screen themselves
• Overrides for standard application CSS that the skin needs to make

					
						
							...
							
								../_base/base2/skin.css
							
							...
						
						...
					
				

					
						
							...
							
								../_base/base2/skin.css
								skin.css
							
							...
						
						...
					
				

Application CSS Files

You do not need to do anything to include these files in your skin -- the appropriate ones are always used.

A brief explanation of each:

Filename	Used for
common.css	Files common to many situations
dwt.css	Widget styling (Buttons, Toolbars, etc)
editor.css	HTML editor widget
login.css	Login (and splash screen) styles
msgview.css	Email message body styles
spellcheck.css	Spell checker styles
wiki.css	Zimbra Documents (wiki) page styles when opened in a new window
zhtml.css	Styles for the Standard (HTML) version
zlogin.css	Login (and splash screen) styles
zm.css	Styles specific to the Zimbra Web Client application
zmadmin.css	Styles specific to the Zimbra Administration application
zmobile.css	Styles for the mobile-phone version of ZWC

Note that you should avoid modifying these css files directly, as any changes to the files will not survive even minor upgrades to your ZWC installation. If you need to change a style that is defined in an app CSS file, copy that definition into your custom skin.css file and modify it there.

Skin HTML Files

					
						...
							
							...
							
								../_base/base2/skin.html
								../_base/base2/splash.html
							
							...
						
						...
					
				

					
						...
							
							...
							
								../_base/base2/skin.html
								splash.html
							
							...
						
						...
					
				

Custom Skin Layout

Regardless of how you start, it is important to pay attention to a few rules:

• You must have an element with ID='skin_outer' which is the outer-most element of your skin. This element must span the entire browser window without scrolling, and is responsible for making sure all of the elements within it have their sizes automatically re-adjusted when the browser window is resized. (The easiest way to do this is with a table set to width and height of 100%).
• You must provide a a number of elements within your skin.html file with specific IDs that control where the various parts of the application will show up. If any of these elements is missing, your skin may not load. These correspond to the Skin Zones -- please see that section for a list of elements.

  If you wish to visually omit a zone, create an element with the appropriate ID and position it with CSS so that it is off screen -- this will hide it from the user.

Custom Splash Screen

There is just one rule to follow for your splash screen:

• The outer container for your splash screen must have ID='skin_container_splash_screen'. It must span the entire browser window without scrolling, and should resize properly when the browser window is resized. (The easiest way to do this is with a table set to width and height of 100%).

Skin JS Files

If you are using the standard skin.html file, you should just include the standard skin.js file (skins/_base/base2/ZmSkin.js) from the base skin directory -- everything is set up properly. To use the standard skin.js file, your manifest.xml should look like the following:

					
						...
							
							...
							
							...
						
						...
					
				

If you have a custom skin.html file, you might need to have a custom skin.js file. If you keep all of the same IDs for the Skin Zones as detailed below, you may be able to skip this step.

If you do need to create a custom skin.js file, it is easiest to base your skin.js file on the standard one: to do this, create a new file .../zimbra/skins/YourSkin/skin.js and update your manifest.xml like so:

					
						...
							
							...
							<script>
								../_base/base2/ZmSkin.js
								skin.js
							</script>
							...
						
						...
					
				

Note that the base skin.js file must come before your skin.js file.

Detailing the Javascript code that you must include in your custom skin is beyond the scope of this document -- please Getting Help for more information on making javascript changes to your skin.

Skin Zones

Skin Colors

Base Colors

Note that slightly lighter and darker shades of each of these colors are generated automatically (using the @darken(...)@ and @lighten(...)@ Skin Functions) to create a cohesive look in the skin.

Skin Variable	Purpose
AppC	Master color for the entire skin. Shades of this color are used as background and border colors for most of the Skin Zones.
AltC	Alternate color for the skin. Shades of this color are generally used for: Toolbars, Selected/highlighted buttons, etc.
SelC	highlight color for lists.

Other Skin Colors

Following is a list of other colors which are used to change various parts of the skin -- you generally will not need to change these colors:

Skin Variable	Purpose
HilightColor	Background color for right-clicked items, drag and drop, selected item in a tree
HilightColor-blurred	Background color for tree items when the tree does not have focus
MatchedColor	Background color for items matched in a search (default is HilightColor)
RightClickColor	Background color for right-click items (default is HilightColor)
HeaderColor	Background color for headers, such as in the tree, above a list, etc
InputBgColor	Background color for INPUT elements (text fields)
WidgetBgColor	Background color for widgets such as Buttons and Selects
SeparatorColor	Border color for separators between sections

Skin Containers

Here's a diagram of the zones of the "beach" skin. Note that some zones may typically be hidden -- for example, the ad zones, or the Advanced Search ("search_builder") zones are often hidden.

(Enlarge)

Each zone corresponds to an element (generally a DIV) in the skin.html file -- we call these "Skin Containers". Use the table below to map the names of the skin container elements to the Skin Variables that control them:

Element IDs	Skin Variables used	Purpose
Normal skin zones
skin_outer	SkinOuter	Outer container of the skin itself
skin_container_logo	SkinBorderLogo	Logo
skin_container_search	SkinBorderSearch	Container for the search toolbar
skin_container_web_search	SkinBorderWebSearch	Container for the web search toolbar
skin_container_username	SkinTextUsername	Name of the current user
skin_container_quota	SkinBorderQuota	Disk quota usage area
skin_container_switch	(none)	Switch between Ajax and HTML clients link
skin_container_help	(none)	Help button
skin_container_logoff	(none)	Logout button
skin_container_offline_status	(none)	Online/offline status indicator
skin_container_search_builder	SkinBorderSB	"Advanced" search area
skin_container_search_builder_toolbar	SkinBorderSBToolbar	Toolbar for Search Builder (now called "Advanced Search")
skin_container_app_chooser	SkinBorderAppChooser	Application tabs (to switch between apps)
skin_container_current_app	SkinBorderCurrentApp	Toolbar for the Overview Tree
skin_container_app_top_toolbar	SkinBorderAppToolbar	Toolbar for the App Area
skin_container_tree	SkinBorderTree	Tree of folders
skin_container_tree_footer	SkinBorderMiniCal	Mini-calendar in the lower left side
skin_container_tree_app_sash	SkinBorderTreeSash	Vertical bar that resizes the tree and application zones
skin_container_app_main	SkinBorderApp	Main application area (switches based on current app)
Ad containers -- see Working with Ads
skin_container_top_ad	AdStyle, TopAdHeight	Space for a top "banner" ad
skin_container_sidebar_ad	AdStyle, SidebarAdWidth	Space for a "skyscraper" ad to the right of the app
skin_container_tree_top_ad	AdStyle, TreeTopAdHeight	Space for a small ad above the tree
skin_container_tree_bottom_ad	AdStyle, TreeBottomAdHeight	Space for a small ad below the tree
skin_container_bottom_ad	AdStyle, BottomAdHeight	Space for an ad on the bottom of the window
Splash screen and login panel
skin_container_splash_screen	SkinOuter	Background outside of the splash screen and login panel
ZSplashPanel	SplashOuterBorder	Splash screen outer container
ZSplashBodyContainer	SplashOuterBorder	Splash screen inner container
ZLoginPanel	LoginPanelOuterBorder	Login panel outer container
ZLoginBodyContainer	LoginPanelInnerBorder	Login panel inner container
Deprecated
skin_container_status		status area (no longer shown)

To customize a particular skin container listed above, create an entry for it's skin Variable in your skin.properties file and specify the CSS properties that you want for that zone. It is a good idea to start off with the definition of that skin variable in the .../zimbra/skins/_base/base2/skin.properties file.

Most of the skin containers are defined in terms of the Logical Skin Zone Variables defined below -- you may find it advantageous to change these logical variables (which will affect many different zones) rather than change each zone individually.

Also, note that if the base skin.properties file specifies a width and/or height for a particular skin zone, you should specify that as well or the skin may not lay out properly.

For the skin variables named SkinBorder*, you can generally customize the following CSS properties:

• height and/or width (sometimes required to make the app lay out properly)
• background-color and/or background-image
• border
• color (e.g. text color)
• round corners (use the @roundCorners()@ Skin Function)

					...
					SkinBorderSearch       = height:31px; background-color:pink; padding:5px; \
					                         border:1px solid red; @roundCorners(5)@
					                         
					SkinBorderAppToolbar   = @ToolbarContainer@ background-color:pink; 
					...
				

Note that the SkinBorderAppToolbar variable above is defined in terms of the ToolbarContainer replacement (see below) -- this is a common pattern. Placing the background-color entry after the ToolbarContainer replacement ensures that it will override any background-color set in ToolbarContainer.

Logical Skin Zone Variables

Widget Appearance

You can customize the color and border of most widgets in ZWC easily using the following Skin Variables.

In addition to the normal appearance of each widget, you can control the appearance of the widget in the following states:

State	Meaning
normal	Widget in its 'normal' state (e.g. not interacting with the mouse or keyboard)
disabled	Widget when it is not available to be used
hover	Widget when the mouse is over the control
active	Widget when it is being pressed
focused	Widget when it has the keyboard focus
selected	Widget when it has been 'selected', for example a selected tab or a row in a list that is selected
sel-focus	Widget that is both selected and focused (in list viewers only)
default	Widget that will be activated when the return key is pressed
actioned	Widget that is being right-clicked
dragProxy	Widget that is currently being dragged

Logical Widget Variables

• Buttons
• ToolbarButtons
• Selects
• Menus
• Mini-Calendar buttons

Widget Sizing

Skin Variables for Specific Widgets

Buttons

ToolbarButtons

Selects

Application Tabs

Tabs

ListViews

Trees

Accordion

Menus

Tooltips

Links and Anchors

Inputs and Textareas

Mini-Calendar

Sliders

Windows

Working with Fonts

Helpful Skin Variables

Skin Borders

Skin Variable	Usage
TransparentBorder	"Border" used for a widget, etc when you don't want a border to show up initially, but will be showing a border on hover, etc. For example, used in Toolbar Buttons so the buttons don't 'jump' when a border is shown on hover.
NormalOutsetBorder	Normal outset (raised) border based on the AppC variable.
MediumOutsetBorder	Slightly darker outset border based on AppC.
DarkOutsetBorder	Very dark outset border based on AppC.
NormalInsetBorder	Normal inset (lowered) border based on AppC.
MediumInsetBorder	Slightly darker inset border based on AppC.
DarkInsetBorder	Very dark inset border based on AppC.
AltOutsetBorder	Normal outset border based on AltC.
AltInsetBorder	Normal inset border based on AltC.
SelOutsetBorder	Normal outset border based on SelC.
SelInsetBorder	Normal inset border based on SelC.
DisabledBorder	Border for a disabled widget, based on AppC.
DefaultBorder	Border for a default widget -- the widget that will be activated by the return key.
FocusBorder	Border for a focused widget -- the widget that has keyboard focus.
DragBorder	Border for something being dragged in a drag-and-drop operation.
FieldBorder	Border for an input field.
SmallTransparentBorder	Transparent "border" for use in the Mini-Calendar.
SmallOutsetBorder	Outset border for use in the Mini-Calendar (based on AppC).
SmallInsetBorder	Inset border for use in the Mini-Calendar (based on AppC).

Working with Images

Images in ZWC

Images are specified within the ZWC app with a CSS class name that is the same as the name of the image (minus the .gif or .png extension). So an image named: ImgRightArrow.gif will correspond to the CSS class name ImgRightArrow. The consequence of this mapping of image name to CSS class means that there can only be one image of any given name used within the system. The advantage of this is that it is easy to override any image that is used within the application -- you simply add another image of the same name to your skin.

All images in your skin should go in a directory named img/ inside your skin directory: .../zimbra/skins/YourSkin/img/. We'll refer to this below as your skin image directory. The skin variable SkinImgDir will automatically reference this directory.

To add an image to your skin:

1. Create the image as a PNG or GIF image. (See Use of PNGs). If you are replacing a pre-existing ZWC image, make sure your image has exactly the same name as the original image.
2. Create your skin image directory, as above, and place the image in it.
3. Deploy Your Skin

Applying Background Images

1. Create your image as a .gif or .png file, choose a name (we'll use ChromeBg.gif) and save it in your skin image directory (e.g. .../zimbra/skins/YourSkin/img/ChromeBg.gif). Note that this is an arbitrary name, but naming the image the same as the Skin Variable it will be used by can make things clearer.
2. Edit your skin.properties file (.../zimbra/skins/YourSkin/skin.properties), and add an entry for the ChromeBg skin variable, as shown below.
3. Deploy Your Skin.

					...
					ChromeBg		= @image(SkinImgDir, ChromeBg.gif, 100%, 100%, repeat)@
					...
				

Changing Logos

Note that there are legal rules for who may customize these logos, as detailed below and at this site: http://www.zimbra.com/partners/trademark_branding_faq.html

• If you are using the Zimbra Web Client (ZWC) under the open source license, and you have not modifed the software, then you are required to use the Zimbra logo and URL (the default).
  your skin.properties file with the Zimbra logo

  							LogoImgDir      = /zimbra/skins/_base/logos
  							LogoURL         = http://www.zimbra.com
  						

• If you are using ZWC under the open source license, and you have modified the software, then you are required to use the Zimbra Inside logo.
  your skin.properties with the Zimbra Inside logo

  							LogoImgDir      = /zimbra/skins/_base/logos/ZimbraInside
  							LogoURL         = http://www.zimbra.com
  						

• If you are using ZWC under the network (commercial) license, then you are welcome to use your own logo in place of the Zimbra logo, or to retain the original Zimbra logo.
  your skin.properties with a custom logo

  							LogoImgDir      = /zimbra/skins/@SkinName@/logos
  							LogoURL         = http://www.yourcompany.com
  						

  Create your custom logos as specified below:

  Image Location	Notes
  /skins/YourSkin/logos/LoginBanner.png	Shows up on the login and splash screens. Save it in the PNG format (alpha transparency is OK) at 450 pixels wide by 100 pixels tall.
  /skins/YourSkin/logos/AppBanner.png	Shows up in the top-left of the application as it is running. Save it in the PNG format (alpha transparency is OK) at 120 pixels wide by 35 pixels tall.

Changing Icons

Note that you want to override one of the individual images, which should start with Img -- these images are generally in subdirectories of the image directory, eg: .../zimbra/img/arrows/ImgNextPage.gif. The large images such as arrows.gif are merged images which are generated automatically -- see Merging Images below for more information on this process.

Note that it is a good idea for you to create your images at the same size -- generally, 16 x 16 pixels -- as the original Zimbra image. If you do not, things may not line up properly. You do not need to put your images in the same directories as the original Zimbra images.

Merging Images

Naming Images to be Merged

Most images are set to not repeat -- that is, the image should only show up once, even if the HTML element that displays it is larger than the image size. If you want an image to tile, or repeat, you indicate this by saving the image with a special name:

• To repeat both horizontally and vertically (like a background graphic), add .repeat before the extension in your image name, eg: Background.repeat.gif
• To repeat horizontally only (like a gradient behind a header), add .repeatx before the extension in your image name, eg: Header.repeatx.gif
• To repeat vertically only, add .repeaty before the extension in your image name, eg: verticalStripe.repeaty.gif

Note that the default behavior is that all images in each sub-folder of your skin image directory will be merged together. So if you have two folders in your image directory, you will end up with two merged images. This is for efficiency -- combining images is generally a good idea, but the bigger the combined image the more memory it will take up in the browser when it is used over and over. A couple of notes on image directories:

• All images in a directory should have the same color palette (see Color Palette Considerations).
• If you want the ImageMerge program to skip a directory entirely, place an empty text file in the directory called _ignore.flag. This is useful for keeping your source (Photoshop) images close to the images they generate.
• If you want to create CSS entries for a directory of images, but don't want it to try to merge them together, place an empty text file in the directory called _nomerge.flag.

  Color Palette Considerations

  In order for the ImageMerge program to efficiently process a folder of images, all of the GIF images must be saved to exactly the same color palette. This is because the image merge program takes all of these GIFs and mashes them together into a single, large GIF image, which is what is actually sent down to the browser. If you have images within a directory with different palettes, the images will not all be merged -- things will still work correctly, but the ZWC application will not be served as efficiently to your users as it could be.

  The easiest way to work with a large set of images is to have them in a single Photoshop file, and use the "Slice" command in Photoshop to cut the big image into individual images. It is a bit tricky to get Photoshop to save all of these files with exactly the same palette, but below is a formula that is known to work.

  Step 1: save your color palette.

  1. Create your photoshop file and create slices with the names of your images.
  2. In Photoshop, choose Image -> Mode -> Indexed Color...
  3. Choose settings:
     • Palette: Local (Selective)
     • Colors: 254 (note: NOT 256!)
     • Transparency: checked
     • (whatever other Options you like)
     and click OK.
  4. Choose Image -> Mode -> Color Table...
  5. Click Save and save the image with a name you can remember later
  6. Click Cancel to exit the color table dialog.
  7. Choose Edit -> Undo Indexed Color to make sure you don't inadvertently save the indexed color version over your master file.
  You now have a color palette that represents all of the images in the file. You should re-do this step whenever you add or change colors in your master image.

  Step 2: save your images

  1. Choose File -> Save for Web and Devices... (may be called "Save for Web...")
  2. Type ctrl-A (apple-A on a Mac) to select all of the slices in your document.
  3. Change the settings on the right to:
     • GIF
     • in the second menu on the left, select the named palette you saved in Step 1. The colors will switch to (auto) when you touch this menu.
     • Colors: 255
     • (any other settings you wish)
  4. Click Save to save the images.
  5. Move the images in to your Skin Image directory.
  Note that it is very important that you save the images with 255 colors, and not "(Auto)" colors. If you save as "auto", the ImageMerge program will not be able to merge your images.

  You can verify that the images are saved with the same palette by opening two or more of the sliced images and choosing

  Image -> Mode -> Color Palette... -- if both images have palettes of the same 255 colors, it worked. If the images have different palettes, try running through the procedure above again, following the steps in the exact order described.

  Use of PNGs

  Versions of Internet Explorer prior to version 7 did not have native support for PNG images with mutliple levels of transparency (also known as "alpha transparency", or in general "transparent PNGs"). Although there is a hack you can use to use transparent PNGs within IE, too much use of transparent PNGs has been shown in our testing to crash the browser. For this reason, we recommend that you use GIF images whenever possible within your application.

  The exception is the logo images (see Changing Logos), which should be saved as transparent PNGs to make sure that they look good on a variety of skin backgrounds.

  Working with Ads

  The ZWC application in version 5.0 supports displaying ads in five locations:
  • At the very top of the window (Top Ad)
  • On the right side of the window (Sidebar Ad)
  • Above the tree (Tree Top Ad)
  • Below the tree and mini-calendar (Tree Bottom Ad)
  • At the very bottom of the window (Bottom Ad)
  To actually display ads, you deploy Zimlets (see: http://www.zimbra.com/products/zimlets.html) that implement the code necessary to show the ads. Contact Zimbra Professional Services to obtain pre-written zimlets for displaying ads.

  Note that to change the default height or width of an ad, you should override the following skin variables:

  Ad	Skin Variable	Default Value
  Top Ad	TopAdHeight	60px
  Sidebar Ad	SidebarAdWidth	165px
  Tree Top Ad	TreeTopAdHeight	30px
  Tree Bottom Ad	TreeBottomAdHeight	60px
  Bottom Ad	BottomAdHeight	40px

  To do so, add an entry with the new size to your skin.properties file:

  skin.properties file with custom ad sizes

  				...
  				TopAdHeight         = 60px
  				SidebarAdWidth      = 165px
  				TreeTopAdHeight     = 30px
  				TreeBottomAdHeight  = 60px
  				BottomAdHeight      = 40px
  				...
  			

  Working with Templates

  Template files contain fragments of HTML code that the ZWC application uses to draw certain parts of the page. For example, the layout of the "message header" in the email application is encoded in the template "mail.Message#MessageHeader". The default ZWC templates live in the template directory: .../zimbra/templates/.

  You can override any templates in your skin to customize the appearance of the application. To do so:

  1. Create a skin template directory: .../zimbra/skins/YourSkin/templates/
  2. Place one or more template files in the directory, eg: YourTemplateFile.template.
  3. Add the template files to your manifest.xml file, making it look like the below.
  excerpt from sample manifest.xml file referencing skin templates

  					
  						...
  							
  							...
  							
  								templates/YourTemplateFile.template
  							
  							...
  						
  						...
  					
  				

  Don't forget to update your manifest.xml file to point to your new templates file, or they will not appear in your skin.
  The organization of the files within your template directory is up to you, but we recommend that you consider keeping the same organization of template folders and files as in the Zimbra template directory.

  The programming of templates is beyond the scope of this document -- see Getting Help for resources to help customize the appearance of the application via templates.

  Working with Message Files

  Message files contain text fragments (strings) that are presented to the user, for example, the text of buttons or the labels of text fields. You can customize the messages that your users see by overriding any of the default messages in the Zimbra message directory: .../zimbra/messages/.

  Note that there are five types of files in that directory, along with translations into French, Japanese, Spanish, etc:

  • AjxMsg*.properties are messages for the Ajax toolkit that ZWC uses to create the application. This is mostly things like date names, generic error messages, etc.
  • ZaMsg*.properties are messages for the Zimbra Admin application.
  • ZhMsg*.properties are messages specific to the Standard (HTML) version of ZWC.
  • ZmMsg*.properties are messages for the normal ZWC application
  • ZMsg*.properties are messages common to two or more of the above applications.
  Note that the files without a country code are the American English versions, eg: ZmMsg.properties is messages in English, while ZmMsg_it.properties is the Italian version.

  To show custom messages in your skin:

  1. Create a Skin Message Directory: .../zimbra/skins/YourSkin/messages/
  2. Create one or more files with the same name as the standard message file that you want to customize.
  3. Add entries in your skin message file with the same name as that of the standard message. You do not have to copy all of the messages from the original file -- the messages from the default file will be used for anything missing from your file.
  4. Follow the same procedure for any other languages for which you wish to create custom messages.
  5. Note that you do not need to update your manifest.xml file -- all messages in your Skin Message Directory will be loaded automatically.
  See Getting Help for more information on using message files.

  Working with the Standard Client

  The Standard (or "HTML") Client will automatically pick up certain aspects of the Advanced client skins, primarily:
  • logos
  • colors
  • fonts, and
  • custom message files.
  If you create a new skin for the Advanced client, that skin will automatically be available to the HTML client as well.

  Changing the layout of the Standard client, including placement of ads, is beyond the scope of this document -- see Getting Help for resources to make these changes.

  Changing the Login Page skin

  Because a different skin might be associated with each user's account, there is no way to know which skin should be shown on the ZWC login page. For this reason, the login page always comes up with the "beach" skin for all users.

  To change the appearance of the login page, make changes directly to the "beach" skin, in the folder .../zimbra/skins/beach/. Simply make any logo or color changes you like to the .../zimbra/skins/beach/skin.properties file and it will show those changes on the login screen for all users. Also, as "beach" is the default skin for new users, this will also customize the skin that most of your users will see after login as well.

  Unfortunately, changes you make to the "beach" skin will not necessarily survive upgrades to your ZWC install, as the new version will often change the default skins. To make sure your login skin survives upgrades, copy the "beach" skin into another directory before installing the upgrade, then replace the upgraded "beach" with the copy you just made.

  Zimbra Gallery

  The zimbra gallery is a repository of additional skins, language packs and Zimlets that are available for you to download and install on your ZWC server. Please see: http://gallery.zimbra.com/.

  We encourage you to upload any generally interesting skins that you create to the Gallery!

  Deploying Skins

  Locating the Skin Files

  If you have installed ZWC in the normal manner, the files that make up the web interface of ZWC should be in the directory: /opt/zimbra/jetty/webapps/zimbra/. We'll refer to this as your WebApps directory, and it will be generally abbreviated through this document as .../zimbra/....

  Each individual skin is contained in a directory underneath the skins/ directory in your WebApps directory -- for example, for the "beach" skin, all the files for the skin will be found at /opt/zimbra/jetty/webapps/zimbra/skins/beach/. This directory is known as your skins directory.

  Note that most skins reference another, special skin directory to provide resources that are shared across many skins -- this is the base skin directory, and will generally be found at /opt/zimbra/jetty/webapps/zimbra/skins/_base/base2/.

  If you have done a non-standard install of ZWC, please consult your install logs or the administrator of your computer to help find your skins directory.

  Deploying Your Skin

  There are basically three steps to making a skin available on your system. For example, to install a skin named "pumpkin", you would:
  1. Place the skin directory inside the Webapps directory: /opt/zimbra/jetty/webapps/zimbra/skins/pumpkin/
  2. Run the zmskindeploy command, as detailed below.
  3. (optional) Use the Zimbra Administration interface to control which of your mail accounts have access to the skin.

  zmskindeploy

  To make deploying skins easy, we have created a command-line tool that manages all of the little tasks required to properly format the skin and make it available to your users. This tool:
  • Runs the Image Merge process on your skin, so images will be served efficiently,
  • Enables the skin for all users of your ZWC deployment, and
  • Restarts the web server, so it recognizes the new skin.
  It is easiest to run zmskindeploy from the command line in the skins directory, one level up from your skin. For example, to deploy the 'pumpkin' skin:
  Command line steps to deploy a sample skin

  			cd /opt/zimbra/jetty/webapps/zimbra/skins/
  			zmskindeploy pumpkin/
  			

  Note the slash after the name of the skin.

  You can use the zmskindeploy command as many times as you like, for example, if you are actively making changes to a skin and you want to test, make a change, then re-test the skin.

  You can also use zmskindeploy with a .zip file that contains a top-level folder with the same name as the skin. For example, to deploy "pumpkin" from a .zip file, create the zip file called pumpkin.zip with the structure:

  Structure of a skin.zip file

  	  		pumpkin/manifest.xml
  	  		pumpkin/skin.properties
  	  	

  then use zmskindeploy to deploy it
  Command line steps to deploy a skin from a .zip file

  			cp /downloads/pumpkin.zip /opt/zimbra/jetty/webapps/zimbra/skins/
  			cd /opt/zimbra/jetty/webapps/zimbra/skins/
  			zmskindeploy pumpkin.zip
  			

  Getting Help

  If the directions in this document are unclear or you have questions about developing your own skins,
  • Network Edition Customers can contact support, https://support.zimbra.com/supportlogin.php
  • Open Source users can find help from the Zimbra Forums, http://www.zimbra.com/forums/
  Network Edition customers, if you need help designing and developing new skins, contact Zimbra Sales to work with our Professional Services team. Email sales@zimbra.com.

  Troubleshooting

  Working with skins can be a bit tricky -- if things are not changing like you want them to, try the following:
  • Restart the web server.
  • Clear your browser cache.
  • Verify that any additional files you are adding to your skin such as templates or css files are specified in your manifest.xml file.
  • When all else fails, see Getting Help above for help in creating your skin.

  Tips

  Working with FireBug

  When developing a skin, your best friend is the FireBug extension for Firefox, available at

  http://getfirebug.com

  After installing firebug, you will see a little green checkbox (or a red X) at the bottom-right corner of your browser window status bar. (You may need to restart Firefox or show the status bar to see this). Clicking this icon brings up the Firebug console, which gives you a number of powerful debugging tools for web pages in general.

  
  (Enlarge)

  Specifically for ZWC, you can use the "Inspect" button of Firebug (next to the little bug icon in the upper-left of the console) to figure out the CSS class of a particular part of the app you want to tweak.

  1. Show the Firebug console and click on the Inspect button.
  2. Click on the part of the application that you want to tweak.
  3. Look in the pane on the left in the console -- you will see the HTML source that makes up that part of the display. You can also click tags in the HTML source display to highlight that part of the application (in the example above, the "MsgHeaderTable" which shows the header of an email message is selected and highlighted).
  4. You can use this to figure out