382 Part VI — Creating Extensions and Themes Text Editor Most files in themes are simple text files (.txt). You can use any text editor to edit them. I use a Windows-based operating system, and depending on the level of complexity involved, I use Notepad, WordPad, or even Microsoft Visual Studio .Net. Notepad and WordPad are great basic text editors, but when I want to do something like a find/replace in multiple files, I use Visual Studio .Net because it allows multiple files to be open at once. The beauty of the Mozilla theme engine lies in its cross-platform compatibility. If you weren’t already aware of this, different operating systems use different ways to store line breaks. Windows-based sys- tems use carriage return plus line feed (CR/LF), UNIX-based (including Linux) systems use only LF, and Macintosh systems use only CR. This can cause problems if the software isn’t able to detect the line-break style of a file. The Mozilla theme engine is able to detect different line- break styles and accommodate them. That means that you can use any text editor, regardless of operating system, as long as the file is saved as plain text. Bottom line, use a text editor that you’re comfortable with. Image/Graphics Editor As with text editors, the choice is up to you. Generally, most images in themes are either GIF or PNG format because of their transparency options. Any image/graphics editor that allows you to save images with transparency is acceptable. My favorite is Jasc Paint Shop Pro. You can also use Adobe Photoshop or any similar tool for your operating system. I don’t recommend editors as simple as Microsoft Paint, as they generally don’t handle transparency properly. ZIP-Format Compression Tool A ZIP-compatible compression tool is required to create the JAR file, which is the compressed archive file. Feel free to use any compression tool that you are comfortable with to create the JAR file when ready to test or make your theme public. I use WinZip, but your favorite, if dif- ferent, should work too. Another great tool is 7-Zip. 7-Zip is free and comes with command- line options built in. With WinZip, command-line tools are an add-on. The only exception to “use any ZIP-compatible compression tool you want” is Zipmagic; I’ve heard reports from some folks that it’s incompatible with the JAR file format. You can go to http://www.winzip.com to get a copy of WinZip and to http:// www.7-zip.org for a copy of 7-Zip. Building Your First Theme So you’re ready to create a Firefox theme? Now that you know all the tools required, it’s time to roll up your sleeves and get to work. The best way to get started is to use the default Firefox theme as a template. 26_596500 ch18.qxd 6/30/05 3:15 PM Page 382 383 Chapter 18 — Creating Themes Define and Create Your Theme’s Core Files While it may sound simplistic to say that a theme is composed of images and text files, there are a great many files, and the Firefox theme engine looks for specific files in specific places. You should never try to write all the files yourself. No theme author that I know of ever created a theme that way. It’s better to begin by modifying the default theme. Browse to the location where you installed Firefox. Up until the release of Firefox 1.0.2, there were zipped versions of Firefox available for download. Now that those have been discontinued for official releases, you will need to be able to locate the folder where you installed Firefox. For those of you using Windows, the default install location for Firefox is C:\Program Files\ Mozilla Firefox. Mac users have two ways to access the Firefox folder. You can Ctrl+click the Firefox applica- tion package and select “Show Package Contents,” or you can browse to the /Applications/ Mozilla.app/Contents/MacOS/ folder. For the Linux users out there, there does not seem to be a standardized location yet for the Firefox installation. The install location depends on which distribution you are running. I know the install locations for three popular Linux distributions. Gentoo installs Firefox to the /usr/lib/MozillaFirefox directory, Debian to the /usr/lib/mozilla-firefox directory, and Fedora to the /usr/lib/mozillafirefox directory. The default theme file is named classic.jar, located in the Firefox\chrome directory. If you have not been able to locate your Firefox directory yet, now is the time to search your computer for the classic.jar file. You’ll need to open classic.jar with your ZIP format compression tool and extract the files. After extraction, you should have a directory structure similar to that shown in Figure 18-1. F IGURE 18-1: Classic.jar directory structure Because the default theme is installed during the Firefox installation process, it has a different directory structure from that of themes that require installation on their own. You’ll need to move some files around and create some yourself. Figure 18-2 shows the directory structure that your theme will need. 26_596500 ch18.qxd 6/30/05 3:15 PM Page 383 384 Part VI — Creating Extensions and Themes F IGURE 18-2: Your theme’s directory structure Both the preview.png and icon.png files are used in the Themes window.The preview.png file traditionally shows what the theme looks like when in use, and the icon.png file is displayed to the left of the theme’s name, as shown in Figure 18-3. F IGURE 18-3: Themes Manager Creating the install.rdf File You might have noticed that the default theme doesn’t have an install.rdf file. This is one of the files that you need to create. The following is the install.rdf file from my Smoke theme: <?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>{3646e22c-5e51-43fb-b8a4-9ebaf7eb11f2}</em:id> <em:version>1.5</em:version> <em:targetApplication> <Description> 26_596500 ch18.qxd 6/30/05 3:16 PM Page 384 385 Chapter 18 — Creating Themes <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <em:minVersion>0.8</em:minVersion> <em:maxVersion>1.0</em:maxVersion> </Description> </em:targetApplication> <em:name>Smoke</em:name> <em:description>Based on the Orbital icon set by Florian Freundt (http://www.freundt.org/florian)</em:description> <em:creator>Aaron Spuler</em:creator> <em:contributor>Icons by Florian Freundt</em:contributor> <em:homepageURL>http://www.spuler.us</em:homepageURL> <em:updateURL></em:updateURL> <em:internalName>smoke</em:internalName> </Description> </RDF> Creating the contents.rdf File The default theme also handles the contents.rdf file differently. Instead of one contents.rdf file, it has four — one in each subdirectory. You’ll need to delete all four of the contents.rdf files. After you have deleted all four contents.rdf files, you must create one file and place it in the root directory of the theme, as shown in Figure 18-2. The following is the contents.rdf file from my Smoke theme: <?xml version=”1.0”?> <RDF xmlns=”http://www.w3.org/1999/02/22-rdf-syntax-ns#” xmlns:chrome=”http://www.mozilla.org/rdf/chrome#”> <Seq about=”urn:mozilla:skin:root”> <li resource=”urn:mozilla:skin:smoke”/> </Seq> <Description about=”urn:mozilla:skin:smoke” chrome:name=”smoke”> <chrome:packages> <Seq about=”urn:mozilla:skin:smoke:packages”> <li resource=”urn:mozilla:skin:smoke:global”/> <li resource=”urn:mozilla:skin:smoke:browser”/> <li resource=”urn:mozilla:skin:smoke:mozapps”/> </Seq> </chrome:packages> </Description> <Description chrome:skinVersion=”1.5” about=”urn:mozilla:skin:smoke:global”/> <Description chrome:skinVersion=”1.5” about=”urn:mozilla:skin:smoke:browser”/> <Description chrome:skinVersion=”1.5” about=”urn:mozilla:skin:smoke:mozapps”/> </RDF> 26_596500 ch18.qxd 6/30/05 3:16 PM Page 385 386 Part VI — Creating Extensions and Themes For the moment, you can use these files as they are, but you’ll want to edit them later. If you already know the name you want for your theme, replace all instances of Smoke with your theme’s name. You should probably also change the creator name and URL right now. If you don’t have a web site, you can leave that portion blank, as I’ve done with the em:updateURL section. (The update URL is discussed later in this chapter.) For more information on RDF files, see http://www.xulplanet.com/tutorials/ mozsdk/rdfsyntax.php. Generate a Custom GUID A Globally Unique Identifier (GUID) is a 128-bit random number. The number of unique ids is so large that the chances of generating the same 128-bit number twice are virtually nonexis- tent. There are two GUIDs in the preceding sample install.rdf posted. One is for Firefox ( ec8030f7-c20a-464f-9b0e-13a3a9e97384), and the other is for the Firefox version of the Smoke theme ( 3646e22c-5e51-43fb-b8a4-9ebaf7eb11f2). A GUID is used to avoid causing confusion by guaranteeing that no two themes or extensions have the same name. You’ll need to generate a GUID for your theme. This will replace the Firefox Smoke GUID on the line <em:version>1.5</em:version> in the sample code previously pro- vided. I use the following tool, available on the Web, to generate GUIDs for themes: http:// www.hoskinson.net/webservices/guidgeneratorclient.aspx , shown in Fig- ure 18-4. The Rain theme is shown in the screenshot. F IGURE 18-4: GUID Generator 26_596500 ch18.qxd 6/30/05 3:16 PM Page 386 387 Chapter 18 — Creating Themes This web site is very simple to use: Simply click the Generate GUID button, and the text box above the button will be populated with a GUID. If you need to create more than one, just click the button as many times as needed. Customizing Chrome Chrome is the user interface portion of the application window that lies outside a window’s content area. Toolbars, menu bars, progress bars, and window title bars are all examples of ele- ments that are typically part of the chrome. Every part of the chrome is defined through CSS files. All the files in your theme contain declarations for objects in the chrome. The most important CSS file for Firefox is browser\browser.css. This file controls the main display that’s visible while using the browser. All of the standard buttons (back, forward, stop, reload, print, go, and so on) are defined in this file. In order to change the attributes for an element, you need to know its internal id. Using the DOM Inspector The DOM Inspector is without a doubt the most useful tool involved when constructing a theme. I didn’t know about it when creating my first few themes, and believe me, I wish I had. Without the DOM Inspector, it became a guessing game, and my guesses were wrong more often than not. With the DOM Inspector, you can find out anything you want to know about every portion of the browser window. It will tell you the CSS id for any button, what file the button attributes are defined in, and even in what line the definition starts. To start using the DOM Inspector, follow these steps: 1. Go to the Tools menu and select DOM Inspector.This opens the DOM Inspector in a new window. 2. Go to the File menu, select Inspect a Window, and then select the Mozilla Firefox win- dow. If you’ve done that correctly, the text box at the top of the page will read as follows: chrome://browser/content/browser.xul. 3. Click the Inspect button. The bottom half of that window should display the browser window. Figure 18-5 shows the progress so far. My Smoke theme is shown in the screenshot. Now you can start to explore the code to generate browser elements. Directly underneath the File menu is a button that looks like a mouse pointer hovering over a button. This button allows you to click on a browser element and see its attributes. To activate this feature, click on the button (it turns darker when you do this); then click on a browser element in the lower pane. Try that now. Click on the Reload button (it will briefly flash red). In the upper-left pane, the Reload button will be selected in the DOM tree, and in the upper-right pane, infor- mation about the Reload button will be populated. Clicking the button to the left of the text “Object - DOM Node” brings up a menu with six items. The one that we are interested in at this time is the CSS Style Rules menu item (see Figure 18-6). 26_596500 ch18.qxd 6/30/05 3:16 PM Page 387 388 Part VI — Creating Extensions and Themes F IGURE 18-5: DOM Inspector F IGURE 18-6: Reload button, CSS Style Rules Now that the CSS rules are shown, you can actually see what code controls the Reload button. The first two lines in the CSS Style Rules pane are irrelevant. The third item details the styles applied to all buttons. This deals with margins, padding, borders, and text colors. The fourth, fifth, and sixth items — .toolbarbutton-1 — are general properties that deal with the main toolbar buttons only.The following buttons are part of the .toolbarbutton-1 group: Ⅲ Back Ⅲ Forward Ⅲ Reload Ⅲ Stop 26_596500 ch18.qxd 6/30/05 3:16 PM Page 388 389 Chapter 18 — Creating Themes Ⅲ Print Ⅲ Downloads Ⅲ History Ⅲ Mail Ⅲ Bookmarks Ⅲ New Tab Ⅲ New Window Ⅲ Cut Ⅲ Copy Ⅲ Paste The last line, #reload-button, details properties that are specific to the Reload button. Understanding CSS Because the entire user interface is defined through Cascading Style Sheets, you’ll need to know something about CSS to create a Firefox theme. I had never heard of CSS when I started creating Mozilla themes, and that made the process (unnecessarily) difficult. I still don’t know all that much about CSS, but I know enough to get around. If you don’t know any CSS, now might be a good time for a bit of research. A Google search for “CSS Tutorial” will bring up lots of useful sites to get you started. If you’re interested in a quick tutorial, visit the follow- ing sites: Ⅲ http://www.htmlhelp.com/reference/css/ Ⅲ http://www.w3schools.com/css/ Creating Needed Graphics To make your theme truly unique, you’ll need to replace the graphics associated with the default theme. A great majority of the buttons are found in the files browser\toolbar.png and browser\toolbar-small.png. PNG is an extensible file format for the lossless, portable, well-compressed storage of raster images. PNG is a replacement for GIF because PNG allows for true color (24-bit) images with alpha transparency, as opposed to GIF, which allows for 256-color images with indexed trans- parency. Indexed-color, grayscale, and true-color images are supported, plus an optional alpha channel for transparency. The PNG format was sought as a replacement for the GIF format when Unisys requested royalties from GIF-supporting software for the use of its patents on the LZW compression algorithms in 1994. See http://www.webcolors.freeserve.co.uk/png for more information on the PNG format. 26_596500 ch18.qxd 6/30/05 3:16 PM Page 389 390 Part VI — Creating Extensions and Themes Overlay Default Icons If you want to use the same size buttons as the default theme (24 × 24 pixels for large buttons, 16 × 16 pixels for small buttons), you can simply open the image files and replace them with your own images in your image editor. I would recommend this method to anyone unfamiliar with CSS. The default theme uses one large image file to hold all the large toolbar button images and another for the small toolbar button images. In Figure 18-7, the buttons are all laid out on a single *.png image. F IGURE 18-7: Toolbar.png The top row of icons is for the normal state (not disabled, not hovered). The second row holds the icons displayed when you hover over a button with your mouse. The third row is the icons shown when a button is disabled. You’ll notice that there is only one icon on the fourth row — that is the bookmarks icon, which has four states in the default theme. When you click on the bookmarks button, Firefox displays your bookmarks along the left side of the screen. The icon on the fourth row is displayed while the bookmarks are open. Personally, I don’t like to use one large image file to hold all the toolbar images. It’s hard to edit files when they’re stored this way because of image alignment issues. I store each button in a different image, with three button states per image, as shown in Figure 18-8. The only down- side to storing each button in a different image is that compression is generally better when all buttons are stored in a single image, as in Figure 18-7. The compression issues should not affect your theme at all during normal use — only the size of the jar file. F IGURE 18-8: Separate images for each button The normal button image is on top, in the center is the button when hovered over, and on the bottom is the disabled state image. I do not specify a fourth state for the bookmarks icon while open. I modified the code to display the hover state for the icon when the bookmarks are visible. 26_596500 ch18.qxd 6/30/05 3:16 PM Page 390 391 Chapter 18 — Creating Themes Keep in mind that there is no correct way to lay out images; you can simply choose the method that works best for you. As long as the code you write is valid CSS and points to valid images, it will work properly. Layered Images The easiest way for me to align all the different image states was to put each state on a separate layer.That way, I could manipulate each layer individually. Another method that might prove helpful is the use of gridlines. I use Jasc Paint Shop Pro to edit images while creating themes.To overlay the default theme’s images, open browser\toolbar.png, as shown in Figure 18-9. F IGURE 18-9: Paint Shop Pro Because the default theme uses 24 × 24 pixel images for large icons, you need to have your images the same size. Open up the image that you would like to use for the Back button and then copy the image by pressing Ctrl+C, or selecting Edit ➪ Copy.To paste your image as a new layer, press Ctrl+L or select Edit ➪ Paste➪ Paste As New Layer. You can then select the new layer in the layer properties window (it will be called Raster 2), and use the Move tool to drag your icon over to where the Back button resides in the default icon set. Once you com- plete that step, your display will look similar to Figure 18-10. The Back button on layer 2 is the Back button from the Smoke theme. 26_596500 ch18.qxd 6/30/05 3:16 PM Page 391 . install.rdf posted. One is for Firefox ( ec8030f7-c20a-464f-9b0e-13a3a9e97384), and the other is for the Firefox version of the Smoke theme ( 3646e22c-5e5 1-4 3fb-b8a 4-9 ebaf7eb11f2). A GUID is used. 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>{3646e22c-5e5 1-4 3fb-b8a 4-9 ebaf7eb11f2}</em:id> <em:version>1.5</em:version> <em:targetApplication> <Description> 26_596500. favorite, if dif- ferent, should work too. Another great tool is 7-Zip. 7-Zip is free and comes with command- line options built in. With WinZip, command-line tools are an add-on. The only exception