Chris Schmidt (crschmidt) wrote,
Chris Schmidt
crschmidt

Creating a Mozilla extension: Walkthrough

Since some people have demonstrated an interest in my recent creation of a Firefox plugin, I'm writing a walkthrough as to how such a thing is created. This document will hopefully serve to answer the questions I had, but couldn't answer for myself. Many of the tutorials out there are informative, but too complex for creation of a simple plugin. Hopefully this will correct that.

This tutorial demonstrates how to build a status-bar type Mozilla extension.


First, you should download the framework for this tutorial, at http://crschmidt.net/walkthrough/extensionname.xpi . If you don't want to download it, I've set links up so you can follow along anyway. Some files have slightly different names in the web version, to accomodate for browsers that ignore content-type headers. This framework is a simple way to begin writing an extension which creates a status bar icon, lets it change the icon to something new based on a Javascript function, and lets something happen when that icon is clicked.

I have added "extensionname" to most functions that are specific to this extension. You should keep something that uniquely identifies your functions in your Javascript at all times - Mozilla extensions are, apparently, not run in a sandbox, so your functions can overwrite other peoples.

The first thing to do, after you have downloaded the file, is unzip it. This results in two files: install.rdf, which is a manifest of your Extension, and a chrome folder with an extensionname.jar in it.

$Editor the install.rdf file. As you can see, it is simply RDF, using the RDF and "em" namespaces to describe the package.

  • em:id is a specific string related to your project. In order to create a uuid, run "uuidgen" on any *nix box:
    [crschmidt@zeus ~]$ uuidgen 
    6ab234de-d450-46f4-9ebd-31ebee52be20
    .
  • Version number. Version number of your extension
  • targetApplication, assuming you're building for Firefox, can be left alone.
  • name, description, creator, homepageURL: all self explanatory. Insert your own.
  • File: we are going to include one java jar file in this package. It is currently named extensionname. You will probably want to change this in the Description and package lines


Change to the chrome directory. Here you can see we have a .jar file, which is again, really just a zip file. Unzip "extensionname.jar", to create the content directory: change into it, then into the extensionname directory.

This is the meat of the extension. Here you have the description:

  • browserOverlay.xul: Changes to the actual Mozilla interface. This is where we're going to describe our statusbar item.
  • browserOverlay.js: Javascript code to tell our statusbar icon how to behave.
  • extensionname.css: CSS to describe various properties. Not really useful in this case, as we're not using CSS to do our work.
  • extensionname*.png: Images for `on` and `off` in the statusbar.


In addition to these, you have a contents.rdf file. This file contains information about your plugin: specifically, the .xul file, which relates it the file to the browser. You'll need to change anything that says "extensionname" to the name of your extension. You'll most likely also want to change the extensionname.png files to have a name that better mirrors your extensionname, although this is not strictly required.

Next, edit the browserOverlay.xul file. As you can see, this file is an RDF/XML description of the changes you will be making to the browser. Also, it includes the CSS and Javascript for the plugin. Again, change the "extensionname" to the appropriate extensionname for your plugin. In our script, we're going to add a "LoadListener" - something that gets called on Load, so that we can listen for navigation and tab changes. You can see that once we include our Javascript file, we add the LoadListener, then go on to defining a new statusbar item.

The statsbar has a tooltip, with an id and a description. This tooltip will appear over the statusbarpanel we are about to create.

The statusbarpanel has a class that identifies it as being for an icon: statusbarpanel-iconic. It also has an ID, which we will use in the javascript, and a javascript function, from browserOverlay.js, to perform when clicked. The insertafter is the default location for most statusbar items. Lastly, we add a tooltip to the statsubar item.

Next we edit the browserOverlay.js file, which contains the code which actually controls the icon. At the top we define several functions: getBrowser() and getDocument(), both used to make things easier because the typical javascript models don't work quite as expected, because we aren't executing from within the window.

Next is the part of the extension that you'll need to edit:
  • lightup: Code to determine whether the icon should change to "On" mode.
  • extensionname_lightup: Code to change the icon image to the "lit up" or "on" version.
  • main_extensionname: Code which is executed on loading a page or tab. (As determined by the LoadListener.
  • extensionname_clicked: Javascript to perform when the icon is clicked.
  • addLoadListener: Function to add event checking. The default checks for navigation or tab events.
The flow of the function comes in through the LoadListener. It is then passed to the main_ function if a tab switch or navigation event has occured. Here, we get the Element labelled extensionname-status: this is the name of our statusbar icon. We set the icon to be in the "off" state, then call "lightup". If the icon needs to be lit up - as determined by the "lightup" function, then we change the image to be the lit up version. Mozilla captures clicks for us, and delivers them to extensionname_clicked. Voila! The code is done! Now, what to do with it? Change to the root directory of the project. (The one with the install.rdf.) Remove all but the chrome and install.rdf files. Change to the chrome directory. Remove all but the "content" directory. Then issue the following commands: zip -r extensionname.jar content/ rm -rf content cd .. zip -r extensionname.xpi * Now you have a fully functional Mozilla extension, packaged in a xpi format, which can be installed using javascript, as in http://crschmidt.net/doap/doaper.html . This page is available in wiki form, although not yet completely copied over, at http://crschmidt.net/mywiki/ExampleExtension . Any edits you wish to make for correctness can be made there.
Subscribe
  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 2 comments