This tutorial is a step-by-step guide to making a theme for Sunbird 0.3a1 and later versions. It is designed for beginners. It does not cover advanced topics.
You might be able to apply the same method to other Mozilla applications by changing some of the details.
Introduction
A theme is a package that users can install in an application to change the appearance of the application, without changing how the application works.
For example, a theme can change the size and colour of the toolbar buttons, and provide different icons on the buttons. But a theme cannot provide an extra button.
What do you need to make a theme?
To make a theme, you usually need these tools:
- A jar tool or zip tool
- An editor for plain text files
- Software for creating and editing images
Note: Some zip tools only work with files whose names have <tt>.zip</tt> at the end. You can use this kind of zip tool if you rename each file before and after using the tool.
You also need knowledge of:
- Using your operating system to create files and directories
- Using the tools listed above
- CSS
- Graphic design
Knowledge of XUL, XBL and JavaScript is useful for advanced themes.
Making a theme
A theme consists of:
- A unique identifier
- A file containing information about the theme
- A file that registers the theme with Sunbird
- Some files containing the theme itself
Set up your theme in Sunbird's profile directory. For information on how to find the profile directory, see the Mozillazine article: Profile Folder
Inside the profile directory, go to the <tt>extensions</tt> directory.
Note: If the <tt>extensions</tt> directory is empty, you are in the wrong place—start again and follow the instructions more carefully.
Creating a unique identifier
Create an identifier that is likely to be unique, in the form:
- <tt>something@domain-name</tt>
It must contain an at-sign (<tt>@</tt>), making it look something like an e-mail address, but it does not need to be a real e-mail address. Before and after the at-sign, it can only contain the characters A-Z, a-z, 0-9, full stop, hyphen and underscore. If you do not own a domain name, you can make up something else. If you want to make it clear that your made-up name is not a real domain, add <tt>.invalid</tt> to the end.
Create a new directory in the <tt>extensions</tt> directory. Use the identifer as your new directory's name. This new directory is your theme directory.
Go into your theme directory.
Creating information about your theme
In your theme directory, create a plain text file named <tt>install.rdf</tt>.
Copy and paste the content from here, making sure that you scroll to get all of it:
<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="http://www.mozilla.org/2004/em-rdf#">
<Description about="urn:mozilla:install-manifest"
em:id="just-testing@example.com"
em:name="Just Testing"
em:creator="Rod Whiteley"
em:description="A test theme for Sunbird"
em:homepageURL="http://developer.mozilla.org/"
em:version="0.1"
em:internalName="testing"
em:type="4" >
<em:targetApplication><!-- Sunbird -->
<Description
em:id="{718e30fb-e89b-41dd-9da7-e25a45638b28}"
em:minVersion="0.2.9"
em:maxVersion="0.4" />
</em:targetApplication>
</Description>
</RDF>
In the line that starts <tt>em:id</tt>, paste your identifier between the double-quote characters, replacing the identifier that is there now.
Change the next six lines to describe your theme.
Ensure that the internal name is a single word.
Note: If your theme is for a version of Sunbird later than 0.4, then also change the maxVersion.
Save the file.
Registering your theme
To register your theme, create a plain text file named <tt>chrome.manifest</tt>.
Copy and paste the content from here (just one line):
skin calendar testing chrome/calendar/
Change <tt>testing</tt> to your theme's one-word internal name.
Save the file.
Creating the theme itself
To create the theme itself, go to Sunbird's program directory.
Note: If you do not know where the program directory is, look at the properties of the shortcut or launcher icon that you use to start Sunbird. There you can see the location of the directory.
In the program directory, go to the <tt>chrome</tt> directory.
Use a jar tool or zip tool to unpack the file <tt>calendar.jar</tt> there.
Go to the <tt>skin</tt> directory that has just been created, then to the <tt>classic</tt> directory there. Copy the <tt>calendar</tt> directory that you find there.
In your theme directory, create a new directory named <tt>chrome</tt>.
Paste the copied <tt>calendar</tt> directory, together with all its contents, into your new <tt>chrome</tt> directory.
Now you have a theme, although it looks exactly the same as Sunbird's classic theme.
Modifying your theme
To modify your theme, change the CSS and image files in any way you like.
For testing purposes, go to the <tt>calendar</tt> directory that you have just pasted. Edit the file <tt>calendar.css</tt> there. Add this line at the end:
label {color: red;}
Save the file.
Fixing bug 320823
If you are using the Sunbird 0.3a1 release, or a test build before 2005-12-21, then you must apply a fix for bug 320823 to allow Sunbird to use themes.
Go to Sunbird's program directory, then to the <tt>defaults</tt> directory there. In the <tt>pref</tt> directory, edit the file <tt>sunbird.js</tt> and search for the <tt>pref("extensions</tt> entries. Add the line:
pref("extensions.dss.enabled", false);
Save the file.
Using your theme
To use your theme, restart Sunbird.
From the menu bar, choose Tools – Themes...
In the Themes window, check that your new theme has appeared.
Select it and press the Use Theme button.
Restart Sunbird again.
If your theme is working, you see the effect of the changes that you made.
Developing your theme
To develop your theme, make further changes to the theme files. You might prefer to do some design work in an image editor first, so that you have a clear design concept to implement.
Understanding Sunbird's user interface
To understand Sunbird's user interface, go to Sunbird's program directory, then to the <tt>chrome/content/calendar</tt> directory there. Examine the files there to understand how Sunbird's user interface is constructed.
The basic interface is written in XUL, but some parts are constructed using XBL or JavaScript.
To discover details of the interface, you can also use the DOM Inspector tool in Firefox. Install a compatible test build of the Calendar extension in Firefox 1.5, and examine its interface. The details are mostly the same as in Sunbird.
Note: Sunbird's views changed at the end of December 2005. So do not waste time styling the old views. Work with a recent test build so that your theme will be compatible with the next release.
Testing further changes
When you make further changes to your theme, test them by restarting Sunbird.
To detect errors, choose Tools – JavaScript Console... The JavaScript Console window displays CSS errors, not just JavaScript errors.
Making an icon and preview
The Themes window can display an icon and a preview graphic. You normally make these after you have designed the rest of your theme.
Make an image file 32 by 32 pixels, and save it as <tt>icon.png</tt> in your theme directory.
Make an image file about 200 by 100 pixels, and save it as <tt>preview.png</tt> in your theme directory.
Adding other components
Your theme only modifies the calendar component. Sunbird also contains communicator, global, help and mozapps components.
To add these to your theme, unpack the file <tt>classic.jar</tt> in Sunbird's <tt>chrome</tt> directory. From the unpacked <tt>skin/classic</tt> directory, copy the extra directories into your theme.
In your <tt>chrome.manifest</tt> file, add lines like this:
skin communicator testing chrome/communicator/ skin global testing chrome/global/ skin help testing chrome/help/ skin mozapps testing chrome/mozapps/
replacing <tt>testing</tt> with your theme's one-word internal name as before.
To understand the user interface provided by these other components, unpack the other jar files.
Packaging your theme
You can package your theme and make it available on a web site for other users to download and install.
There are two methods: a simple method, and the normal method.
Simple packaging
Note: If you use this simple method to package your theme, then it can take up much more disk space than it really needs. You might prefer to use this method only while you are developing your theme, and to use the normal method for public releases.
In Sunbird, use the default theme or some other theme.
Move your theme directory to a temporary location. This uninstalls it from Sunbird.
Use a jar tool or zip tool to pack the contents of your theme directory. It is usual to turn off compression so that your theme's speed is maximized. Make sure that the tool packs all the directories and files that make up your theme.
Name the packed file with the <tt>.jar</tt> extension.
For example, when I wrote this article I used this command in my theme directory:
zip -0r testing-0.1.jar .
Make this jar file available to users.
Normal packaging
In Sunbird, use the default theme or some other theme.
Move your theme directory to a temporary location. This uninstalls it from Sunbird.
Go to your <tt>chrome</tt> directory. Use a jar tool or zip tool to pack everything in your <tt>chrome</tt> directory into a file. It is usual to turn off compression so that your theme's speed is maximized. Make sure that the tool packs all the directories and files that make up your theme.
Name the packed file with the <tt>.jar</tt> extension.
For example, when I wrote this article I used this command in my <tt>chrome</tt> directory:
zip -0r testing.jar .
Go back to your theme directory and edit the file <tt>chrome.manifest</tt>.
Change the line for the calendar component to:
skin calendar testing jar:chrome/testing.jar!/calendar/
and make the corresponding change in any other lines that you added.
Save the file.
Use a jar tool or zip tool to pack the files in your theme directory together with your <tt>.jar</tt> file. It is usual to use maximum compression so that users can download your theme quickly. Make sure that the tool does not pack any component directories.
Name the packed file with the <tt>.jar</tt> extension.
For example, when I wrote this article I used this command in my theme directory:
zip -9 testing-0.1.jar * chrome/testing.jar
Make this jar file available to users.
Installing a packaged theme
Install your packaged theme in the normal way, by dragging the jar (or a link to it) and dropping it in Sunbird's Themes window.
Select the newly installed theme and press the Use Theme button.
Restart Sunbird.