This post summarizes some of my findings while attempting to make a descent single-button Firefox extension. I’ve tested the code shown below with Firefox 1.5 and 3.0 under Windows, and Firefox 3.0 under Linux, and there were zero portability issues.

I would suggest reading a tutorial about toolbars and possibly Mozilla’s own tutorial about XUL before the notes below.

The magic

All I wanted was to put a little button on my Firefox browser. At some point I realized that I won’t get things working like I want unless I understand what I’m doing. So I dived into the thing called XUL.

I have to admit, that it looks terrible at first glance. I started to change my mind when I realized, that XUL is a format for describing GUI items. That my case of toolbar extensions is a very narrowminded one. To get an idea what XUL can do,  just have a look on the so-called periodic table. But that’s really nothing compared with the simple fact, the all of Firefox’  GUI (menus, buttons, dialogs) is implemented in XUL and JavaScript.

But my the real enlightment came to me at page 391-392 of Programming Firefox. That’s where I realized that I should unzip the browser.jar file, which is exactly where one could expect to find it: In the Mozilla Firefox/chrome directory (where the application is installed, not where it puts its cache data etc.)

Also, unzipping classic.jar is useful to see the names of the image files used, so that the relevant place can be found easily in browser.jar’s files. It’s much easier to find the place at which the reload button is defined when its image file’s name is known.

Reverse engineering

Let’s investigate the reload button, then. It wasn’t too difficult to realize that its icon can be found in the classic.jar, in a file named Toolbar.png (find the directory yourself). Searching for that string in all of classic.jar’s files, the next clue was  in browser.css (same directory as Toolbar.png).

Now, I won’t pretend to really understand what’s going on in that CSS file, and neither did I make a real effort to do so. All I needed was to come across a CSS definition like:

#reload-button {
  -moz-image-region: rect(0px 96px 24px 72px);
}

If you’re not so good in CSS, that’s a definition for an object with ID ‘reload-button’. I wonder what that object could be…

So now I had my next clue: Look for reload-button in browser.jar’s files. Surprise, surprise, it’s in browser.xul. The button is declared as

      <toolbarbutton id="reload-button" class="toolbarbutton-1 chromeclass-toolbar-additional"
                     label="&reloadCmd.label;"
                     command="Browser:Reload"
                     tooltiptext="&reloadButton.tooltip;"/>

Which, to tell the truth, is not so interesting. What I’m really looking for, is the ID of the enclosing XML tag. Scrolling up a bit, I found it:

<toolbarpalette id="BrowserToolbarPalette">

This is all I could ask for. But what is a “toolbarpalette”, I asked myself. Google took me straight to Mozilla’s documentation, which spelled it out for me.

The aftermath is, of course, that there was no need for reverse engineering, since the documentation tells me exactly how to get the button at the desired position. On the other hand, I didn’t find that information before.

I see no point in telling the whole story of going back and forth from searching the jar files for strings, then trying Google and/or trying to squeeze in an element of my own. The bottom line is that once I understood how the XUL represents the GUI itself, it became fairly easy to find the right magic words.

So I’ll go on with the bottom line of how to put the button in some interesting places.

The skeleton

I’ll skip the framework, since it’s documented all over. You can always unzip any Firefox extension XPI file to get an idea of what should be in it.

I assume that we already have a Javascript file, testingbutton.js. In that file, we have a function called testing_doit(), which we want executed every time our button is pushed.

Basically, the XUL file has the following format:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://testingbutton/skin/testingbutton.css" type="text/css"?>

<overlay id="Testing-Overlay"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

  <script type="application/x-javascript"
    src="chrome://testingbutton/content/testingbutton.js" />

... One or more element definitions come here ...

</overlay>

The important magic word here is <overlay>. What it means is that we can add elements to existing GUI elements by using their ID.  For example (shown in detail below), if I want to add an element to the toolbarpalette with ID “BrowserToolbarPalette”, I simply repeat its opening tag, and put my things there. This will not override the existing definition, but rather append new elements.

Note that any number of snippets from the examples below can be inserted to add several controls to the browser window.

And just before starting, here’s the CSS that comes along: Basically, it defines the image to use on the buttons, which are pinpointed through their IDs (using classes may have been more elegant?)

#Testing-Toolbar-Button {
    list-style-image: url("chrome://testingbutton/skin/logo.png");
}
#Testing-Doit-Button {
    list-style-image: url("chrome://testingbutton/skin/logo.png");
}
#Testing-Doit-Button2 {
    list-style-image: url("chrome://testingbutton/skin/logo.png");
}

In the toolbar (not)

I’ll start with a spoiler: The code below will add the button to the Toolbar Palette and not to the toolbar itself. In other words, after installing the extension, nothing will happen until the user manually puts the button in place. Not very impressive. I suppose there is a way to get the button there automatically, but given the alternatives, I didn’t bother to check how to do that.

Here’s the code:

  <toolbarpalette id="BrowserToolbarPalette">
    <toolbarbutton
      id="Testing-Doit-Button"
      label="Testing button"
      tooltiptext="Do it!"
      oncommand="testing_doit();"
    />
  </toolbarpalette>

The only really interesting thing here is that the ‘toolbarpalette’ tag shares its ID with the one defined in browser.xul. That’s the point, after all.

In a toolbar of its own (ugly)

I’m showing this one, only because it’s popular in examples I’ve seen, and it turns out ugly for a single button. The code below creates a full toolbar, from left to right, and puts one little button in it. Looks pathetic. Makes sense if you have a lot of buttons (and users who love your application a lot).

  <toolbox id="navigator-toolbox">
    <toolbaritem flex="0">
      <toolbarbutton id="Testing-Toolbar-Button"
       tooltiptext="Do it!"
       oncommand="testing_doit();" />
    </toolbaritem>
  </toolbox>

Note that ‘toolbarbutton’ has an ID which is mentioned in the CSS file. This is how the graphical icon appears.

In the existing toolbar (bingo!)

Well, I’m not sure if this is exactly where you would expect it, but the code below puts the button at the rightmost position next to the toolbar the user drags bookmarks to. The purely logic place might have been next to the address bar, but the actual position is excellent. Code follows:

  <toolbar id="PersonalToolbar">
    <toolbarbutton id="Testing-Doit-Button2"
     tooltiptext="Do it!"
     oncommand="testing_doit();" />
  </toolbar>

(By the way, I found the magic ‘PersonalToolbar’ ID simply by looking at browser.xul and trying it out. The name sounded promising, after all)

In the status bar (So cool!)

At the bottom-right corner, with minimal distraction:

  <statusbar id="status-bar">
    <statusbarpanel class="statusbarpanel-iconic"
     id="Testing-status-button"
     onclick="testing_doit();"
     tooltiptext="Do it!"
     src="chrome://testingbutton/skin/logo.png" />
  </statusbar>

An entry in the context menu

For users who don’t like to travel much with their mouse (laptops?), we have the menu which pops up when you right-click. How to add an entry to the context menu is described here. Note that the executed script can get some info about what was right-clicked (it’s called a context menu, after all).

Anyhow, this is what I made of it:

  <popup id="contentAreaContextMenu">
    <menuitem id="Testing-menu-entry"
     label="Do it!"
     oncommand="testing_doit();"/>
  </popup>

Conclusion

This XUL framework takes some time to get used to, but it’s a fantastic demonstration of how an open-source project can expose its internals without needing to compile anything. Despite some difficulty, working with Firefox’ internals is far more enjoyable than its well-known counterpart. Which shouldn’t surprise anyone.

So here is my short list of the main problems you may run into, while attempting to layout a web page using CSS-backed DIVs. If you really have to, that is.

Pitfall #0: Resize

If your page is made with CSS, don’t let the width change. Period. Play with CSS/DIV layout only when you’re inside a box, whose width is known and fixed to the pixel. This is not very browser tolerant, I know. It may not work well on a tiny screen. Or a very big one.

But trust me on this: If you don’t set the overall width, you will sooner or later find yourself with spillovers and overlapping graphics. Maybe you can get it to survive a page resize on your browser. You have no chance with the IE version still not out.

If you want to allow a resize, use tables.

Pitfall #1: Huge CSS file (reference by ID)

This one is so common, that sometimes I wonder if I missed something.

Anyhow, the original idea of CSS, if I got it right, was to define the format in one place and put the content in another. I suppose someone hoped that people would go on using simple tags such as <h1> and <p> and get beautiful pages with clean HTML.

And to make things nicer, they allowed classes. So if you wanted a special paragraph, you just went ‘p.special’ in the style definition, and then <p class=”special”> in the HTML, and there you were, the HTML still readable and the format consistent and depending on the content.

But then came style-by-ID, which turned everything into a joke. This made it possible to define the style for a very certain element, pin-pointing it by its ID tag. So if I wanted to format one single paragraph, I’d go ‘#theID’ in the CSS file, and then <p id=”theID”> in the HTML. And that makes me wonder: If the styling is going to be used once anyhow, why not put it directly in the HTML? Why not go <p style=”…”> instead? Don’t tell me that you separate formatting from content, when you can’t change anything in the CSS file without checking the specific place where it’s used. If you remember where it was, that is.

Pitfall #2: The IE ‘width’ bug

The CSS2 spec paragraph 10.2 clearly defines the ‘width’ property as “that of the rendered content within”. Microsoft probably said “we are the standard” and decided to include the padding and the border in the ‘width’ property. This is said to be fixed in IE6, so maybe it isn’t an issue today, after all.

Below is drawing of the box model, and the difference between the two definitions of ‘width’. The sad bottom line is that if you need a consistent width of some element, padding and border have to be zero. If this is not an option, the only safe solution is to put your element in another element (a DIV, I suppose) and define the ‘width’ for the enclosing element.

Box model

Pitfall #3: Getting absolute positioning wrong

So let’s go through a few quick facts:

• Absolute positioning puts your element where it would anyhow, unless you specify otherwise for the X axis (with “left” and “right” style properties) and/or the Y axis (with “top” or  “bottom” style properties). The only difference is that no space is allocated on the rendered page. The responsibility to keep the underlying area clean (or intentionally overlapping) is all yours.  Usually, if you don’t know exactly what you’re doing, things will get wrong sooner or later.
• If you want the element on a fixed position on the screen, no matter how the page is scrolled (logo?), used the “fixed” position.
• “relative” position is not what it appears to be. It will move the block from its original position, but allocate  space for it, as if it was there. Makes sense if you want chemistry-style subscripting, but otherwise I can see only one use: The zero-offset relative positioning, which is a way to set the ‘position’ property to something else than static (the default) without actually doing anything, and hence create a “containing block” in its natural place (more about that next).
• The “left”, “right”, “top” and “bottom” properties are related to the “containing block”, whose definition is a pitfall in itself. (See the CSS2 spec, paragraph 10.1, item 4). To make a long story short, the browser will climb up the hierarchy of blocks until it finds one, which isn’t statically positioned. It will then respect that block’s padding, and there is the zero point.
  Now, “statically positioned” is the default setting of the “position” property, which means that the browser should put the element following the “old-fashioned” rules. See the example below for how to use the “relative” position to make the enclosing DIV effective.
  If the containing block isn’t explicitly defined, hell breaks loose. The browser will most likely pick the root block, which is the top left corner of the page. Or not, depending on other junk you have on your page. Everything happens.

Pitfall #4: Absolute positioning know-it-all

I think that the main reason why “professional” web designers started talking about replacing <TABLE> formatting with <DIV> and CSS was that they first painted their web page with some graphics tool, and then wanted to copy their graphic design exactly into the web page. Which is a nice concept, if you can assure that the page will be viewed exactly like you expect: The same fonts, the same sizes, the same screen size, and so on. Which you can’t, but that’s another story.

No wonder they hated tables. It’s really a headache to control how the browser displays tables down to the pixel. Tables were, after all, not meant to be used that way. Getting the graphics from one table cell aligned with the next one is not easy. Not to mention more complex relations between graphic elements. And then came CSS and the DIVs.

The real power with DIVs is absolute positioning. Just make yourself a box, decide how large it will be (down to the pixel) and put whatever you want inside, exactly where you want it. Something like this:

<div style="position: relative; height: 200px; width: 200px; border: dotted red 1px;">
This is my canvas!
<div style="position: absolute; top: 60px; left: 20px">And</div>
<div style="position: absolute; top: 50px; left: 70px">I</div>
<div style="position: absolute; top: 55px; left: 90px">can</div>
<div style="position: absolute; top: 60px; left: 130px">put</div>
<div style="position: absolute; top: 110px; left: 40px">the</div>
<div style="position: absolute; top: 105px; left: 70px">elements</div>
<div style="position: absolute; top: 112px; left: 140px">where</div>
<div style="position: absolute; top: 150px; left: 80px">I</div>
<div style="position: absolute; top: 155px; left: 90px">want!</div>
</div>

And you get this:

Now I’m asking, isn’t this heaven? I say: It is, on your browser, on your computer. But since you’ve told the browser exactly what to do, you’ve also crippled its ability to fix things when the page is shown differently from how you expect it. A simple example follows.

Pitfall #5: Overflow

The page got resized? The fonts are shown larger than you defined? There was more text than expected? In the old days, the browser used to fix this. With CSS and DIVs you get rubbish.

The CSS spec says, that any block can overflow. What to do with the excessive graphic pulp is up to the browser (or it can be defined) but no matter how it’s handled, the result is ugly.

Let’s take a silly menu layout for example:

<div style="position: relative; width: 120px; height: 70px; border: solid 1px black">
<div style="position: absolute; top: 10px; left: 20px; background-color: #f8f;">Take me!</div>
<div style="position: absolute; top: 40px; left: 20px; background-color: #ff8;">Or take me!</div>
</div>

That looks like this:

The truth is, I can’t be sure that you see this as I do. But I’ll assume that it looks idiotic, but OK. But what happens if a script puts more text than expected? Or if the user forces a larger font? I’ll try to simulate this by choosing a larger font here:

But the truth is that I can’t know if this example went through OK, because I don’t know how your browser responded. But that’s the point, isn’t it?

If you want to be on the safe side, use the ‘overflow’ property. Below is shown what happens when you set ‘overflow: hidden;’ (to the left) or ‘overflow: scroll;’ (to the right) for the toplevel <div>. At least nothing spills over.

Pitfall #6: Floats

For some reason, which is beyond me, floats are commonly suggested as a solution for organizing web pages (except for horizontal layout, as shown below). There is only one problem with floats: They were intended to push text, and nothing else.

The whole idea was to allow an image to float to the left or right, and let the text surround it, just like as they do in newspapers. This is why the CSS2 spec says, in paragraph 9.4.1:

In a block formatting context, boxes are laid out one after the other, vertically, beginning at the top of a containing block. (…) In a block formatting context, each box’s left outer edge touches the left edge of the containing block (for right-to-left formatting, right edges touch). This is true even in the presence of floats (although a box’s content area may shrink due to the floats).

Let me spell this out: Paragraphs, DIVs or whatever, shouldn’t get pushed aside by floats. What should get pushed is the text they contain (or more precisely, inline elements). What happens in reality seems to depend on the browser. Firefox and Google Chrome follow the spec, IE plays its own game.

So let’s look at the following example:

<div style="border: 1px solid black; margin: 6px; padding: 5px; float: left; width: 4em; height: 4em; background-color: #ffdddd; text-align: center;">
Nice image</div>
<div style="background-color: #ff8; width: 12em; border: solid 1px black;">
This is my DIV, which has melted into the float.
Only the text is pushed aside.
</div>

Which looks like this on your browser:

Note that the non-floating DIV (in yellow) should surround the float. It should be packed as if the float wasn’t there. This is what the spec says should happen. In real life I got:

Float behavior on Firefox and IE

Not very impressive, is it?

By the way, if you want a rectangle which doesn’t mix with floats, put a table there. Tables are inline elements, so they won’t collide with floats. But if you’re playing with floats, you must be thinking that tables are obsolete…

Alternatively, you could go for a floats-only region. People who test with IE only are likely to get this wrong, because of the problem mentioned above. Anyhow, the idea is to pack DIVs horizontally to the right and to the left using floats, and avoid collision from top and bottom using the “clear” directive. For example:

<div style="background-color: #ffd; border: solid 1px black; text-align: center;">Above all</div>
<div style="float: left; background-color: #fdd; width: 4em; height: 3em; border: solid 1px black; text-align: center;">
One</div>
<div style="float: left; background-color: #fdd; width: 4em; height: 2em; border: solid 1px black; text-align: center;">
Two</div>
<div style="float: right; background-color: #fdd; width: 4em; height: 4em; border: solid 1px black; text-align: center;">
Four</div>
<div style="float: right; background-color: #fdd; width: 4em; height: 3em; border: solid 1px black; text-align: center;">
Three</div>
<div style="clear: both; background-color: #ffd; border: solid 1px black; text-align: center;">And this is below all!</div>

Which looks like this:

This is great for multiple columns, whose heights are unknown. We want the bottom DIV below all of them, and this is how it’s done. Note that if we put a non-floating DIV in the middle, we would get different behavior on IE and W3C-compliant browsers.

Note that none of the DIVs in this example contains the other. What makes them avoid each other is the “clear: both” attribute at the bottom which tells the browser that floats are not allowed in either side. So we get a clean line, immediately below.

One problem (or feature) of this method, is that if there is not enough horizontal space, floats will be pushed vertically, a bit like inline flow. Paragraph 9.5 of the W3C specification says:

If there isn’t enough horizontal room on the current line for the float, it is shifted downward, line by line, until a line has room for it.

This can’t be relied on too much, though. It looks like Firefox prefers to let some of the page go out of view rather than to mess the page up, when the page is resized to very narrow (below 400 pixels?). I don’t know exactly how it works, but the fact is that at some point the floats don’t tile vertically (in IE they do). I guess it’s an interpretation of “not enough horizontal space”.

And just a final remark about floats: The W3C specification requires that the width is known, and must therefore be set unless it has an intrinsic value (e.g. an image). But nothing stops us from setting the width in percents. With this simple trick, we can have columns that grow and shrink according to the limiting DIVs width (resizing…), while controlling the proportions between the columns.

Just a warning, though: Be careful with letting the overall width come near 100%, since the browser may round each float’s pixel width slightly. And of course, keep in mind that the width doesn’t include the border, margins nor padding, so these can cause a mess when things get tight. Not to mention mixing percentage width floats with constant width floats.

Pitfall #7: Getting the selection wrong

The grammar is in principle simple, but knowing the formalities is important. For example, div.theclass { } means a DIV with class “theclass”, but not necessarily a DIV within it. For a DIV within a certain class, the selection is e.g. “.theclass DIV { }”. This also goes for IDs, e.g. “#theID DIV { }”. The list can be nested, so a link within a list item within a certain ID could look like “#theID li a:visited { }”. The same trick goes with classes instead of IDs.

If several cases are desired, start the nesting from the beginning. Exactly like “a.banner:link, a.banner:visited, a.banner:active { }” one should also go “banner a:link, banner a:visited, banner a:active { }” when a “within” relation is desired rather than a direct one.

Conclusion

If you want to control your page’s layout down to the pixel, DIVs and CSS are your screws and screwdriver. Just remember that things may look very different when someone views your page with a cellular phone or some other gadget you wouldn’t think about.

As they always say, when everything else fails, RTFM (Read the Fine Manual). In the case of CSS, that manual is the W3C specification. This is not to say that browsers really follow it. Firefox does most of the time. At least they consider it a bug when it doesn’t. Microsoft and their IE live in a world of their own.

Anyhow, if you wonder why your <div><div><div>-page is a mess, or why everything goes wrong with patches of page fragments being where they shouldn’t be, the ultimate answer is to understand how the fine machine works. Or at least, how it was meant to. And that is written in the spec. Boring, but a man has to do what a man has to do.