Difference between revisions of "HowTos/Theming Kit"

Revision as of 20:23, 5 November 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 1000x1 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

The list below is only a starting point. Once you've followed these guidelines, you'll have a theme that is close to your goal, which you can tweak to perfection.

• 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 <theme>/css/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
    • .timePopStart
    • .timePopEnd
    • .fb_timePopStart
    • .fb_timePopEnd
    • .panel
    • .miniCalendarPane
    • .calendarSetPane
    • .treeviewContainer
    • .menuItemShortcutCell
    • .menuItem_disabled .menuItemShortcutCell
    • .toolbarButton_down
    • .sliderMarker (slider.css)
    • background for calendar hours
    • status bar background
  • Medium Light:
    • .grid_header_mousedown
    • .tab_selected
    • .tab_pane
    • .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
    • .menuTitle_hover
    • .grid_scrollable_div
    • body (shpants.css)
    • .dayWeekViewAllDayEntryCell
    • .dayWeekViewAllDayFillerCell

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

• 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 four shades of the contrast color.
• Assign your contrast colors as follows in colors.css unless otherwise noted:
  • Light:
    • .dayWeekViewEntryCellOutView, .dayWeekViewEntryCellOutViewCore (calendar.css)
    • .monthViewEntryCellInCore (calendar.css)
    • .datePickerCell_active (calendar.css)
  • Medium-Light:
    • .menuItem_hover .menuItemShortcutCell
    • .treeviewNodeLabelCell_selected_blur
    • .dayWeekViewEntryCellInView, .dayWeekViewEntryCellInViewCore (calendar.css)
    • .monthViewEntryCellOutCore (calendar.css)
  • Medium-Dark:
    • td.monthViewEntryCell div.isSelected
    • .grid_highlighted_focused_data_row
    • .menuBar
    • .menuItem_hover .menuItemLeftIconCell
    • .menuItem_hover .menuItemRightIconCell
    • .table_view_highlighted_focused_data_row
    • .treeviewNodeLabelCell_selected
    • .planningAvailabilitytDiv (calendar.css)
  • Dark:
    • .menuItem_hover .menuItemCaptionCell
    • .paneHeader

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.

Removing a Theme

To remove a theme from the Tools -> Options menu:

• Remove the package. For example, on a RedHat distribution you'd run a command similar to:

rpm -e scalix-swa-theme-mytheme-11.4.2-11691

• Edit the theme's properties.xml file so that the theme is disabled

<theme enabled="false">

• Build the package

package-theme.sh mytheme

• Install the package

rpm -i scalix-swa-theme-mytheme-11.4.2-11691.noarch.rpm

• Restart the scalix-tomcat service:

service scalix-tomcat restart

To remove the Scalix Default and Scalix Classic themes, you will need to copy those themes from the samples subdirectory to the src subdirectory (else the package-theme.sh script will not find them). Then follow the steps above, skipping the removal of the package.

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

• • .dayWeekViewEntryCellInView, .dayWeekViewEntryCellInViewCore - in day, work week, or week view, the hours that are outside the work hours. Shown in pink in the attached screenshot.
  • .dayWeekViewEntryCellOutView, .dayWeekViewEntryCellOutViewCore - in day, work week, or week view, the work hours. Shown in green in the attached screenshot.
  • .monthViewEntryCellInCore - In month view, the squares showing the days of the selected month. Orange in the attached screenshot.
  • .monthViewEntryCellOutCore - In month view, the squares showing the days NOT in the selected month. Pink in the attached screenshot.
  • .datePickerCell_active - In the date picker, the date, week, or month you have clicked on. Shown in greenyellow in the attached screenshot.
  • .calendarViewPlanningOuterCell - in Planning view, the "empty" times. Shown as light green in the attached screenshot.
  • .calPlanningViewTitleTable - the "header" cells in the planning view. Labeled either "Availability" or with the name of the calendar being portrayed. Orange in the screenshot.
  • .planningViewOffWorkHoursDiv - In planning view, shows non-work hours in the divider between Availability and Calendar displays. Green (not light green) in the attached screenshot.
  • .planningViewOffWorkDaysDiv - In planning view, shows non-work days in the divider between Availability and Calendar displays. Affected by .calendarViewPlanningOuterCell. In the attached screenshot .planningViewOffWorkDaysDiv is set to red but .calendarViewPlanningOuterCell is set to lightgreen so .planningViewOffWorkDaysDiv shows up as brown.
  • .planningAvailabilitytDiv - In planning view, used in the Availabilty area to show the cumulative busy time of all displayed calendars. It shows up pale or muted. Set to red in the attached snapshot.

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 - this is where you will make most of your color changes. It is divided into sections that correspond to the other .css files as follows:
  • calendar.css
    • .upcomingAppointmentsDiv
    • .calendarViewHeaderCell - depending on the calendar view selected, this is day and date (day and week view), or day (month view). The attached screenshot shows it set to orange.
    • .dayWeekViewAllDayEntryCell - in day or week view, the end user can double-click this bar just beneath day/date and create an all-day entry. The attached screenshot shows it set to yellow.
    • .dayWeekViewAllDayFillerCell - the little cell to the right of the "all week" bar in a day or week view. The attached screenshot shows it set to blue.
    • td.monthViewEntryCell div.isSelected - the selected date in the month view of the calendar. Also affects a selected all-day appointment in the month view of the calendar. The attached screenshot shows it set to red color on purple background-color.
    • table.isSelected - a selected appointment or meeting in the month view of the calendar. The attached screenshot shows it set to purple on orange (very attractive :).
    • .dayWeekViewApptDiv - shows the beginning and end of appointments in the day or week view. The attached screenshot shows it set to green.
    • .dayWeekViewAllDayApptDiv -
    • .monthViewAllDayApptDiv -
    • .dayWeekViewApptBody -
    • .isToday - the color of today's date in day or week view; usually set to same value as .monthViewEntryCell .isToday. In the attached screenshot it is set to blue.
    • .monthViewEntryCell .selected - deprecated. Use td.monthViewEntryCell div.isSelected instead (available in 11.4.2 and more recent)
    • .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. In the attached screenshot it is set to red. Note that there is a bug which causes this color to revert to red if you click today, then another day.
    • .isNotToday - In day or week view, the color of the day and date that are not today. In month view, the color of date numbers that are not today. The attached screenshot shows this set to green.
    • .upcomingAppointmentHeaderCell -
    • .upcomingAppointmentTimeCell -
    • .upcomingAppointmentSubjectCell -
    • .calendarLoadingDiv
  • dragdrop.css
  • grid.css
    • .grid_container
    • .grid_scrollable_div - the background behind upcoming appointment reminders. The attached screenshot shows it set to purple.
    • .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. The attached screenshot shows it set to orange.
    • .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. The attached screenshot shows it set to yellow.
    • .menuShadow - color behind the drop-down menus. The attached screenshot shows it set to purple.
    • .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. The attached image shows this set to orange.
    • .menuItem_hover .menuItemCaptionCell - the item your mouse is hovering over in the drop-down menu. The linked image shows this set to green.
    • .menuItemShortcutCell - the "shortcut keys" in the menu, for example "control+<" for previous message. The attached image shows it set to red.
    • .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 orange.
    • .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 blue.
    • .menuItem_hover .menuItemRightIconCell - the cell to the right of the shortcut field. The linked image shows this set to purple.
    • .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 - divides the panes, for example the list of folders from upcoming appointments, or the list of messages from message preview. Shown in yellow in the attached screenshot.
    • .paneDividerOn - the pane divider turns this color when you click on it to resize the pane. Shown in green in the attached screenshot.
    • .pane, .messagepane, .appointmentspane - the color of the calendar or empty folders. Also shows up behind the folder list and message list when the client is loading. Does not affect planning view of the calendar. Shown in blue in the attached screenshot.
    • .bigTableResizer
    • .renamer - box when you are renaming a folder in the table. The linked screenshot shows it set to red.
    • .paneHeader - header for Folder list, Calendar list, Upcoming Appointments, Date Navigator. The linked screenshot shows it set to orange.
    • .messageHeader - the message header in the preview pane. The attached screenshot shows it set to yellow.
    • .miniCalendarPane
    • .textInputField - where you enter text, such as a name to search for when addressing a message by clicking the "to" button. The linked screenshot shows it set to light blue.
    • .messageRenderer - the message in the preview pane. The linked screenshot shows it set to pink.
    • .popdownButton -
    • .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. The linked image shows it in greenyellow.
    • .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. Set to red in the linked screenshot.
    • .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 - the un-highlighted messages in the message list. Set to light blue in the attached screenshot.
    • .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. The linked screenshot shows this set to orange.
    • .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. The linked image shows this set to yellow.
    • .tab_pane - the window where you create an appointment or meeting. Set to light blue in the linked image.
  • 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. The linked image shows it set to yellow.
    • .FreeBusyMeetingBody - where the busy time for the proposed meeting is displayed on scheduling tab when creating a meeting. The linked image shows it set to orange.
    • .FreeBusyMeetingLeftBar - in scheduling tab, this color is on the lefthand side of meeting busy time. Set to blue in the attached screenshot.
    • .FreeBusyMeetingRightBar - in scheduling tab, this color is on the lefthand side of meeting busy time. Set to light blue in the attached screenshot (difficult to see, zoom in).
    • .timePopStart, .timePopEnd, .fb_timePopStart, .fb_timePopEnd - on the appointment and scheduling tabs when creating a meeting, these buttons are used to pop up a list of start and end times. Shown in greenyellow in the linked screenshot.
  • 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)