Creating FireFox Starter Extensions

This article provides step-by-step instructions on how to develop the simplest extension for FireFox.
This is a partial translation of the original article .

This is not my article, but my friend (his story: templar8@gmail.com). He really wants to get on Habr. I myself do not have enough karma for invite.

Introduction

This guide is a step-by-step instruction on how to create the simplest extension. We will try to add another small panel with the phrase “Hello, World!” To the status bar.

Environment preparation

Extensions are packaged and distributed as zip-files or packages with the extension XPI.
')
Here is an example of a typical internal XPI file structure:

exampleExt.xpi:
/install.rdf
/components/*
/components/cmdline.js
/defaults/
/defaults/preferences/*.js
/plugins/*
/chrome.manifest
/chrome/icons/default/*
/chrome/
/chrome/content/

We need to create a directory structure similar to this. First, create a root extension directory (for example, C:\extensions\my_extension\ or ~/extensions/my_extension/ ). Inside this directory, create a chrome directory in which to create a content directory.

In the root directory of the extension, create two empty text files with the names chrome.manifest and install.rdf . The result should be a directory structure of the following form:

<ext path>\
install.rdf
chrome.manifest
chrome\
content\

Additional information on setting up the environment can be found here .

Installation script

Open the install.rdf file and add the following text to it:

1. <? xml version = "1.0" ? >
3. < RDF xmlns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
4. xmlns: em = "http://www.mozilla.org/2004/em-rdf#" >
6. < Description about = "urn: mozilla: install-manifest" >
7. < em: id > sample@example.net </ em: id >
8. < em: version > 1.0 </ em: version >
9. < em: type > 2 </ em: type >
11. <! - Target Application this extension can install into,
12. with minimum and maximum supported versions. ->
13. < em: targetApplication >
14. < Description >
15. < em: id > {ec8030f7-c20a-464f-9b0e-13a3a9e97384} </ em: id >
16. < em: minVersion > 1.5 </ em: minVersion >
17. < em: maxVersion > 3.0. * </ em: maxVersion >
18. </ Description >
19. </ em: targetApplication >
21. <! - Front End MetaData ->
22. < em: name > sample </ em: name >
23. < em: description > A test extension </ em: description >
24. < em: creator > Your Name Here </ em: creator >
25. < em: homepageURL > www.example.com </ em: homepageURL >
26. </ Description >
27. </ Rdf >

* This source code was highlighted with Source Code Highlighter .

• sample@example.net is the extension ID. This value is written in the email address format and is required to identify the extension (it should not be your email address). Make it unique. You can also use the GUID. NOTE: Although this parameter is written in the email address format, it does not have to be valid. (example.example.example)
  
• The <em:type>2</em:type> - 2 parameter indicates that this will be an extension. For example, for design themes, this value should be set to 4 (all type codes can be found here ).
  
• {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - ID of Firefox (note. Lane - apparently, for Thunderbird will be a different value).
  
• 1.5 - the number of the minimum required for the expansion version of Firefox. Never use the * symbol to indicate minVersion, this can lead to unexpected results.
  
• 3.0. * - the maximum version number of Firefox with which the extension will work. This value should be no newer than the latest version of the browser at the moment! In this case, “3.0. *” Indicates that the extension will work with Firefox 3.0 and versions 3.0.x.
  

(If you received a message that install.rdf is incorrect, it would be useful to download this file in Firefox (File-> Open file ...), after which the browser will show you xml errors. In my case there was a space before "<xml")

Extensions created to work with Firefox 2.0.0.x, you need to specify as the maximum version of "2.0.0. *". For extensions created for working with Firefox 1.5.0.x - "1.5.0. *".

A list of required and optional parameters of the installation script can be found here .

Save the file.

Browser extension using XUL

The Firefox user interface is written using XUL and JavaScript. XUL is an XML subtype that allows you to create user interface elements, such as buttons, menus, control panels, trees, and so on. All user actions are processed using JavaScript.

To "expand" the browser, we modify individual parts of the Firefox user interface by adding or modifying widgets (controls). We add widgets by adding new XUL DOM elements to the browser window and control their behavior using scripts and event handling.

The browser interface is defined in browser.xul ( $FIREFOX_INSTALL_DIR/chrome/browser.jar contains content/browser/browser.xul ) In browser.xul we can find a description of a status bar that looks something like this:

1. < statusbar id = "status-bar" >
2. ... < statusbarpanel > ...
3. </ statusbar >

* This source code was highlighted with Source Code Highlighter .

<statusbar id="status-bar"> is the “tie point” of the XUL layer.

XUL layers

XUL layers are a way to add widgets to a XUL document. A XUL layer is a .xul file that defines XUL fragments that describe tie points in a “main” document. These fragments can point to widgets that will be added, deleted, or changed.

Sample XUL Layer Document

1. <? xml version = "1.0" ? >
2. < overlay id = "sample"
3. xmlns = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" >
4. < statusbar id = "status-bar" >
5. < statusbarpanel id = "my-panel" label = "Hello, World" />
6. </ statusbar >
7. </ overlay >

* This source code was highlighted with Source Code Highlighter .

The <statusbar> with an id equal to “ status-bar ” indicates the browser widget to which we want to add our element.

The <statusbarpanel> is a new widget that we want to add.

Save this code in the sample.xul file sample.xul the chrome/content directory.

Chrome URIs

XUL files are part of the so-called. “ Chrome Packages ” are packages of user interface elements loaded via the chrome:// URI. Instead of loading the interface using file:// URIs (especially Firefox’s location may vary depending on the platform and systems), Mozilla’s developers decided to create a new URI type, using which all installed applications will have access to XUL content.

The URI for the browser window is chrome://browser/content/browser.xul . Try entering this URL in the Firefox address bar.

Chrome URI consists of several parts:

• The 1st is the protocol ( chrome ), which tells the Firefox network library that this is a Chrome URI.
  
• The 2nd is the package name (in this example, browser ), which points to a set of user interface components. For your application, this part must be unique, in order to avoid conflicts with other extensions.
  
• 3rd - the type of data requested. There are three types: content (XUL, JavaScript, XBL links and other components of the user interface of an application), locale (DTDs, .properties files, which may contain other files containing user interface localization lines) and skin (CSS and theme images) .
  
• The last part is the path to the downloaded file.
  

For example, chrome://foo/skin/bar.png loads the file bar.png from the skin section of the foo theme.

When you download something using the Chrome URI, Firefox uses the Chrome Registry (Chrome Registry) to convert this URI to the actual file path on disk (or in JAR archives).

Create Chrome Manifest

For more information on Chrome Manifest and all of its properties, refer to the reference guide .

Open the chrome.manifest file that was created in the root directory of your extension. Add the following code:

content sample chrome/content/

( Do not forget about the closing slash, “/”! Without it, the package will not be registered.)

Let's sort each element:

1. chrome package type
2. chrome package name (must be written in lower case, because Firefox / Thunderbird in version 2 and earlier do not support mixed case names - bug 132183 )
   
3. placing chrome package files

This means that the sample package files are located in the chrome/content directory relative to the location of the chrome.manifest file.

Please note that the content, localization and skin files must be inside the content, locale and skin directories of the chrome subdirectory, respectively.

Save the file. Now, when you launch Firefox with your extension (how to do this will be described below), the chrome package will be registered.

Register layer

Now you need to associate your layer with the browser window. To do this, add the following lines to the chrome.manifest file:

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

These two lines tell Firefox to link sample.xul and browser.xul while browser.xul loading.

Testing

First, we need to tell Firefox about our extension. At the development stage for Firefox version 2 and higher, you can specify where to get the new extension, and the browser will load it after each restart.

1. Go to your home directory , and then to the directory containing the Firefox profile you are going to work with (for example, Firefox/Profiles/<profile_id>.default/ ).
   
2. Go to the extensions/ directory, if it does not exist, create one.
   
3. Create a text file and place in it the full path to the directory with your extension (for example, C:\extensions\my_extension\ or ~/extensions/my_extension/ ). Windows users should be aware of the direction of the slash, be sure to add the closing slash and remove all trailing spaces.
   
4. Save the file with the extension id as its name (for example, sample@example.net). No file extension.
   

Now everything is ready for testing.

Launch Firefox. Firefox on the text link itself will find a directory with your extension and install it. After launching the browser, you will see the inscription “Hello, World!” On the right side of the status bar.

You can make some changes to the .xul file, restart Firefox, and immediately see the result.

Build Package

Now that the extension is working, you can create a package for distribution and installation.

Zip the contents of the directory with your extension (not the extension directory itself) with the zip archiver and change the extension of the archive from .zip to .xpi.

If you are the happy owner of Extension Builder, it can do all the dirty work for you (Tools -> Extension Developer -> Extension Builder). Just go to the directory with your extension and click the Build Extension button. This extension has a lot of tools to facilitate development.

Now upload the resulting .xpi file to your server and make sure its type is set to application/x-xpinstall . After that, you can download and install the extension.