Dive into Mozilla Modifying Firefox using an Extension Lab
Dive into Mozilla > Dive into Mozilla Day 5 > Modifying Firefox using an Extension Lab
...in progress...
Contents
- 1 Introduction
- 2 The 'What': write a tab creation extension
- 3 The 'Where': figuring out where to put our code
- 4 The 'How': the necessary changes to the code
- 5 Reflections
- 6 Resources
Introduction
In the previous lab we made a small change to the behaviour of Firefox by modifying the browser's source code. In this lab we explore how to achieve the same effect using an extension rather than modifying the tree.
The goal of this exercise is to expose you to Firefox extensions and to show you how to modify or extend the browser without changing it's source code directly. Some thought will also be given to the two methods of doing this (i.e., in the tree vs. as an extension), comparing their advantages and disadvantages.
The 'What': write a tab creation extension
As was previously the case, our goal is to modify Firefox so that new tabs are created (i.e. positioned) beside the current tab instead of being appended to the end of the list.
However, unlike last time where we modified tabbrowser.xml directly, this time we will overlay our changes onto the browser at runtime, and alleviate the need for any direct changes to the code. This is possible using extensions.
The 'Where': figuring out where to put our code
The first thing we should address is why we're doing this at all: why bother creating an extension in order to do what we've already done in the tree? There are a number of answers to this question.
Changes in the tree vs. an extension
The first problem with doing things in the tree is that in order for you to distribute the local changes you've made, people will have to use your custom build of Firefox. While this might seem like a good idea the first time you build the browser, it isn't sustainable long term, and users will always want to get the browser from Mozilla for security fixes, new features, etc.
A logical alternative might be to try and get your change accepted into the tree. This involves filing a bug on https://bugzilla.mozilla.org and then creating and attaching a patch with your changes. The problem here is that even though you might think it is a good idea for tabs to be created in the way we've specified, the community may not--people have already put thought into the way things work now, users are accustomed to it, etc. In this case your bug will likely be marked WONTFIX, which means that your patch won't make it into the tree.
What does this leave? You could fork Firefox, as some people have done, and create your own version of the browser. Obviously this isn't what we'd like to do. Rather, what we need is a mechanism to insert a small change into the browser, and do so in such a way that users can choose to install our code or not. Mozilla provides such a mechanism in the form of Extensions.
Extensions allow third-party developers (and Mozilla, for that matter) to write add-on packages that users can install to extend or modify the standard browser. By rewriting our earlier code as an extension, we can give users an extension to install, which will have the same effect as our custom build. For all but the most universal of changes, extensions are the best way for developers to write code that targets the browser.
Planning the extension
Having decided to rewrite the code as an extension and remove our changes from the tree, a logical first thought would be: "how can I modify my existing code to create an extension." While we learned some useful things modifying the browser directly, our extension will require a completely new approach to solving the same problem.
Instead of searching for existing code to change, we have to take the browser as a given and find ways to work with it. To that end, let's look again at the code for tabbrowser's addTab method:
var t = document.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", "tab");
...
this.mTabContainer.appendChild(t);
...
// Dispatch a new tab notification. We do this once we're
// entirely done, so that things are in a consistent state
// even if the event listener opens or closes tabs.
var evt = document.createEvent("Events");
evt.initEvent("TabOpen", true, false);
t.dispatchEvent(evt);
return t;
After the new tab is created and appended to the list, an event is dispatched. The developers of tabbrowser.xml wanted their code to be extensible; that is, they wanted to provide a way for future developers to extend the code by inserting a hook. In this case, after a tab is created an opportunity is provided to do something. Their foresight makes our job much easier.
How to move a tab?
Now we know that there is a logical time/place to run our code via the TabOpen event. The next thing to consider is what our code will do. Previously we replaced append with insertBefore and stopped the problem before it happened. In this case, by the time the TabOpen event is dispatched, the tab will already be created and positioned at the end of the list.
We need another solution, so we need to go hunting in tabbrowser's documentation and code. What we need is a way to reposition a tab after it has been created. A quick look through the docs for tabbrowser reveals nothing. However, the code is more helpful:
<method name="moveTabTo"> <parameter name="aTab"/> <parameter name="aIndex"/> ...
The moveTabTo method takes a tab to be moved, and a new position. This is exactly what we need. Now there are just two things left to figure out: 1) how to get the newly inserted tab; and 2) the index of currently selected tab so we can go one to the right.
How to get the newly created tab using code?
Having already studied and worked with the code in addTab, and knowing that new tabs are always appended to the end of the list, we could do this:
var container = gBrowser.tabContainer; var lastIndex = container.childNodes.length - 1; var newTab = container.childNodes[lastIndex];
However, looking back at the event dispatching code for TabOpen we see that the event is dispatched ??? t, where t is the newly created tab:
t.dispatchEvent(evt);
How to get the index of the currently selected tab?
Start by creating a new extension, either by hand, or using Ted Mielczarek's wonderful wizard:
http://ted.mielczarek.org/code/mozilla/extensionwiz/
Directory structure:
addtabbeside/
content.manifest
install.rdf
content/
firefoxOverlay.xul
overlay.js
Here is the content.manifest file:
content addtabbeside content/ overlay chrome://browser/content/browser.xul chrome://addtabbeside/content/firefoxOverlay.xul
Here is the install.rdf file for the extension:
<?xml version="1.0" encoding="UTF-8"?>
<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>addtabbeside@senecac.on.ca</em:id>
<em:name>Add Tab Beside</em:name>
<em:version>0.1</em:version>
<em:creator>David Humphrey</em:creator>
<em:description>New tabs are created beside the current tab instead of at the end of the tab list.</em:description>
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <!-- firefox -->
<em:minVersion>2.0</em:minVersion>
<em:maxVersion>3.0a3pre</em:maxVersion> <!-- trunk build Feb 27, 2007 -->
</Description>
</em:targetApplication>
</Description>
</RDF>
Here is firefoxOverlay.xul:
<?xml version="1.0" encoding="UTF-8"?>
<overlay id="addtabbeside-overlay"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<script src="overlay.js"/>
</overlay>
Load Listener code:
Reading through the rest of the moveTab method, we see that when a tab is successfully created, the TabOpen event is dispatched
(see ...)
// Dispatch a new tab notification. We do this once we're
// entirely done, so that things are in a consistent state
// even if the event listener opens or closes tabs.
var evt = document.createEvent("Events");
evt.initEvent("TabOpen", true, false);
t.dispatchEvent(evt);
return t;
This is useful information, because it tells us that if we want to know when a tab has been created, we have to add a listener for this event.
moveTabTo
http://lxr.mozilla.org/seamonkey/source/toolkit/content/widgets/tabbrowser.xml#1958
Create a file named: addtabbeside@senecac.on.ca
This file should contain the full path to your extension, for example:
C:\temp\addtabbeside
Now put this file in your development profile's extensions directory (NOTE: replace Username with your username and dev-profile with your development profile name):
C:\Documents and Settings\Username\Application Data\Mozilla\Firefox\Profiles\dev-profile\extensions
overlay.js
var AddTabBeside = {
// State info on the last tab to be selected.
mPreviousIndex: 0,
onLoad: function() {
// Add a listener for the TabOpen event, which gets called as
// part of addTab in tabbrowser.xml
var container = gBrowser.tabContainer;
container.addEventListener("TabOpen", this.onTabOpen, false);
// Also add a listener for TabSelect so we know when focus changes to a new tab
container.addEventListener("TabSelect", this.onTabSelect, false);
// Finally, add a listener for shutdown
window.addEventListener("unload", this.onUnload, false);
},
onUnload: function() {
var container = gBrowser.tabContainer;
container.removeEventListener("TabOpen", this.onTabOpen, false);
container.removeEventListener("TabSelect", this.onTabSelect, false);
},
onTabSelect: function (e) {
// when a different tab is selected, remember which one. This is
// necessary because when a new tab is created, it will get pushed
// to the end of the list, but we need to know where to put it.
this.mPreviousIndex = gBrowser.tabContainer.selectedIndex;
},
onTabOpen: function (e) {
// Get the newly created tab, which will be last in the list
var newTab = e.target;
// Move this new tab to the right of the previously selected tab,
// checking to see how many tabs there are currently. By default
// there is 1 tab, and the first time onTabOpen is called, there will
// be 2 (the default plus the newly created tab). In this case, don't
// move the new tab, since it is already in the right spot. In all
// other cases, move the tab to the right of the current tab.
if (gBrowser.tabContainer.childNodes.length > 2) {
gBrowser.moveTabTo(newTab, this.mPreviousIndex + 1);
}
},
};
window.addEventListener("load", function(e) { AddTabBeside.onLoad(e); }, false);
It's one thing to say you'd like to change the browser's behaviour, but quite another to actually do it. The change you have in mind might be quite simple, in the end (ours is). But you still have to figure out where that simple code needs to go. That can be difficult. However, difficult isn't the same as impossible.
How do you begin? First, let's start at the top and find some UI notation we can search for in the code. In our case, we can focus on the various methods for creating a new tab:
- CTRL+T
- Right-Click an existing tab and select New Tab
- File > New Tab
The second and third methods are useful, as they provide us with a unique string we can search for in the code. Before we can change anything, we have to search and read existing code in order to understand where to begin--this is the standard pattern for open source and Mozilla development.
Search 1 - finding a UI string
We're looking for a unique string--"New Tab"==, so we'll use LXR's Text Search feature. Here are the results you get when you search for "New Tab":
http://lxr.mozilla.org/seamonkey/search?string=New+Tab
Lots of results, many of which point to comments in the code. However, the first result looks interesting:
http://lxr.mozilla.org/seamonkey/source/toolkit/locales/en-US/chrome/global/tabbrowser.dtd#2
Here we see the DTD file describing the key/value pairs for the en-US localized strings. Mozilla uses this technique to allow localizers to translate strings in an application into many different languages without having to change hard-coded strings in the code (you can read more about localization, DTDs, and Entities here)
Looking closely at tabbrowser.dtd we see that our English string, "New Tab", has the following entity:
<!ENTITY newTab.label "New Tab">
This is good information, because it allows us to repeat our search with an entity instead of a string, which should help us get closer to the code we're after.
Search 2 - finding an ENTITY
Repeating the search with the newTab.label ENTITY value instead of the "New Tab" string makes a big difference--we have many fewer hits:
http://lxr.mozilla.org/seamonkey/search?string=newTab.label
Not surprisingly, the first result is the same DTD file (i.e., tabbrowser.dtd) we already found. The second result looks interesting, though:
http://lxr.mozilla.org/seamonkey/source/toolkit/content/widgets/tabbrowser.xml#80
Here we see the code to generate the pop-up context menu for a tab (i.e., what you get when you right-click on a tab in the browser):
<xul:menuitem label="&newTab.label;" accesskey="&newTab.accesskey;"
xbl:inherits="oncommand=onnewtab"/>
Having found the appropriate entity value, we also notice the use of a function name, onnewtab. This line of code says that the xul:menuitem will inherit the oncommand value from its parent (you can read more about XBL attribute inheritance here). In other words, when this menu item is clicked, call the onnewtab function.
Search 3 - finding a Function
Armed with this new information, we are even closer to finding the right spot to begin working. We've gone from UI string to XML ENTITY to function. All we have to do now is find that function:
http://lxr.mozilla.org/seamonkey/search?string=onnewtab
This returns many results for things we aren't interested in, including files rooted in /suite, /db, etc. Since we are interested in finding this behaviour in Firefox, we need to focus on the files rooted in /browser. One looks particularly interesting:
http://lxr.mozilla.org/seamonkey/source/browser/base/content/browser.xul#503
In this case, the tabbrowser widget has the onnewtab property set to another function, BrowserOpenTab(); (i.e., Firefox seems to handle tab creation in a non-standard way, providing its own method instead of using the default). Since we want to find the definition of this function, we search for "function BrowserOpenTab(", which returns two results:
http://lxr.mozilla.org/seamonkey/search?string=function+browseropentab%28
Again, we're interested in Firefox (i.e., browser) instead of SeaMonkey (i.e., suite), so we skip to the second result:
http://lxr.mozilla.org/seamonkey/source/browser/base/content/browser.js#1802
This shows us that we need to be looking for yet another function, loadOneTab(). Another search:
http://lxr.mozilla.org/seamonkey/search?string=loadonetab
The first result is not surprising, and we're back to the tabbrowser widget. The loadOneTab method calls another method to actually create and insert the new tab:
var tab = this.addTab(aURI, aReferrerURI, aCharset, aPostData, owner, aAllowThirdPartyFixup);
Since addTab is a method of this we can search within the current document (CTRL+F) to find the addTab method. Finally we've found the right spot!
http://lxr.mozilla.org/seamonkey/source/toolkit/content/widgets/tabbrowser.xml#1160
this.mTabContainer.appendChild(t);
Now all that we have to do is modify it to insert rather than append.
The 'How': the necessary changes to the code
There are different ways you could go about making this change, and someone with more experience using tabbrowser might recommend a different strategy or outcome. I decided to work on something that I knew nothing about in order to highlight the process one goes through, or at least the process I went through, when working with someone else's code. Since my goal is to show you how to do this, I also discuss my errors and mistakes below--they are an important part of the process too.
First Attempt
The goal is to make as small a change as possible, since the existing code works well--I just want it to work slightly different. I'm also not interested in reading all of the code in order to make such a small change. I want to leverage as much of what is already there as I can.
I assume that the appendChild() method is responsible for the behaviour I don't like (i.e., adding new tabs to the end of the list). I'm not sure what to replace it with, so I do another search inside tabbrowser.xml (i.e., using CTRL+F) looking for other methods/attributes of mTabContainer. I come-up with some interesting options:
index = this.mTabContainer.selectedIndex; ... this.mTabContainer.insertBefore(aTab, this.mTabContainer.childNodes.item(aIndex)); ... var position = this.mTabContainer.childNodes.length-1;
I decide that I can probably accomplish my goal using these alone, and so start working on a solution. Here is my first attempt, showing the changes to mozilla/toolkit/content/widgets/tabbrowser.xml and the addTab method:
// Insert tab after current tab, not at end.
if (this.mTabContainer.childNodes.length == 0) {
this.mTabContainer.appendChild(t);
} else {
var currentTabIndex = this.mTabContainer.selectedIndex;
this.mTabContainer.insertBefore(t, currentTabIndex + 1);
}
I then repackage the toolkit.jar file (change objdir to your objdir name):
$ cd mozilla/objdir/toolkit/content $ make
then run the browser to test (NOTE: minefield is my testing profile):
$ ../../dist/bin/firefox.exe -p minefield --no-remote
I try to create a new tab using File > New Tab and nothing happens.
Second Attempt
Clearly my code has some problems, since I've completely broken addTab. I decide to look for clues in the Error Console (Tools > Error Console) and notice the following exception whenever I try to add a new tab:
Error: uncaught exception: [Exception... "Could not convert JavaScript argument" nsresult: "0x80570009 (NS_ERROR_XPC_BAD_CONVERT_JS)" location: "JS frame :: chrome://global/content/bindings/tabbrowser.xml :: addTab :: line 1161" data: no]
I make a guess that childNodes.length is not zero, but 1 by default (i.e., there is always at least one tab, even if it isn't visible). A quick modification to the code, and I test again:
if (this.mTabContainer.childNodes.length == 1) {
...
Third Attempt
This works, but only the first time I create a new tab. Clearly I still have some misconceptions about how mTabContainer.selectedIndex and mTabContainer.insertBefore() really work.
I can't yet see how my code is wrong, but the exception I'm getting clearly indicates that I've got some sort of type conversion problem. I decide to look again at the code examples in tabbrowser.xml that I'm using as a guide, specifically insertChild().
After a few seconds the error is obvious: I've used an Integer where a Tab was required. Here is the corrected code:
// Insert tab after current tab, not at end.
if (this.mTabContainer.childNodes.length == 1) {
this.mTabContainer.appendChild(t);
} else {
var currentTabIndex = this.mTabContainer.selectedIndex;
this.mTabContainer.insertBefore(t, this.mTabContainer.childNodes.item(currentTabIndex + 1));
}
Success, and some bugs
After repackaging the toolkit.jar file and running the browser, I'm able to confirm that this last change has been successful. Opening a new tab now works in the way I originally described. I make a few more tests to insure that I haven't broken anything else, for example, what happens if I am on the last tab and not in the middle. This works, which makes me realize that using append() is probably not necessary at all, and I can safely shorten my code down to the following:
// Insert tab after current tab, not at end. var currentTabIndex = this.mTabContainer.selectedIndex; this.mTabContainer.insertBefore(t, this.mTabContainer.childNodes.item(currentTabIndex + 1));
This means that six lines of code become two, and with that reduction in number of lines, hopefully a reduction in new bugs I've added (NOTE: within reason, favour fewer rather than more lines of code).
Speaking of bugs, a closer read of addTab (see line 1219) would indicate that we've introduced a few with our new positioning code:
// wire up a progress listener for the new browser object. var position = this.mTabContainer.childNodes.length-1; var tabListener = this.mTabProgressListener(t, b, blank); ... this.mTabListeners[position] = tabListener; this.mTabFilters[position] = filter; ... t._tPos = position;
Where the assumption before was that the newly created tab was at the end of the list, the new code breaks that. Therefore, we also need to update the value of position
// wire up a progress listener for the new browser object. var position = currentTabIndex + 1
No other obvious defects are visible from our changes.
Reflections
The change I was making was simple enough that I didn't bother looking at any documentation or using the JavaScript debugger. I found out afterward that tabbrowser has good documentation on MDC.
Another trick worth trying when you're making lots of JavaScript changes like this is to add the following line to your .mozconfig file:
ac_add_options --enable-chrome-format=flat
This will cause the .jar files to be expanded so that you can edit the .xml/.js/.xul files in place and skip the repackaging step above (see http://www.mozilla.org/build/jar-packaging.html). If you also use the Extension Developer's extension you can reload the chrome without restarting the browser.
