The story of a non-hacker who wrote a Firefox add-on

Ever wonder what it’s like for a non-hacker to jump into Mozilla’s world of add-on development?  If you’re reading this on Planet Mozilla, there’s a very good chance you have a lot more technical background than a guy like me.  But, maybe you’d like to read about a non-developer’s first attempt at writing an extension.

Here’s my story.

Last week, I found myself repeatedly performing the same task with my browser.  Over and over again, I would click on the “View” menu option in Firefox, select the “Toolbars” option and then mouse over to “Bookmark Toolbar”.  Why?   I have daily tasks that use bookmarklets that I’ve placed in my bookmark toolbar.  However, I like a sleek look for my browser, so I always choose to hide extra features like toolbars and sidebars.  You can imagine that the process of collapsing and uncollapsing my bookmark bar got a bit tiresome and it triggered the thought: “What if I built an extension that could take care of this for me?”

My curiosity to develop an extension for Firefox had always been overshadowed by a bit of timidity in crossing into the world of development.  I am not a developer, having taken only two or so CS courses in college.  What if I had a question?  Who would I ask without seeming to waste a Mozilla developer’s very valuable time?  Forget it…just move on, right?  Well, not this time…I felt like I had a good idea and was curious.  So I gave it a try.

Before going further, let me share the extension.  It’s called the “Bookmark Bar Toggler” and you can install by following this link.   The add-on remains in Mozilla’s add-on sandbox and will be in “experimental” phase until it moves into recommended status.  Therefore, you have to log into addons.mozilla.org to get this extension until it becomes recommended by AMO.  The Bookmark Bar Toggler allows a user to add a button to the chrome of the browser that collapses and uncollapses the bookmark bar.

After realizing I had an idea that an extension could solve, I began to search around on just how to make it.  I felt that this would be a terrific experiment.  Can I actually write an extension and then blog about the pain and/or joy of the process?

So, last Wednesday night, I looked at Mozilla Developer Center to see what I could find on extension development.   I found the page: “Building an Extension“.  It looks like Ben Goodger started this back in 2005.  Thanks, Ben.  Also, many thanks to Eric “Sheppy” Shepherd (docs guru) and all the folks from the community who have edited it to its present state.  “Building an Extension” takes the most novice (me) through the process of setting up an environment on the OS, creating a chrome manifest, and writing the XUL and JavaScript code.  I followed the step-by-step process to build the sample “Hello World” extension.  I eventually got it working, but not without some frustration.

One of the first things this tutorial asked me to do was to create the install.rdf.  In the install.rdf example, I was asked to cut and paste several lines of code into a document.  Admittedly, I was a bit anxious to begin hacking on my idea, so I changed some stuff that I thought I would use for my eventual extension.  Specifically, I changed “<em:id>sample@example.net</em:id>” to what I thought would be my extension’s ID.  I chose “firefox.toolbar.tray”.  Why did I do this?  Not sure…in hindsight the name doesn’t even really make sense.  But, the XUL hackers reading this will know that I changed the syntax to something incorrect, even though it tells me RIGHT IN THE TUTORIAL that this has to be “in email address format”!  Notice that my ID has no “@” symbol.  I thought I had followed every step, but my “Hello World” just wouldn’t work.  I eventually had to go back and recheck everything until I saw this error.  I was reminded not to be hasty, but also I had to wonder, why didn’t a flag pop up and tell me that this was an issue?  It might have been nice for some error message to have popped up somewhere alerting me to this syntax error.  Is that possible?  Another possible piece of feedback, maybe we should make the instructions about that syntax even more explicit.  Only newcomers are going to read this documentation, so let’s make it painfully obvious.  I must have spent nearly 2 hours trying to find this simple error.

Another error I found in my install.rdf was incorrectly referencing the version of Firefox where this extension would work.  At first, I had entered the <em:maxVersion> to be 3.x.  I just didn’t know what to put in there.  But, this was not correct.  I eventually found that I had to change the code to <em:maxVersion>3.0pre</em:maxVersion>for my extension to work.  This wasn’t really documented too well and it would have been nice to get some sort of error message…but I eventually figured it out by looking at other install.rdfs and seeing the proper syntax.

Eventually, I got “Hello World” to show up in the bottom status bar of my browser and began to feel like I was in business.  It was time to start figuring out how I was going to create a button that would make my bookmark bar collapse and uncollapse whenever I clicked it.  Web searches led me to this great article on MDC:  Custom Toolbar Button.  Could it be this easy?  I had the sample extension I just built on my computer to use as a framework, and now I had a tutorial on how to add a toolbar button to the chrome of the browser.

I began walking through the tutorial and thinking about what I wanted the extension to do.  I wasn’t able to find every answer on the Web, so I turned to the Mozilla community for some help.  So many tools exist for someone to access when needed:  MDC, irc.mozilla.org, Planet Mozilla, MXR / LXR, and more.  I’d be foolish to try to convince anyone reading this post that I know how to code in CSS, XUL or JavaScript, I don’t.  But, that didn’t mean I couldn’t ask or poke around to find answers to my questions.  That’s just what I did.  I got on IRC and asked some random questions to developers I knew would answer.  I could have easily visited #extdev to ask the extension development community about what I was trying to do, but chose to call on individuals I knew…either method would have worked.  With the “Custom Toolbar Button” tutorial and some persistence, I quickly learned how to create a set of CSS, XUL, and JS files that would get my extension running.  (Stick with me non-hackers…it wasn’t too tough.)  The explanations are all directly in the tutorial and it wasn’t hard to piece together and then figure out where I had bugs.

The trickiest part for me was writing the JavaScript.  I knew I had to expand the sample function that was set up in the MDC tutorial.  The skeleton was there and I had my ideas. I used the DOM inspector to inspect the browser chrome and find the exact name of bookmark toolbar that my function would reference.  Then, I got a tip to look at some SeaMonkey code in LXR and saw the “collapse” command.  I also got a tip on the final line of code, which dictates the state of the command (whether the bookmark bar was collapsed or not) to persist after I restarted or shutdown.  That code was in the SeaMonkey source here, line 4491.

I ended up with the following code:

function OpenCloseBookmarkBar() {
var elem = document.getElementById(”PersonalToolbar”);
elem.collapsed = !elem.collapsed;
document.persist(”PersonalToolbar”, “collapsed”);
}

Really not too hard to understand, is it? I admit, I stumbled through writing this.  But once I had it, it was easier for me to see how it worked.  Many thanks to sspitzer for a tutorial how to write this code.  Couldn’t have done it without the help of one of Mozilla’s long-time Jedis…sspitzer.

Another tricky part was creating the correct order of the lines of code in the XUL file.  I misplaced my JavaScript command in that file, as well as the reference to the CSS code.  But, once I saw that this was in the wrong order (by looking at other, similar XUL files and asking around), I changed it to the correct order.  In a perfect world, I probably could have used some better documentation on this.  XUL seems like it can be a pretty tricky language and structuring these files for a newcomer is pretty foreign.

The next step was designing the button for the chrome of the browser.  I went back to lxr and got the .PNG file for the Firefox 3 Mac theme.   Asa gave me some great tips on how to perfectly crop out and edit the section I wanted and, voila, I had a button for my extension.

The “Building an Extension” tutorial gives a great tutorial on how to package up the extension.  I followed these guidelines, zipped up my files, and put the extension on AMO.  To be honest, the process was really straight forward and not too painful.

It is obvious that so many community members have put work into this process.  For a non-developer, it’s not perfect, but it’s pretty damn close.  Congratulations and thanks to everyone who had some effort in making extension development easy (MDC, AMO, those who are on IRC and ready to help…), it wasn’t bad at all, sincerely.

So, what did I learn and what’s next?

1. Version 2 of this extension needs to have a few things:  I have to create images that look good on other platforms; I am going to work on l10n; and I want to add key stroke commands that will collapse and uncollapse the toolbar.  Do you have any other recommendations?  You know the drill, comment on this post.
2. I learned that MDC is awesome.  Really, this is a great resource from the Mozilla Community.  I was impressed how much of the documentation was already updated for Firefox 3!  Writing this extension would have been impossible without the community’s work on MDC.  What a terrific resource.
3. It would be nice if there was some built in XUL debugger or error messenger that pointed out syntax errors and other things like where to place lines of code.  I don’t even know if this is possible or if it exists, but it was a thought I had.
4. The addons.mozilla.org upload process was very well designed.  It allowed me to write a detailed description of my add-on and get it in the sandbox without a challenge.  Add-on developers are probably familiar with this experience, but for a newcomer, it was a great user experience.  What do you think?
5. The Mozilla Community does it again…couldn’t have done any of this without those who were responsive to my questions or those who helped write the documentation.  Special thanks to Seth Spitzer, Asa, the guys on IRC, Dan Mills (irc nick: Thunder) for some thought provoking conversation, and all those who wrote this great documentation.
6. Extension development is not as scary as I thought it would be.  I really wanted to demystify the experience.  With so many tools on the Web, a community of developers who will answer questions, and so much open source code to look at, I came away thinking that the biggest challenge is probably finding an idea and knowing how to do good web searches…just like when I had the idea to buy a new Nintendo Wii for $300.  That was also challenging, but I had the idea and performed some superb web searches. Time for some Guitar Hero 3 with Xavier Stone and  Casey Lynch.

That’s it.  Happy to enter the world of AMO as a novice hacker.  I’ll keep playing around with it to see how I can make this extension better.

Oh…and please install my extension and tell me what you think.