Difference between revisions of "HowTos/Theming Kit"

Revision as of 19:40, 13 October 2008

Prerequisites

On Debian-based systems, you must have dpkg installed. This is normally present.

On RPM-based systems, you must have the rpmbuild program present. This is normally not installed. It is probably in a package called rpm-build, which can be installed with the package maintenance program for your Linux distribution.

Installing the Software

The Theming Kit software is included in release 11.4.1 and more recent.

After upgrading your Scalix server, you will find the theming kit software in

<current version>/extras/swa/theming-kit/swa-theming-kit-<version>.tar.gz

For example: /root/scalix-11.4.1-U1-GA/extras/swa/theming-kit/swa-theming-kit-11.4.1-11592.tar.gz

gunzip and tar -xvf the file.

The swa-theming-kit-<version> contains the following directories:

• README.txt - instructions on how to use the Theming kit. This article is largely based on the README.
• package-theme.sh - used to build a new RPM or DEB from your theme files, to be installed on your SWA server.
• src - this is where you will put the files for your new theme; it also contains sample files from the Scalix Default theme that you can use as a basis for building your new theme.
• samples - contains the files for the Scalix Classic and Default themes.
• packages directory contains files used to build your theme package (the .rpm or .deb file); these files should not be altered.

Creating a Theme

• In the src directory, create a subdirectory with the name that you want your theme to have, for example, 'src/sunset'. Spaces are not allowed in the directory name.
• Copy the contents of one of the sample directories in "samples/" into your

new directory. Alternatively, you can copy the files from src/scalix-sample into your new directory.

# cp -pr samples/scalix-default/* src/sunset

or

# cp -pr src/scalix-sample/* src/sunset

• Edit the files but DO NOT CHANGE THEIR NAMES.

Quick Theme Change

These steps will help you create a new looking client with very little effort.

• Begin with a copy of the default theme

# cp -pr src/scalix-sample src/<theme>

• Edit src/<theme>/properties.xml - give your new theme a name, a long name, a description, and author
• Change the menu background: replace src/<theme>/img/app/md5/menuBar_d.gif with your own color choice; size is 1x1000 pixels; it should be dark on the left and your company color on the right
• Change the logo in the client: replace /src/<theme>/img/app/md5/partner_logo.gif with your own logo; size is 200x23 pixels; it should be on a transparent background; it should be a color that shows up well against your company color
• Change the logo on the log-in screen (this is not part of the theme, it will affect all logins but it is a nice touch): replace /var/opt/scalix/??/tomcat/webapps/webmail/img/logo.gif with your own logo; size is 180x33 pixels
• Change the selected item color and menu hover colors: edit src/<theme>/css/colors.css and change #D80000 to your company color throughout the file.
• Create and Install the package as described later in this document.

Adding Graphics

When adding graphics to the client, take pains that the image does not affect legibility of the text. For example, have a very light graphic and dark text. Here are the steps to take for adding a graphic to the message header area of the preview pane.

• Put the .gif file in src/<theme>/img/app; size is 500x77 pixels or less.
• Modify the src/<theme>/css/colors.css file:

.messageHeader {
  background-color:#A7A0ED;
  background-image:url(../img/messageHeader.gif);
  background-position:100% 0%;
  background-repeat:no-repeat;
}

The background position means place the image 100% to the right and 0% down; this positions the graphic in the top right corner of the Message Header in the preview pane.

Note that the background-image url does not mention the app subdirectory but states a path of ../img/<filename.gif>, even though the .gif file is actually placed in the app subdirectory.

Example of graphic in preview pane message header

Tips for Professional Look and Feel

• Decide on any graphics you want to incorporate into the theme. This might be your company logo, a favorite photo, or something else you think is cool. Update the partner_logo.gif or create messageHeader.gif to include your graphic. Place these in <theme>/img/app and update the messageHeader entry in colors.css if necessary.
• Pick a color that complements the graphic; this will become the base color for your theme.
• Figure out hex color values for five or six shades of your selected base color, from lightest to darkest. The very lightest color is optional; you can use white instead.
• Assign your color values as follows (in colors.css unless otherwise indicated):
  • White or very lightest color:
    • .renamer
    • .textInputField
    • .messageRenderer
    • .grid_container
    • .grid_unhighlighted_data_row
  • Light color:
    • .upcomingAppointmentsDiv
    • .FreeBusyMeetingBody
    • .FreeBusyMeetingLeftBar
    • .FreeBusyMeetignRightBar
    • .popdownButton
    • .panel
    • .miniCalendarPane
    • .calendarSetPane
    • .treeviewContainer
    • .menuItemShortcutCell
    • .menuItem_disabled .menuItemShortcutCell
    • .sliderMarker (slider.css)
    • background for calendar hours
    • status bar background
  • Medium Light:
    • .grid_header_mousedown
    • .tab_selected
    • .tab_pane
    • .toolbarButton_down
    • .messageHeader
    • .treeviewNodeLabelCell_selected_blur
    • selected mode button
    • preview pane divider
    • selected message color
    • .menu
    • .grid_highlighted_unfocused_data_row
    • .table_view_highlighted_unfocused_data_row
  • Medium:
    • .FreeBusyTableHeader
    • .tab
    • unselected mode button
    • slider background
    • .dayWeekViewAllDayFillerCell
  • Medium Dark:
    • mode background
    • .calendarViewHeaderCell
    • .menuItemLeftIconCell
  • Dark:
    • .paneHeader
    • .table_view_header
    • shadow for mode selector background
    • .dayWeekViewAllDayEntryCell
    • .menuTitle_hover
    • .grid_scrollable_div
    • body (shpants.css)
    • .dayWeekViewAllDayEntryCell (calendar.css)
    • .dayWeekViewAllDayFillerCell (calendar.css)

• Create gradient .gif files in <theme>/img/app/md5
  • White or Lightest at top, Light at bottom: tree_background.gif
  • Medium at top, Dark at bottom: divider_d.gif
  • Medium at top, Medium Light at bottom: toolbar_d.gif
  • Black, dark base color, or dark contrasting color at left, white, light base color, or light contrasting color at right: menuBar_d.gif
  • Dark at top, medium dark at bottom: modebar_bg.gif

• Edit modebar.gif so that the selected item is on a medium light background and the non-selected item is on a medium background.

• Pick a color that contrasts with the base color of your theme; this will be the color of selected folders and messages.
• Figure out hex values for two shades of the contrast color. These should be medium to dark shades.
• Assign your contrast colors as follows in colors.css unless otherwise noted:
  • Medium:
    • .grid_highlighted_focused_data_row
    • .table_view_highlighted_focused_data_row
    • .menuItem_hover .menuItemCaptionCell
    • .menuItem_hover .menuItemShortcutCell
    • .treeviewNodeLabelCell_selected
    • .planningAvailabilitytDiv (calendar.css)
    • .monthViewEntryCell .selected

• • Dark:
    • .menuItem_hover .menuItemLeftIconCell
    • .menuItem_hover .menuItemRightIconCell

Building the Package

In the folder where the package-theme.sh script is installed, run package-theme.sh <theme>

./package-theme sunset

This will create a "deb" or "rpm" package in the current directory.

Checking the Package

RPMs:
rpm -qlp <package-file> - List all the files in the package

scalix-swa-theme-sunset-11.4.1-11592.noarch.rpm

rpm -ql --dump <package-file> - List verbose information about all the files in the package

rpm -ql --dump scalix-swa-theme-sunset-11.4.1-11592.noarch.rpm

DEBs:
dpkg -x <package-file> <path> - unpacks the data files as if the path named was "root" - does not execute any of the scripts, such as preinst, postinst - you can look at the files to see if they are in the right folders

mkdir out
dpkg -x scalix-theme-sunset-11.4.1-123_all.deb out

Installing the New Theme

• Copy the package to the first Scalix SWA server where you wish to install it. The first server might be an SWA-only server that is used only for testing.
• Install it. One way is to use the GUI-based package maintenance program for your Linux distribution. Look for documentation on installing packages that are on your hard drive and not in your repository.
  Another way is to use the "rpm" or "dpkg" commands. These are documented with "man" or "info".

rpm -i  scalix-swa-theme-sunset-11.4.1-11592.noarch.rpm

• Restart SWA on that server.

service scalix-tomcat restart

• Test on that server to make sure that it behaves as you expect.
• Repeat for all the Scalix servers that have SWA installed on them.

Activating the New Theme

The user must activate the new theme in their own profile. Perform the following steps:

• If the user had an SWA client window open on their desktop while SWA was restarted on the server, close the window and log in again.
• Click on the following:

- Tools
- Options

• Select the "Themes" tab in the bar on the left.
• From the drop down "Themes" list, select the new theme, i.e. 'sunset'.
• Click "OK"
• The user may need to close SWA and login again for the changes to take effect.

Files You can Modify

This is just a partial description to get you started. Play and have fun with it! To help you understand what's what, here's some terminology: Panes - appear in the left hand side of the SWA client and can show folder list, calendar list, upcoming appointments, date navigation, etc. Panels - appear on the right hand side of the SWA client and can list messages, show a preview of a message, show the calendar, etc. Tree - Table - the list of folders Grid - the list of messages, contacts, or notes in the table Menu - file, edit, view, actions tools, help Toolbar - beneath the menu; icons to launch various tools; context-sensitive

<theme>/img/app

• alarm.gif - displayed when there is a reminder set on an appointment or meeting
• meeting.gif - used in calendar view to indicate a meeting rather than an appointment
• meeting_organizer.gif - appears beside the organizer's name in the list of meeting attendees
• meeting_resource.gif - displayed when an invitee is a resource
• misc_icons.gif -
• month_cal_overflow.gif -
• optional_attendee.gif - appears beside optional attendees' names in the list of meeting attendees
• private.gif - appears in calendar view to show an appointment or meeting is private
• repeat.gif - appears in calendar view to show an appointment or meeting is recurring
• repeat_ex.gif - used to indicate a recurring appointment or meeting for which one instance has been edited (recurring exception)
• required_attendee.gif - appears beside required attendees' names in the list of meeting attendees

<theme>/img/app/md5

• calpop.gif - used when creating an appointment or meeting, or setting a contact's birthday or anniversary; when you want to pop-up a calendar from which to select a date
• divider_d.gif - used to divide left hand panes from right hand panes (for example, mailbox list, upcoming events, date navigator from message list and preview). Also used to form the background for message display and meeting creation windows.
• freebusy_info_bg.gif - used when free/busy info is not available
• folderIcons.gif - used beside list of folders to indicate inbox, outbox, drafts, calendar, etc.
• hoveroverstick.gif - Used to make part of the "speech bubble" for context-sensitive information that appears when you hover your mouse over something; for example, when you hover your mouse over a bold date in the date navigator, or an appointment in the calendar.
• indicator.gif - displayed in the mode selection area when you have a new message.
• labels.gif - used to label appointment or meeting (Important, Business, Personal, Vacation...)
• logo.gif - Edit this and put it in /var/opt/scalix/??/tomcat/webapps/webmail/img/ if you want to change the login screen logo.
• menuBar_d.gif - the background behind the text menu and the logo
• misc_icons.gif
• modebar.gif - indicates whether you're looking at messages or calendars (bottom left corner)
• modebar_bg.gif - background for mode bar; the mode bar is where you select whether you want to view messages or calendars.
• partner_logo.gif - logo in top right corner of SWA client
• preferencesIcons.gif - used for the Tools->Options menu
• search_relevance_off.gif - used in search results window to indicate relevance
• search_relevance_on.gif - used in search results window to indicate relevance
• tableIcons.gif - used in the list of messages to indicate new message, attachment, follow-up flag, meeting request accepted, non-delivery, etc.
• toolbar.gif - icons used in the toolbar (context-senstitive horizontal icons, just below the menu)
• toolbar_d.gif - background for toolbar icons
• tree_background.gif - used for the background of panes; use this to shade from white top to gray bottom, for example

<theme>/css

calendar.css

• calendar.css - controls calendar; uses tree_background.gif, labels.gif

fonts.css

• fonts.css - fonts used with calendar, menus, tabs, etc.

modebar.css

• modebar.css - controls the area where you pick mail/calendar view; uses modebar.gif, modebar_bg.gif, and indicator.gif

tableview.css

• tableview.css - ; uses folderIcons.gif

treeview.css

• treeview.css - controls the folder list area; uses tree_background.gif, folderIcons.gif

colors.css

colors.css - colors used in the other .css file

• • calendar.css
    • .upcomingAppointmentsDiv
    • .calendarViewHeaderCell - depending on the calendar view selected, this is day and date, or day
    • .dayWeekViewAllDayEntryCell - in day or week view, the end user can double-click this bar just beneath day/date and create an all-day entry
    • .dayWeekViewAllDayFillerCell - the little cell to the right of the "all week" bar in a day or week view.
    • .dayWeekViewApptDiv
    • .dayWeekViewAllDayApptDiv
    • .monthViewAllDayApptDiv
    • .dayWeekViewApptBody
    • .isToday - the color of today's date in day or week view; usually set to same vlaue as .monthViewEntryCell .isToday
    • .monthViewEntryCell .selected - the selected date in the calendar month view. The selected date is displayed on a background of "background-color"
    • .monthViewEntryCell .isToday - when the calendar is in month view, today's date shows up in this color; usually set to the same value as .dayWeekViewApptDiv .isToday
    • .isNotToday - color of date numbers in month view that are not today
    • .upcomingAppointmentHeaderCell
    • .upcomingAppointmentTimeCell
    • .upcomingAppointmentSubjectCell
    • .calendarLoadingDiv
  • dragdrop.css
  • grid.css
    • .grid_container
    • .grid_scrollable_div
    • .grid_header
    • .grid_header_mousedown - what happens when you click a grid header, to sort by subject, date, author, etc.
    • .grid_unhighlighted_data_row
    • .grid_highlighted_focused_data_row - controls how a highlighted item appears in the grid - i.e. a highlighted message or contact.
    • .grid_highlighted_unfocused_data_row - the selected message or contact in the grid when focus is on the table
  • menu.css
    • .menuBar - Set this to the same value as the right-hand color of menuBar_d.gif, because it will show on the right if you make your screen wider than menuBar_d.gif
    • .menuTitle_hover - highlights the menu item your mouse is hovering over, before you select it. The linked image shows this set to green.
    • .menu - the drop down menus; file, edit, view, actions, tools, help
    • .menuShadow - color behind the drop-down menus
    • .menuItemLeftIconCell - this will show to the left of the active options in a drop-down menu. The linked image shows this set to red.
    • .menuItem_hover .menuItemLeftIconCell - the icon (or empty cell) of the item your mouse is hovering over in the drop-down menu
    • .menuItem_hover .menuItemCaptionCell - the item your mouse is hovering over in the drop-down menu. The linked image shows this set to orange.
    • .menuItemShortcutCell - the "shortcut keys" in the menu, for example "control+<" for previous message
    • .menuItem_disabled .menuItemShortcutCell - the shortcut cell for items on the menu that cannot be selected in the current context. The linked image shows this set to blue.
    • .menuItem_hover .menuItemShortcutCell - the color of the "shortcut key" in the menu when you hover your mouse over the selection. The linked image shows this set to purple.
    • .menuItem_hover .menuItemRightIconCell - the cell to the right of the shortcut field. The linked image shows this set to yellow.
    • .singleToolbarMenu
    • .singleToolbarMenuLeft
    • .singleToolbarMenuRight
    • .menuItem_disabled .singleToolbarMenuRight
  • shpants.css
    • body - the color that lies behind everything else; it will show up at the bottom of the "Loading user preferences" screen during login and beside the calendar pane if the window is sized very large. The linked image shows it set to red.
    • .panel_header
    • .panel
    • .paneDivider
    • .paneDividerOn
    • .pane, .messagepane, .appointmentspane
    • .bigTableResizer
    • .renamer - box when you are renaming a folder in the table
    • .paneHeader - header for Folder list, Calendar list, Upcoming Appointments, Date Navigator
    • .messageHeader - the message header in the preview pane
    • .miniCalendarPane
    • .textInputField - where you enter text, such as a name to search for when addressing a message by clicking the "to" button
    • .messageRenderer - the message in the preview pane
    • .popdownButton - button to select start/end time when creating an appointment or meeting
    • .infobar
    • .hoverOverMenu - the bubble that pops up when you hover over an upcoming event in the upcoming events pane, or a bold date in the date navigation pane
    • .calendarSetPane
  • tableview.css
    • .table_view_header - The column headers over the list of messages or contacts in the grid, i.e. From, Subject, Date, etc.
    • .table_view_header_mousedown - Controls how a header looks when you click on it, for example to sort by sender, subject, or date. The linked image shows this set to green.
    • .table_view_scrollable_div
    • .table_view_unhighlighted_data_row
    • .table_view_highlighted_focused_data_row - controls how a selected table item like a message or contact appears when the table is in focus. The linked image shows this set to purple.
    • .table_view_highlighted_unfocused_data_row - controls how a selected table item like a message or contact appears when the table is not in focus. The linked image shows this set to pink.
    • .col_separator
  • tabs.css
    • .tab - tabs not in focus when you are creating an appointment or meeting.
    • .tab_selected - indicates which tab you are on when creating an appointment or meeting - for example, when creating a meeting if you're on the appointment, scheduling, or recurrence tab.
    • .tab_pane - the window where you create an appointment or meeting
  • toolbar.css
    • .toolbar
    • .toolbarButton_down - indicates that you have clicked on a toolbar icon
  • treeview.css
    • .treeviewNodeLabelCell_selected - shows how a folder looks when it's selected and the folder list (tree view) is in focus. The linked graphic shows this set to orange.
    • .treeviewNodeLabelCell_selected_blur - shows how a folder looks when it's selected and the folder list (tree view) is not in focus. The linked image shows this set to blue.
    • .treeviewContainer
  • wnd_ComposeAppt.css
    • .FreeBusyTableHeader - shows date and hours above free/busy view on scheduling tab when creating a meeting
    • .FreeBusyMeetingBody - where the free and busy time is displayed on scheduling tab when creating a meeting
    • .FreeBusyMeetingLeftBar - in scheduling tab, this color is on the lefthand side of the free-busy display area
    • .FreeBusyMeetingRightBar
    • .timePopStart, .timePopEnd, .fb_timePopStart, .fb_timePopEnd
  • override colors
    • body.print
    • iframe.messageRenderer html body
    • .datePickerCell

grid.css

• grid.css - ; uses folderIcons.gif

shpants.css

• shpants.css - controls panes in SWA client; uses calpop.gif, folderIcons.gif, hoveroverstick.gif, misc_icons.gif, search_relevance_off.gif, search_relevance_on.gif, toolbar.gif, tree_background.gif

tabs.css

• tabs.css

wnd_ComposeAppt.css

• wnd_ComposeAppt.css - controls the appointment window; uses freebusy_info_bg.gif, calpop.gif, tableIcons.gif

dragdrop.css

• dragdrop.css - controls drag-and-drop; uses folderIcons.gif

menu.css

• menu.css - controls menu (File, Edit, View...) and the context dependent icon menu below that in all windows; uses menuBar_d.gif, toolbar.gif, misc_icons.gif

slider.css

• slider.css - controls the slider

toolbar.css

• toolbar.css - controls the context dependent icon menus; uses toolbar_d.gif, toolbar.gif, labels.gif, misc_icons.gif

Ltward 14:05, 26 August 2008 (PDT)