Basics

1. Extension Manager

To open the extension manager, do: M-x extensions.

Note: there are some circumstances under which the extensions manager does not complete loading. This debian bug report describes some of the symptoms and some possible solutions http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=683343

If you encounter this problem, you may be able to install extensions directly, without going through the extension manager.

2. Installing Extensions

If you are unable to use the extension manager, you can open a URL pointing to the .xpi file for the extension, either a web url or a local file url (if you have already downloaded the .xpi).

There is a security system in Mozilla that prevents you from installing xpi files from unknown sites. Conkeror does not yet have a complete UI for managing trusted sites, so you may encounter silent failure when trying to install an extension. One option is to download the xpi file and install it from your own computer. Another option is to disable the security system like this: 

session_pref("xpinstall.whitelist.required", false);

3. Tried Extensions

Many Mozilla/Firefox extensions work fully or partially with Conkeror. Some work unmodified out of the box, while others require a bit of tweaking. Here is a collection of notes about the extensions we have tried.

4. Compatibility

While a few extensions work out of the box with Conkeror, most extensions are, properly speaking, Firefox extensions, meaning that they were written for Firefox and often have in greater or lesser degree, dependencies on features only found in Firefox. The Conkeror user looking to use such extensions should expect to be in for a little bit of work. Following are the typical steps to take with a new extension.

5. Normal Install

First try to install the extension. If it installs without complaint, that means it is already either explicitly marked as compatible with Conkeror, or compatible with toolkit, which is another word for XULRunner. Skip Forced Install and go straight on to Glue Code. But if normal install failed with an error about not being compatible, read on.

6. Forced Install

The most assured way to force an extension to install in Conkeror when it is not marked as compatible is to make one or two changes to files in the xpi archive of the extension. Save the xpi to disk, and make the following changes to it. The xpi file is a zip archive, so Emacs' archive-mode can be used to make these changes, or, for those allergic to Emacs, you can unzip the file, make the changes, and make a new zip.

6.1. Edit install.rdf

All extensions contains a file in their root called install.rdf. This file is a kind of manifest of the name, author, version, and description of the extension, and most interestingly, what programs it is compatible with.

The file will contain one or more stanzas of em:targetApplication listing the compatible programs. em:id should be either toolkit@mozilla.org or {a79fe89b-6662-4ff4-8e88-09950ad4dfde}.

Min and maxVersion must match your xulrunner or Firefox. The resulting stanza should look something like this: 

<!-- Conkeror -->
<em:targetApplication>
    <Description>
        <em:id>{a79fe89b-6662-4ff4-8e88-09950ad4dfde}</em:id>
        <em:minVersion>0.1</em:minVersion>
        <em:maxVersion>9.9</em:maxVersion>
    </Description>
</em:targetApplication>

6.2. Delete META-INF Files

Some extensions contain a directory called META-INF. The files in it are simply a digital signature to prevent people from installing files that have been tampered with. (Imagine that.) If you modified any files in the extension, you will need to delete the META-INF files in order to force an install of the extension.

7. Glue Code

Installing an extension is usually only half the work. The other half is writing glue to be able to use the extension in Conkeror. This typically involves writing one or more Conkeror commands to invoke the features provided by the extension. Extensions that have deep dependencies on behaviors unique to Firefox will be more of a challenge than simple ones, or ones designed for portability across applications. There is no way we can tell you everything you need to know to write glue code for extensions, but we can give you a few examples. How these examples apply in the case of each individual extension will vary widely, and fluency in javascript and knowledge of the Mozilla Extension platform will be your best tools for success.

TO-DO: links to info about how extensions work.

TO-DO: example code for common things like opening chrome windows.

8. Jetpack

Jetpack is a Mozilla sdk for building extensions more easily than by the traditional method, so we can make some general notes that will apply to any extension built with Jetpack.

8.1. Panel

Jetpack's 'panel' feature is Firefox-only.