Create a New Theme

• Home
• Extensions
• Themes
• Translations
• Contribute
• Resources

[edit] Setting up your theme workbench.

[edit] Prerequisites:

Ok so you're here to start theming, but there are a few things we need to get going first. We need to setup a workbench for you to easily develop and test your themes, and, when you're ready, deploy them. However, to do any of this, you're going to need a set of tools to do your magic. More importantly, you're going to need the knowledge to do so.

[edit] Help?:

If you have any problems with this document, or you need some help with a certain step, please contact the author (me) at: brij at flock dot com. Thank you, and enjoy!

[edit] Files of Interest

You'll need to download the appropriate file for your platform. These base themes are templates for you to create your own theme :)

• Flock Base Theme (1.1) for Win32/Linux
• Flock Base theme (1.1) for Mac OS

[edit] Software Tools:

Creating a theme is a very visual process, there are some basic software tools you'll need.

[edit] Image Editors:

A good image editing program is a must, here are some examples:

Adobe Photoshop:

The one ring to rule them all. Lord of the Rings jokes aside, Photoshop is a great application, but it ain’t cheap. If you've got a big wallet, this app will be the end-all for your graphics needs. Not only can you do theming graphics, but you can also do extensive photo editing, print-based graphics, digital painting, and more.

Photoshop has good vector editing capabilities, but only supports one layer effect at a time (you'll see what I mean when you read on).

• Photoshop has HTML Export with slicing (with Adobe ImageReady)
• Photoshop has excellent Wacom Stylus support.

Adobe Fireworks:

My personal favorite; I ended up switching from Photoshop to this app. Its great. Features WYSIWYG vector editing, and now features both Fireworks layer effects, and Photoshop layer effects. Also improved (but still not perfect) Photoshop importing.

• Fireworks is far cheaper than Photoshop, and it only focuses on a particular area of the market, which is web graphics, and layout design. It's definitely NOT a photo editor, and doesn't try to be.
• It can easily create visual mockups, and supports multipage layouts (new in v9).
• Supports HTML export with slicing (built in)
• Has multi-layer, and nested layer support (new in version 9, aka CS3).
• Has support for multiple layer effects, per layer, and a single set of Photoshop layer effects
• Pre-set styles (handy for creating theme widgets, or using them as a base for your own), these can apply to basically any vector object.
• Has limited Wacom Stylus support.
• Version 8 runs in Wine, but not perfectly. See Wine-db for more info.

The Gimp:

This is a great app, but in my opinion, not recommended for doing theming. It does have great photo-editing abilities, but its major loss is that it doesn't support the creation of Vectors. If you draw something, its very hard to re-edit that later.

Does this mean you're at a loss for using the gimp? No, you 'can' still theme, but it isn't going to be easy, and its going to take you some time.

• Get a companion vector editing app, that can rasterize its graphics, or atleast put the graphics in a format that the Gimp can read. I think Inkscape can do this, but I'm not 100% positive.
• Get the layer effects script-fu for the gimp (Google is your friend); it’s very limited, but may help you do basic operations like drop shadow, stroke effects, etc. Its still bitmap based, so once you apply the effect, you'll have to basically undo to fix it.
• Use the path of the light side....I mean, use the bitmap paths in the Gimp, they are still editiable later on, and combined with gradients, and layers, you can fake an editable vector. Like I said, it’s not easy.
• Has very good Wacom Tablet support.
• In the end, it's just going to take some time. But be aware that the Gimp is going to take longer, and won't achieve the same results as apps such as Photoshop and Fireworks.

[edit] Text Editors:

Ok, now image editing isn't everything. You're gonna need some good text editors. Something with syntax highlighting would be good, because it can help catch some of those silly errors.

Note: I don't mention every editor, nor do I mention all the best ones. These are just some I know and have used. Feel free to google around for other editors.

Here are some examples of good text editors:

• Vi/Vim/Emacs/Pico - Win/Linux/Mac:
  • Console world unite, all will get the job done.
• Kate – KDE:
  • VERY good text editor. This is my favorite on Linux right now, I switched from G-edit. Supports tabbing, view splitting (with two different files), line-based bookmarking, saved sessions (so you can save a session for each theme your working on), integrated shell/console, file browser, and autocomplete that works with XUL (whoohoo!).
• G-Edit – Gnome:
  • Good editor, but lacks some of the cooler features I use a lot, like view splitting.
• Ultraedit – Windows:
  • This editor is basically identical to Kate in functionality, except for the XUL autocomplete. Very powerful though, the best in my opinion for windows, but not free.
• Crimson – Windows:
  • Very Powerful, and free. Similar to Kate, not quite as many features...but very close.

[edit] Other Utilities:

Now you've got your tools to make your images, and create your CSS. So you're done, right? No! You need to package that...but with what? What you’ll need is a good archiving/compression app that supports the zip format. I'm not going to list them off, because there are just WAY too many of these. Basically you just need something that can create a zip file, and retain the zip structure of that zip.

One more app you're going to need, and will be absolutely valuable for your theming is the DOM-Inspector from Mozilla. This app will allow you to inspect various UI elements for discovery, and debugging. It allows you to see the associated CSS, javascript, and box model of any element within the browser chrome.

[edit] What you need to know:

So you've got your super-1337 kit of software, but you need to know how to use it! What you'll need to know is:

• How to use an image editor, and have some creativity to actually be able to conceptualize and draw out graphics.
• How to use CSS, and Mozilla CSS (Google is your friend!).
• How to to use basic file operations, such as directory manipulation, text editing, archiving zip files, etc.
• Have a basic understanding of XUL, and how it’s laid out.
• Knowing the DOM-inspector is handy.

[edit] Setting up your workbench

[edit] Creating your Directory Structure:

First of all, we're going to need to setup a directory structure to store your theme. Let’s create a directory called “projects” on your hard drive.

Please place it in one of the following areas based on your Operating System:

• c:\projects\ (win32)
• /home/<your username>/projects (mac/unix/linux)

So you're going to want to place your theme projects in this directory, in the following section, we will do so.

[edit] Extracting the theme:

You'll need to download the Flock base theme from here. When you have the theme (which will be in jar format), place it in the projects directory. So you'll have a directory structure like this:

• projects <base dir>
  • flockbasetheme.jar

What you'll now need to do is extract the theme. You can do this in two ways:

• Rename the 'jar' extension to 'zip' and extract the theme
• Or, setup your compression utility to automatically extract jar files.

When your file is extracted, you should have the following file structure:

• projects <base dir>
  • flockbasetheme.jar (or zip)
  • flockbasetheme <dir – your extracted theme dir>
    • chrome <dir>
      • browser <dir>
        • too many contents to list...
      • communicator <dir>
        • too many contents to list...
      • global <dir>
        • too many contents to list...
      • help <dir>
        • too many contents to list...
      • mozapps <dir>
        • too many contents to list...
    • chrome.manifest <text file>
    • icon.png <theme icon>
    • install.rdf <xml/rdf file>
    • preview.png <preview image for theme>

This looks complicated, but read on and we'll explain what everything is.

[edit] Examining the File Structure:

[edit] What the deuce is this stuff?

Glad you asked. So what we did was extract what we call a 'base theme'. This theme is the current theme for the build you downloaded. (there is a base theme for each version) This theme will give you template to create your own Flock Theme.

[edit] The Install.rdf, and what it can do for you!:

The install.rdf is the main file that describes your theme. It provides important meta and install information about your theme. Figure 1 shows an example of this file:

<?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">
    <!-- Unique Theme ID -->
    <em:id>flockbasetheme10@flock.com</em:id>
    <!-- Theme Version Number -->
    <em:version>0.1.0</em:version>
    
    <!-- Flock Browser Compatability --> 
    <em:targetApplication>
      <Description>
        <em:id>{a463f10c-3994-11da-9945-000d60ca027b}</em:id>
        <em:minVersion>1.0</em:minVersion>
        <em:maxVersion>1.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
    
    <!-- Front End MetaData -->
    <em:name>flockbasetheme10</em:name>
    <em:description>The Basic Flock Theme - Ver 1.0</em:description>
    <em:creator>Brij Charan - brij@flock.com</em:creator>
    <em:contributor>Based on Classic Theme from Flock 1.0</em:contributor>
    <em:homepageURL>http://www.flock.com/</em:homepageURL>
    <em:updateURL>http://www.flock.com/updates/flockbasetheme10/update.rdf</em:updateURL>

    <!-- Front End Integration Hooks (used by Theme Manager)-->
    <em:internalName>flockbasetheme10</em:internalName>
  </Description>

</RDF>

Now let’s describe each section of the install.rdf file. We'll cover the ones you'll need to change, the others you can ignore for now.

Unique Theme Id:

• em:id:
  • This is your unique id for your theme, to differentiate it from other themes. This can really be whatever you want, but currently follows the form of an e-mail address.

Theme Version Number:

• em:version:
  • This is the version number of your theme. You create this number, so it can be anything you'd like, but you should stay within the guidelines found here at MDC.

Flock Browser Compatibility:

• em:id:
  • The GUID of the Flock browser. - This has to match the Flock GUID, or this theme won't install in flock. The default value in this base theme is correct.
• em:minVersion:
  • Minimum version number of Flock that this theme is compatible with.
• em:maxVersion:
  • Maximum version number of Flock that this theme is compatible with.
  • Because your base theme has these values set, it's a good idea to 'not' change these numbers, as your base theme is already good to launch.

Front End Metadata:

• em:name:
  • This is the name of your theme; it can be whatever you like.
• em:description:
  • Your theme description. Please make it descriptive so users know what your theme is about.
• em:creator:
  • This is you! Put your name here :)
• em:contributor:
  • The names of the contributors of the theme. People who originally designed it or the company.
• em:homepageURL
  • The homepage URL of the theme
• em:updateURL
  • The URL where your themes update.rdf is located (if you don't know what that is, don't worry, I'll explain later.)

Front-End Integration Hooks:

• em:internalName
  • The internal name of your theme.
  • VERY important. You need this to refer to your theme in your chrome.manifest.

[edit] The Chrome.manifest (of destiny):

Take a look-see at Figure-2: you'll see a new type of file that may be a little confusing.

This is the chrome manifest, it allows your theme to link a chrome url to a physical location in your directory structure.

Chrome URLS from a chrome.manifest: A chrome url is a special addressing system used in Mozilla applications. For themes we use this url to refer to different images and CSS files. In figure 2, we setup our chrome urls through our chrome manifest file. Our first line refers to the global package of flocks theme. chrome provider: skin package name: global localname/internalName: flockbasetheme10 path to files: chrome/global/ Here is how that line would look when referencing it as a chrome URL: chrome://flockbasetheme090/global/skin/<filename.css|img> To learn more about the Chrome Registration system, please go to MDC's Chrome Registration page.

 skin    global            flockbasetheme10    chrome/global/
 skin    help              flockbasetheme10    chrome/help/
 skin    mozapps           flockbasetheme10    chrome/mozapps/
 skin    browser           flockbasetheme10    chrome/browser/
 skin    communicator      flockbasetheme10    chrome/communicator/

This chrome.manifest file links your theme to the various packages in the chrome that are used for styling. You can do other modifications to your chrome.manifest like overlays, but that is beyond the scope of this document. You can learn more at the MDC Chrome Registration page.

[edit] The Chrome Directory:

So you've seen the all the files in the root of the base theme, but we haven't looked at this mysterious chrome directory much. Well we will, but we need to do some directory setup before we get more into the chrome structure.

[edit] Setting up Your Workbench:

So now we have an idea of the files that help define a theme.

What we're about to set up is called...well, it’s not really called anything. We'll call it a pointer theme. This pointer theme is not like a traditional theme, because it refers to a directory structure instead of a jar. Why would we want to do this? Simple: this keeps you from having to uncompress a jar, make your changes, recompress the jar, then re-install the jar each time you make a change.

With a pointer theme, all you need to do is place your pointer file in your profile, then launch your browser, select the new theme, restart, and you're good to go. Whenever you make a change, you simply restart your browser to see those changes apply. Much easier than recreating the jar file every time, don't you think?

[edit] Customizing your theme properties

Now that you have gone through the structure of your flockbasetheme, its time we individualize it.

What we're going to do now, is change the names for your theme to your first Flock theme. We will modify the following attributes:

• The Install.rdf
  • We're going to need to change a few attributes here
• The Chrome.manifest
  • Also needs a name change
• The Directory Name
  • We need to keep the same name structure

[edit] Exercise #1 – Customizing your Theme Properties.

1. Go to your project directory.
   We're going to have to change the directory name of your Flock base theme to something more appropriate.
   
   So here is what the path to your theme will look like:
   • c:\projects\flockbasetheme\ (win32)
   • /home/<your username>/projects/flockbasetheme/ (mac/unix/linux)
2. We don't want your new theme to be called the flockbasetheme, so let’s rename that to firstflocktheme.
   
   So our new path will look like:
   • c:\projects\firstflocktheme\ (win32)
   • /home/<your username>/projects/firstflocktheme/ (mac/unix/linux)
3. Now let’s edit your install.rdf file with your text-editor.
   1. Change your em:id from flockbasetheme10@flock.com to firstflocktheme@flock.com.
   2. Change the em:name from flockbasetheme10 to firstflocktheme.
   3. Change the internal name from flockbasetheme10 to firstflocktheme.
   4. Save and close install.rdf.
4. Now edit chrome.manifest with your text-editor.
   1. Change all instances of flockbasetheme10 to firstflocktheme.
   2. Save and close chrome.manfiest.

Now we're done with exercise one, we've customized your Flock base them to now be called firstflocktheme. Now onto our next exercise.

[edit] Creating a pointer file:

The first thing you'll need to do is create a pointer file, with an absolute path to your theme directory.

So our path will look like (we created this in our previous exercise):

• c:\projects\firstflocktheme\ (win32)
• /home/<your username>/projects/firstflocktheme/ (mac/unix/linux)

Now that you have your path correctly setup, we're going to create a pointer file.

ATTENTION!: When you create a pointer file, you refer 'DIRECTLY' to your Flock theme directory. So if you uninstall that theme, your browser will 'remove' your theme, and also remove your directory! So always backup your theme when you do a change, and never 'Uninstall' your pointer theme without being absolutely sure that you want to remove that directory as well.

[edit] Exercise #2 - Creating a pointer file.

1. Exit out of Flock.
2. Go to the root of your theme directory.
   • c:\projects\firstflocktheme\ (win32)
   • /home/<your username>/projects/firstflocktheme/ (mac/unix/linux)
3. Create a new file with a name that is the same as em:id that you created in your install.rdf.
   (Note: It should be something like firstflocktheme@flock.com. )
   So you will now have a file called firstflocktheme@flock.com, and it will be sitting in your firstflocktheme directory.
4. Now please open this file in a text editor of choice:
   Note: You may get a warning stating that you're editing a binary file, but this is because the extension is 'com', which usually refers to an executable. In our case this is just a text file, so ignore any warnings.
5. Now type in (or paste) the path to your theme directory in this file.
   Note: Your path will be something like c:\projects\firstflocktheme\ (for win32 systems), or /home/<username>/projects/firstflocktheme/ (for mac/unix/linux systems).
6. Save your file, and close your text editor.
7. Now go to your current profile directory.

   Finding your Profile directory: The following examples where your profile 'might' be located on your system. Not all systems are the same, so these locations may not be 100% accurate. For win32 systems: *C:\Documents and Settings\<username>\Application Data\Flock\Browser\Profiles\<profile-id>\ (Application Data is usually a hidden file in win32 systems. So, adjust your view folder type to show hidden files) this may not work for all users, the other folder containing the data we need is: *C:\Program Files\Flock\Flock (this is the folder where you installed Flock) For Mac systems: */Users/<username>/Library/Application Support/Flock/Profiles/<profile-id>/ For Linux systems: */home/<username>/.flock/browser/<profile-id>/ <username> refers to your current username. <profile-id> refers to the unique directory name for your profile, it will usually be some alphanumeric sequence like: 6hfuuz82d.default Note: Windows has a Browser & Profiles directory, the Mac has only Profiles, and Linux has only browser.

   So now you've found your profile directory, there will be a lot of files and directories in here, but we're only interested in one, extensions.
8. Open the extensions directory.
   Note: This directory may have other contents in it, or it could be empty, it depends on your profile. It's irrelevant at this point on what’s inside the extensions directory.
9. Now copy the pointer file – firstflocktheme@flock.com (or whatever you called it) – to your profiles extensions directory.
10. Start up Flock, and go to the menu Tools, and click Add-ons.
    Note: You'll be presented with a dialog similar to Figure – 3 .

    Figure - 3

11. Select the firstflocktheme if its not already selected, and click 'Use Theme'.
    Note: When you click 'use-theme', you will see text saying to restart Flock.
12. Close the add-ons dialog, and quit Flock.
13. Start Flock.
14. You will now have your new theme loaded!

Now we've setup your workbench! You are almost ready to start modifying the CSS/images. But there are a few things we need to cover first before we move forward.

[edit] Understanding the Chrome Directory:

The chrome directory contains all the CSS and images necessary to build your theme. This is where the real magic happens.

To effectively change the look of our browser, you'll need to know some CSS and image manipulation. You will also need to know roughly what areas of the CSS relate to which visual area in the browser. Well, you're in luck: I've created a map for you!

Please refer to Appendix-A to see a map that shows the various areas of the chrome. After the map there is a table which gives paths to images and CSS files where the outlined areas are defined in the theme.

[edit] Setting up a custom CSS file and assets directory:

When doing work on a theme, it's more modular to put your CSS in one or more separate files, and avoid modifications to the core theme files. This allows you to quickly update your base theme without having to go through a complicated merge process with every CSS file.

[edit] Exercise #3 – Creating a custom CSS file and asset directory:

1. Quit Flock.
2. Open the browser chrome directory.
   • c:\projects\firstflocktheme\chrome\browser\ (win32)
   • /home/<your username>/projects/firstflocktheme/chrome/browser/ (mac/unix/linux)
3. Create a new text file called custom.css in the browser directory. Note: This file is empty for now.
4. Load up the browser.css file in the browser directory.
   1. Add the following code to your file (new code is marked bold):

      44 45 46

      @import url(chrome://browser/skin/tabs.css); @import url(chrome://browser/skin/custom.css); ...

   2. Save and close the browser.css file.
5. Now from the same location – the browser directory – create a directory named custom.

You now have your own custom CSS file to work with, as well as a custom asset directory to put your custom images in.

[edit] CSS Magic:

Ok, so now that we have a rough idea where everything is, and your theme is now loaded as a workbench, its time to start modifying our theme.

[edit] Understanding the Image Regions and Image Matrices:

So what is an image matrix? Well an image matrix is a large matrix (or grid) of images that represent icons used in the chrome of the browser. The browser uses custom CSS to pull 'regions' of these matrix sets out to display. Figure – 4 shows an example of how image regions are laid out.

The image on the left illustrates how an image region is laid out. Suppose the light blue area is the image, which in the diagram starts at x/y coordinates 0,0. The matrix has 3 images for a back button, so to utilize this image without having to cut it, we pick virtual regions from the image. So for the first normal state, our virtual region is a box that starts from the top left at x:0px, y:0px; and ends at the bottom right at x:80px, y:80px. Let’s assume this image is called back-button-matrix.png, and it sits in our new custom directory. Refer to Figure – 4b for a CSS example of how this would look like mapped (regions) in CSS, please refer to the image for help.

Figure - 4

 001
 002
 003
 004
 005
 006
 007
 008
 009
 010
 011
 012
 013
 014

 #back-button {
   width: 80px; height: 80px;
   list-style-image: url(“chrome://browser/skin/custom/back-button-matrix.png”) !important;
   -moz-image-region: rect(0px 80px 80px 0px);
 }
 #back-button:hover {
   list-style-image: url(“chrome://browser/skin/custom/back-button-matrix.png”) !important;
   -moz-image-region: rect(100px 80px 180px 0px);
 }
 #back-button:active,
 #back-button:active:hover {
   list-style-image: url(“chrome://browser/skin/custom/back-button-matrix.png”) !important;
   -moz-image-region: rect(200px 80px 280px 0px);
 }

ATTENTION!: When you create your image regions in CSS, you must make sure that your width/height for your button matches the image region, otherwise you'll get some really bizarre rendering errors.

[edit] Packaging a theme:

So once you've finished your theme, what do you do? Well you're probably going to want to show your buddies the magic you've done, but your theme is stuck on your machine...and you sure can't make a pointer to your theme over the internet.

(well, I'm sure you could make a theme pointer file over the internet somehow, but that’s really not in the scope of this document)

So let’s go back to your jar structure. There are really two ways of packaging your themes:

• Single Jar – One Jar to rule them all!
  • Personally I prefer this method, as it’s quicker to do, and yields the same results. In theory it may load faster as well.
• A multi-jar
  • Uses a main jar file, and embedded jar files within that jar.

I'm not going to cover multi-jar mode here. If you wish to learn more about it, please search on MDC for the extension packaging tutorials. (HTTP://developer.mozilla.org/)

[edit] Single Jar:

So to jar your files in a single jar mode, you need to open up the root of your theme.

• c:\projects\firstflocktheme\ (win32)
• /home/<your username>/projects/firstflocktheme/ (mac/unix/linux)

Take your favorite compression utility(Winzip, Winrar, Archive for mac, zip/unzip for linux), compress the following directories and files in a zip:

• chrome <directory>
• icon.png
• preview.png
• chrome.manifest
• install.rdf

Note: Make sure you have the option to maintain directory structure enabled in your zip compression utility, as we need this structure to stay intact.

Now that we have our zip file, we're going to need to change its extension from zip to jar. So your extension should be called firstflocktheme.jar.

Now your theme is ready to deploy. So send it to a friend!

===ATTENTION!:=== Don't install this jar in the same profile as the workbench, as it will overwrite the workbench, and possibly destroy your workbench directory

[edit] Appendix

[edit] Appendix – A

Flock Chrome Layout and Legend.

• This page was last modified 23:20, 14 August 2008.
• About Flock Developer Portal
• Disclaimers