Download STInterfaceFramework SkinningGuide

SmarterTools Inc.
STInterfaceFramework
SkinningGuide
Creating Custom Skins for SmarterMail, SmarterTrack and SmarterStats
SmarterTools Development and Support Teams
6/12/2008
Table of Contents
Introduction and Purpose .......................................................................................................................... 3
Requirements.......................................................................................................................................... 3
Getting Started............................................................................................................................................ 4
Creating a New Skin Folder .................................................................................................................. 4
Understanding the Directory Structure................................................................................................ 4
Locating a Style ...................................................................................................................................... 4
Viewing/Saving Changes .......................................................................................................................... 6
CSS Files ................................................................................................................................................. 6
Images ..................................................................................................................................................... 6
Master Pages .......................................................................................................................................... 7
Overriding Button Defaults ........................................................................................................................ 8
Image Attributes Example ................................................................................................................. 9
Important Notice ....................................................................................................................................... 10
SmarterTools STInterfaceFramework Skinning Guide
Page 2
Introduction and Purpose
The new STInterfaceFramework has become the standard for all SmarterTools products. This
new framework provides the option for SmarterTools Web interfaces to be custom skinned,
allowing for a unified appearance. This article describes the skinning method for your reference.
This process is not for beginners and this document is not an educational tool. You should not
attempt to alter the skin or create new ones unless you have experience with Web interfaces
and building Web sites.
Requirements







Code Editing Software – Microsoft Visual Studio, Adobe Dreamweaver or any other
similar program that can edit HTML and CSS.
Basic knowledge of HTML/XML.
Strong knowledge of CSS.
Image Editing Software – Adobe Photoshop (required for opening the related Interface
Icon .PSD file), any other program capable of editing .PNG and .GIF image files.
Familiarity with image optimization and manipulation procedures.
Multiple Web browsers installed (Internet Explorer 7.0 and FireFox 2.0 recommended).
Installed toolbar extensions for the Web browsers—IE Developer Toolbar and FireBug.
(FireBug is the better option).
SmarterTools STInterfaceFramework Skinning Guide
Page 3
Getting Started
Creating a New Skin Folder
The first step in making a new skin is to create a new skin folder.
This is a simple procedure that is done in two different directories.
From your local drive go into ―Program Files > SmarterTools >
SmarterMail > MRS > App_Themes‖ directory and copy the folder
named ―Horizon.‖ Paste this folder in the same place and give it
the name of your new skin. Repeat this process in the
―MasterPages‖ directory located at the same level as
―App_Themes‖. Make sure to ONLY edit the files within your new
skin folder.
Understanding the Directory Structure
The directory structure is broken down into two main sections, the
―App_Themes‖ directory and the ―MasterPages‖ directory. In both
of these directories, there will be a subfolder for your new skin. In
Figure 1 this subfolder is called ―Viridian.‖ This folder contains all
the files you need to customize the Web interface.
Most of your simple changes—adjusting CSS styles and changing
images—will focus on the files within [YourNewSkinName]
subfolder in the ―App_Themes‖ directory. Main structural changes
are done through the master pages in [YourNewSkinName]
subfolder in the ―MasterPages‖ directory.
Figure 1
Locating a Style
Every single element (image or text) in the framework has at least one CSS style associated to
it. The best method for locating the style(s) is to use a Web browser toolbar (FireBug/IE7
Developer Toolbar). When your test skin is loaded into a browser window, enable the toolbar
extension. For IE7 this located under Tools > Toolbars > Explorer Bar > IE Developer Toolbar.
For FireFox 2.0, FireBug can be enabled by clicking on Tools > FireBug > Open FireBug. Each
toolbar allows you to click on a certain section of the Webpage to show its associated CSS
styles. In IE7, click the far left Arrow Icon and for FireBug use the ―Inspect‖ button (see Figures
2 and 3).
SmarterTools STInterfaceFramework Skinning Guide
Page 4
Figure 2: IE7 Developer Toolbar
Figure 3: FireBug
SmarterTools STInterfaceFramework Skinning Guide
Page 5
After clicking on a certain section, all the styles appear in your
toolbar window, which includes the class name for that element.
This is the class name that you will need to find in either the ―CSS‖
file tree or in one of the subfolders in the ―Controls‖ directory. This
can be found under ―App_Themes > [YourNewSkinName] > CSS‖
or ―App_Themes > [YourNewSkinName] > Controls >‖. (See Figure
4).
Many of these styles are organized into categories (i.e. Calendar,
Login, Grid, etc.). The CSS directory is the main set of CSS
documents, however, there are supplemental CSS files within the
―Controls‖ directory. The ―Controls‖ directory is organized into
specific folders for each control used in the interface. Remember,
edits to the supplemental CSS files will NOT be viewable (take
effect) in the browser window unless a sequential change is made
to the main CSS and then saved.
Figure 4
Viewing/Saving Changes
CSS Files
The CSS files for SmarterMail are located in two places: the ―CSS‖ directory which also includes
a subfolder for the Portal (SmarterTrack only), and in the ―Controls‖ directory which has a
subfolder for each type of control used in the web interface. Changes made to the CSS files
located in the ―CSS‖ directory will instantly be viewable upon refreshing your browser window.
However, the CSS files located in the ―Controls‖ directory are NOT monitored by SmarterMail.
Meaning any changes made to these files will not be readily viewable by simply saving the
document and refreshing the browser window as stated earlier. To see changes made to the
CSS files in the ―Controls‖ directory you must:
1.
2.
3.
4.
5.
Save the CSS file from the subfolder in the ―Controls‖ directory,
Open a CSS file from the ―CSS‖ directory,
Make a change to one of the CSS files (can be as simple as a line return),
Save this change,
Refresh the browser window.
In short, to see changes to the CSS files in the ―Control‖ directory you must make a sequential
change to any CSS file in the ―CSS‖ directory.
Images
All the images for the entire interface are customizable. There is a main ―Images‖ directory,
which has subfolders relating to different sections of the interface. Just like the CSS files, there
is also an ―Img‖ folder in each subfolder of the ―Controls‖ directory. Many images in the interface
SmarterTools STInterfaceFramework Skinning Guide
Page 6
are ―tiled‖, meaning a single image is repeated over and over to achieve a certain appearance.
This keeps the load time down and optimizes the scaling of the interface. (See Figure 5).
The simplest, most efficient way to change
an image is to utilize the same file name,
this way it is a simple replace/overwrite
procedure. In the event you want to change
the name of an image(s), be sure to make
the same change in the corresponding CSS
file. If the image is an icon, you will also
need to reference the section about Overriding Button Defaults. All image changes can be seen
immediately. For the most accurate results, be sure to clear the browser’s cache, and then
refresh the window.
Figure 5
Master Pages
All master pages are located in the ―MasterPages‖ directory within your [YourNewSkinName]
subfolder. Changes to a master page can be seen immediately. Each master page handles the
HTML and ASP for a certain section of the interface. They are as follows:








Root – the outer structure including the main navigation bar and the left tree view panel
Inner – the inner panel that contains all of your messages, settings, reports, contacts,
etc.
InnerPreview – the message preview window
InnerPopup – all popup windows with the interface
InnerSplit – all pages that have a horizontal or vertical splitter (excluding the splitter that
shows/hides the left tree view)
Login – the login page
Wizard – the setup wizard pages during the initial configuration
Error – the form error pages
(SmarterTrack only)


ChatPopup – the Live Chat popup window
CustomerEntry – the entire Customer Portal
SmarterTools STInterfaceFramework Skinning Guide
Page 7
Overriding Button Defaults
Each button within the web interface has a
default icon associated to it. The interface
stores all the button defaults in an xml file
named ButtonBarIcons.xml. This file is
located in the directory called ―App_Data‖
which is outside of the ―App_Themes‖
directory (see Figure 6). DO NOT change
any of the information within this xml file, it
is for reference only.
There is an EDITABLE ButtonBarIcons.xml
file located in the ―App_Themes‖ directory.
See diagram 6.0. This file is used to
override any button’s default icon
established in the App_Data > ButtonBarIcons.xml file.
Figure 6
To override a button’s default icon, locate the name of the button in
the App_Data > ButtonBarIcons.xml file. To locate the name of a
button:
1. Hover over that icon in question within the Web interface. (The
browser Status Bar needs to be visible)
2. Take note of the file path
3. Open App_Data > ButtonBarIcons.xml file and find the button
with that same file path (―/‖ will be replaced with ―.‖) (See
Figure 7)
Figure 7
4. Copy the button tag and then paste this into the App_Themes
> ButtonBarIcons.xml
5. Change the ―image‖ attributes icon file name to that of the new icon file name (your new
icon). See Image Attributes Example below
6. Add [YourNewIcon] to the same image directory as the original
SmarterTools STInterfaceFramework Skinning Guide
Page 8
Figure 8: Web Interface
App_Data > ButtonBarIcons.xml
<Button id="Main.Calendar.frmEvents_btnEdit" image="Edit.png" />
Here we can see the ―id‖ attribute has the file path ―/Main/Calendar/frmEvents‖ from the web
interface, but it has been converted to ―Main.Calendar.frmEvents‖ (for syntax purposes). The
action of the button is then added after the ―_‖, which in this case is ―Edit.‖
The ―image‖ attribute refers to the actual name of the image file used with this button.
Image Attributes Example
Original Button tag:
<Button id="Main.Calendar.frmEvents_btnEdit" image="Edit.png" />
Altered Button tag:
<Button id="Main.Calendar.frmEvents_btnEdit" image="YourNewIcon.png" />
It is recommended that the [YourNewIcon] be placed in the same directory as the original to
ensure the file path is correct. In other words, find the original icon used (it will be in the
―Images‖ or ―Controls‖ directory) and place the new one there with it.
SmarterTools STInterfaceFramework Skinning Guide
Page 9
Important Notice
The recommendations in this document reflect the opinions of its author(s) only and are based
upon their knowledge and experience. No warrantee or guarantee is expressed or implied as to
the efficacy or viability of the information in this document for a particular environment or
application.
SmarterTools, SmarterMail, SmarterTrack, SmarterStats and the respective logos are
trademarks of SmarterTools Inc. All other trade-names and/or trademarks in this document are
the property of their respective owners.
Comments and suggestions regarding the contents of this document should be sent to
[email protected].
SmarterTools STInterfaceFramework Skinning Guide
Page 10