[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread


I have received permission to mirror this info. This is the property of Ed Hume, and the info alone is his. Please do not contact me because of it.


Post #1

This thread is about how to get into making themes. I hope that other themers will add to it. Since Firefox 2.0 has been released, I have updated the instructions.

This thread is about how to get started in theming Firefox 2.0 and later. It is what I wish I could have found four years ago, when I started theming.

Before we start, there is one essential tool you must have: the DOM Inspector. DOM stands for Document Object Model, which is the blueprint for what you see in your browser layout. If you installed Firefox with Developer Tools, you will have the DOM Inspector.

• If you have it, you will find it in your Tools dropdown menu.
  
• If you do not have it, reinstall Firefox, using the Custom install method. Make sure you include the developer tools in your installation.

Now, to start on your theme workshop:

One great thing about Firefox 1.5 and 2.0 is that you can set up a theme directory (call it a workbench) where you can make a change, close the browser, and when you reopen it you can see your change immediately. What follows is how to set this up.

OK, let’s start by setting up a workshop. Create a directory like C:\aa-theme. This will be near the top of your directory listing. Or you can play around with other names, or make a shortcut to your workshop directory. Just make it easy to get to.

Now pick a theme you want to base your theme upon. Or just pick one you are going to explore.

If you want to base your theme on another theme, consider what size icons you want. The Firefox default theme uses 24x24-pixel icons for the large toolbar buttons, and 16x16-pixel icons for the small toolbar buttons. Other themes use larger icons. Pick one where you like the icon sizes.

This post has been edited by Seamaiden: 16 July 2008 - 11:41 PM

[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread

Post #2

Now we play with a theme.

First, you must understand that themes come packaged in compressed files, called jarfiles. They typically have names like thistheme-1.2.3-fx.jar. The .jar extension signifies that the file is a Java archive. They are not always compressed, but we will not be dealing with uncompressed jarfiles.

When you want to look inside a jarfile, you can use a program like 7-Zip or IZarc. There are others that work also, even Windows' own file compression utility - but setting that up to open jarfiles is outside the scope of this thread. The important thing is that you set up your compression/decompression to recognize jarfiles, since it will save you much time.

When you look inside a theme's jarfile, you will either see a file called contents.rdf or chrome.manifest.

Pick a version of a theme you want to work with that has chrome.manifest, if you can.

• If you must pick one that has contents.rdf, use the instructions in this post.
  
• If you have a theme that has chrome.manifest, skip to the next post.

For contents.rdf themes, install the MR Tech Local Install extension and your theme in Firefox 2.0 (you will need the extension for the next step). Close and reopen the browser.

Open Tools > Add-ons > Themes. Select your theme. Right-click on it to get the context menu, and select Browse Install directory (we get this from the Local Install extension). You will now be in the installation directory of your chosen theme. Do a control-a or command-a to select all, and then copy everything in the directory. Now move to a workshop directory and paste everything you copied to that directory.

The reason you have to do this is because contents.rdf themes do not come with a chrome.manifest file. You must install the theme to let Firefox generate a chrome.manifest file. It also generates the chrome directory. The original jarfile is inside the chrome directory.

This post has been edited by Seamaiden: 27 October 2007 - 02:04 PM

[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread

Post #3

Now is a good time for those who started with a chrome.manifest theme to unpack the jarfile. It is true that you can work entirely within the jarfile without decompressing and recompressing it; but if you want to do that you can do it later. For now, I want to keep us all working on the same structures.

Note - The theme structure we are going to discuss is a chrome.manifest theme. If the theme structure you see is not what is described in this post, it is likely to be a contents.rdf theme.

• If the theme you have chosen is a contents.rdf theme, go to the post above and follow those directions.
  
• If the structure of your theme does not match what is described below, go to the post above, then rejoin us here.

About compression utilities: If you have Windows as your OS, you can use Windows’ own compression utility simply by renaming the jarfile from thistheme-1.0-fx.jar to thistheme-1.0-fx.zip. This gets old fast.

Of compression utilities, I have found that IZArc is the easiest to use. With this compression utility I can go inside a jarfile without changing its extension. I can open a file inside the jarfile and change it; when I close the file - still compressed inside the jarfile - IZArc will ask me if I want to apply the changes. I usually say yes (7-Zip also does this). The other thing - and this puts it ahead of WinRAR for me - is that I can set the default output filetype to be a jarfile, saving me some steps.

Whatever you are using, unpack (decompress) the theme’s jarfile now (if you started with a contents.rdf theme, Firefox has already done the first decompression, so you do nothing at this step).

Now, whether you started with a theme compatible with a contents.rdf theme or a a chrome.manifest theme, you should now have a working directory that looks like this:

Code:
(thistheme-1.0-fx.jar)
   chrome (a directory)
   chrome.manifest
   icon.png
   install.rdf
   preview.png

What Firefox does when it installs the theme is to read the install.rdf file to learn what to call the thing, what version number to give it, and whether it is compatible with that version of Firefox. It then reads the chrome manifest to learn where to find the various directories of the theme structure. The icon.png and preview.png files are graphic images (png = Portable Network Graphic) that the Themes Manager uses.

(An aside: The icon image should be 32 pixels tall and 32 pixels wide. If not, it will be squished or stretched to that size. As for preview.png, varying sizes work, but something around 200x150 pixels does not abuse your system.)

The chrome directory in an installation package contains just this: another jarfile. With contents.rdf themes, this is the original jarfile, from which Firefox has extracted install.rdf and the graphics files. It generates its own chrome.manifest file from a file inside the original package.

***

Now your theme needs in ID. There are two methods. Method A is clumsy. Method B is easy and easy to use. I have gone over to Method B, but take your choice.

Theme ID, Method A:

Find a GUID generator (GUID stands for globally unique identifier). You can Google around to find one. You can go here or here for web-based GUID generators. Or you can go to Microsoft’s GUIDGen page and download their GUIDGen utility.

Theme ID, Method B:

Make up an email address. Examples are HiVisGnome@edhume.googlepages.com, silvermel@pardal.de, toolbarcontrol@webdesigns.ms11.net (the ID of an extension), etc. You can see why I recommend this method of making an ID.

***

Now we look at the install.rdf file. We will use SphereGnome as an example.

Inside spheregnome-1.5.0.1-fx.jar you will find the structure listed in the codebox above.

Inside install.rdf you will find:

Code:
 <xml>

<RDF>

  <Description>
    <em>{ded0fc70-7215-4802-afeb-b2982d3e7225}</em>
    <em>1.5.0.1</em>
   
    <Target>
    <em>
      <Description>
        <em>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em>
        <em>1.4.1</em>
        <em>1.5.0.*</em>
      </Description>
    </em>
   
    <Front>
    <em>SphereGnome</em>
    <em>A cool theme with pleasant colors. The buttons light up when you pass over them, and change color or change picture when you click on them. The icons are 24x22 and 32x32, making the theme usable for higher-resolution displays. It is also scalable, so if you set your system font to 125% or even 200%, SphereGnome will expand with it. NOTE: To get a dropdown history from a forward or back arrow, right click on it. It's much easier than trying to stab at a little dropdown marker.</em>
    <em>Ed Hume (edhume@gmail.com)</em>
    <em>Original theme created by Ken S. Lynch.</em>
    <em>BlueSphere SVG Icons and others by Vadim Plessky, [url="http://svgicons.sf.net</em>"]<a href="http://svgicons.sf.net</em>" target="_blank"><a href="http://svgicons.sf.net</em>" target="_blank">http://svgicons.sf.net</em>[/url]</a></a>
    <em>Additional Tombats font icons by Tom Murphy, [url="http://fonts.tom7.com</em>"]<a href="http://fonts.tom7.com</em>" target="_blank"><a href="http://fonts.tom7.com</em>" target="_blank">http://fonts.tom7.com</em>[/url]</a></a>
    <em>http://www.geocities.com/edhume/</em>

    <Front>
    <em>SphereGnome</em>
  </Description>     

</RDF>

The {ded0fc70-7215-4802-afeb-b2982d3e7225} line refers to the ID of the theme, in this case a GUID. I made this ID before I learned about email-style ID's.

The {ec8030f7-c20a-464f-9b0e-13a3a9e97384} line refers to the GUID of Firefox.

You can see the version of the theme, and the minimum and maximum versions of Firefox with which this theme is compatible.

You can also see the official “name” of the theme. This name can have spaces and apostrophes, but don’t use apostrophes: when I used an apostrophe in the “Hallowe’en” theme, Mozilla Update choked on it at the oddest times. I had to rename it “Halloween”. Other names that work are HiVis Big (notice there is a space in the name) and SphereGnome_Big.

Note that the “internal name” should not have spaces or any characters except letters, number, hyphens and underlines. Thus HiVis Big becomes HiVisBig, etc.

You can see where I have given credit to the originator of the theme and the original sources of the art used in the theme. Of course, I made some icons myself, but anyone looking at the originals would be able to tell where I made new ones.

For your work-in-progress, make up a new name (for example My Theme) and put it in the install.rdf file in place of the original theme’s name. Then make a compatible character string for the internal name (for example MyTheme).

Using whichever method you choose, make an ID and paste it into install.rdf in place of the theme’s ID. Do not touch the targetApplication GUID, or your theme will not work on Firefox.

Now for chrome.manifest. Here is chrome.manifest from SphereGnome 1.8:

Code:
skin   global      SphereGnome   jar:chrome/chrome.jar!/global/
skin   help         SphereGnome   jar:chrome/chrome.jar!/help/
skin   mozapps      SphereGnome   jar:chrome/chrome.jar!/mozapps/
skin   browser      SphereGnome   jar:chrome/chrome.jar!/browser/
skin   communicator   SphereGnome   jar:chrome/chrome.jar!/communicator/

The first column tells Firefox this relates to a theme. The second column refers to the internal directories of the theme. The global, help, mozapps and browser directories are default directories from Firefox. The communicator directory is a fossil that supposedly does not need to be there. But once I took it out and my theme didn’t work. OTOH, that was long ago. Perhaps now I’ll try bundling up a theme without it and see how it goes.

The third column refers to the internal name of the theme. Get this right or you get “interesting” results when you install your theme.

The fourth column tells Firefox where to find the various internal directories.

Here, chrome.manifest is telling Firefox is that all of the directories will be found inside the compressed jarfile chrome.jar that is located inside the chrome directory. I have never tried mixing compressed with uncompressed directories, or having different directories in different jarfiles. I don’t know if it will work. I keep them all in one jarfile because it is faster for Firefox to read a smaller compressed file from the hard drive and decompress it in RAM than it is for Firefox to read a longer set of uncompressed files from the hard drive and use them directly.

You will notice that unlike the Firefox-generated chrome.manifest from a contents.rdf theme, the chrome.manifest from this theme does not have a version number. I did this to avoid having to change my chrome.manifest file every time I do a point upgrade.

So go into the chrome.manifest file of the theme you have chose and replace its internal name (e.g. - ThisTheme) with your own (e.g. - MyTheme).

Note - if you go inside the chrome directory and select all of its contents, then when you right-click to get your context menu, your compression utility will offer to let you create chrome.zip or chrome.jar. This is infinitely better than giving it a custom name, since it saves time and potential for errors.

Congratulations. You have just made a potentially installable theme.

In fact, let’s test it. I have an ulterior motive here - actually, two ulterior motives - so do this.

This post has been edited by Seamaiden: 27 October 2007 - 02:16 PM

[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread

Post #4

You are now inside your workshop directory. Make a new folder and name it something like mytheme-0.0-fx.

Now collect everything else in the directory and put it inside mytheme-0.0-fx. Then go inside it.

Inside the mytheme-0.0-fx directory you should have:

• install.rdf
  
• chrome.manifest
  
• up to two png files, and
  
• a chrome directory which contains another jarfile.

Select everything inside the directory, and right-click to bring up your context menu. If you are using IZArc, select the IZArc menuitem. Depending on how you have set up IZarc, you will then see a submenu which leads you to choices, or a menuitem that says “Add to mytheme-0.0-fx.zip” or “Add to mytheme-0.0-fx.jar”. If you have set IZArc up to put out jarfiles as a default, you will see a menuitem that says “Add to mytheme-0.0-fx.jar”. Select that.

If you are using another compression utility, follow the method for that utility. If you are using the built-in Windows compression utility, select the option that automatically adds the selected objects (everything inside the directory) to mytheme-0.0-fx.zip, then rename the resulting file to mytheme-0.0-fx.jar.

Why do it this way?

Because if you were inside your workshop directory and merely selected the mytheme-0.0-fx directory, you would get a jarfile with a mytheme-0.0-fx directory inside it - in essence another layer of directory structure. Since Firefox is not expecting this additional directory layer, such a theme would not install (trust me on that; it was one of my earliest mistakes). Teaching you how to properly use a compression utility was my first ulterior motive in getting you to do this test run.

Now for the smoke test.

Go to the Tools dropdown menu and select Themes. This will open the Themes Manager window. Drag your new theme to the left pane of the Themes manager window. Your theme should take its place in the Themes list. Select it and click on the Use Theme button. Close Firefox and reopen.

Why do I call this a smoke test?

Well, the term derives from when people hand-build electrical or electronic devices. The smoke test came when you plugged it into the wall and turned it on. If nothing smoked, burned popped, etc., then it passed the smoke test.

If it fails the smoke test, close the browser (you may have to force it with ctrl-alt-del or the equivalent).

The most common failure I have run into are these two:

• The second column of the chrome.manifest file is not exactly the same as the internal name in the install.rdf file.
  
  
• The name of the jarfile inside the chrome directory is not exactly the same as the jarfile in the chrome.manifest file.

Remember that we have made no changes in the theme itself. We’ve just changed the name and maybe the architecture. Better to deal with this frustrating business now and not after you’ve sweated over all your theme changes. Go back and muck around until your new theme passes the smoke test. Then move to the next post.

[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread

Post #5

Now we are ready to set up your workbench.

You know what the ID of your theme is. Go into your profiles directory. In Windows XP is it here:

Code:
 C:\Documents and Settings\[username]\Application Data\Mozilla\Firefox\Profiles

Locate the profile you are going to use. As an example, one of mine is named "vbrf3qlv.Default User". Go inside your profile. You will find a number of directories. Themes and extensions are located inside the extensions directory.

Go into the extensions directory of your profile. You will find some subdirectories. They have GUID’s as names, and represent both themes and extensions.

Find the subdirectory with your new theme’s ID. Create a shortcut to it and drop the shortcut into your workshop directory. Now when you go into your workshop you have a shortcut that leads you into your theme’s working directory, what I call your workbench.

Next, unpack the jarfile that is inside the chrome directory. If you are using IZArc, choose the menuitem that says “Extract here.” This will unpack the contents of the jarfile to inside the chrome subdirectory, which is just what you want.

Using SphereGnome as an example, the subdirectory will now contain the original jarfile and the subdirectories:

global
help
mozapps
browser
communicator

Are we surprised?

One thing: themes have many structures. I took my structure from the default theme, but the directories in the theme you choose may be entirely different.

Delete the jarfile, or move it somewhere outside this directory. If you leave it there you will not know whether your test theme is working right.

Now we go up a directory, to the directory named the same as your theme ID.

Copy chrome.manifest and name the copy something like chrome-jar.manifest. If you are using Windows, you may wish at this point to tell the OS to always open .manifest files with Wordpad or something similar.

(Save chrome-jar.manifest. When you go to making your theme installable, you will need this file, only then you will call it chrome.manifest. At this stage it reduces confusion to keep the files under different names.)

Now, close Firefox. Open chrome.manifest. Inside, you will see something like this:

Code:
skin   global      SphereGnome   jar:chrome/chrome.jar!/global/
skin   help         SphereGnome   jar:chrome/chrome.jar!/help/
skin   mozapps      SphereGnome   jar:chrome/chrome.jar!/mozapps/
skin   browser      SphereGnome   jar:chrome/chrome.jar!/browser/
skin   communicator   SphereGnome   jar:chrome/chrome.jar!/communicator/

Edit this file until it looks something like this:

Code:
skin   global      SphereGnome      chrome/global/
skin   mozapps      SphereGnome      chrome/mozapps/
skin   browser      SphereGnome      chrome/browser/
skin   help         SphereGnome      chrome/help/
skin   communicator   SphereGnome      chrome/communicator/

The fourth column no long points Firefox to a compressed jarfile, but to uncompressed subdirectories inside the chrome directory.

Time for another smoke test.

As a precaution, delete the extensions.rdf file before you restart Firefox. This causes Firefox to examine all of its extensions while starting up, so it will know that your theme no longer uses a jarfile but uncompressed directories. Firefox will generate another extensions.rdf file.

Start Firefox (the smoke test).

If it fails the smoke test, close the browser (you may have to force it with ctrl-alt-del or the equivalent).

Again, the most common errors I make to cause smoke test failures are misspellings or using the wrong chrome.manifest file.

When Firefox can start and restart while using your theme with no hiccups, you now have a workbench. Try swapping in some new icons for the old theme’s icons so you get the hang of it.

Each change you make will show up the next time you start Firefox. Your workbench will speed up your development enormously.

What will also help you is the MR Tech Local Install extension. It will supply you with a Restart button you can put on your toolbar.

[YoungAlex]

Original Author - Ed Hume
Homepage * Original MZF Thread

Post #6

A few caveats:

If you are not basing the structure of your theme on the Firefox default, it is polite to ask the author of the theme for permission. I am granting you permission now to use the structures and code in my themes.

In order to learn how to make themes, you need to learn to manipulate css (cascading file sheet language).

Resources include:

First and foremost:

Firefox Chrome Explorer
by "mcdavis941". He will teach you how to code themes!

Also:

Mozilla.org's Creating a Skin for firefox
W3 Schools CSS tutorial
Tizag CSS tutorial
XUL Planet XUL tutorials

Especially the box model:

W3C
Brain Jar
a 3-D box model by Hicks Design

and a bit on Mozilla-specific commands.

Finally, the Mozillazine KnowledgeBase on themes. This will teach you the whys and wherefores of themes. Study this and you will begin to see what you can do with the theme workshop and workbench you have just created.