View source for Getting started with extension development

{{extdev}}
Two major extension developers' features introduced in Firefox 1.5 were the [http://developer.mozilla.org/en/docs/Chrome_Registration greatly simplified chrome registration scheme] and the [http://www.mozilla.org/projects/firefox/extensions/em-changes.html reworked Extension Manager]. These changes make it even easier to start writing extensions.

This article describes steps needed to get started with extensions development. Last two sections have a few development tips and packaging information. Most of it is targeted at beginners in extension development, although the setup tips should be useful for everybody. This article is concise and doesn't go into discussing the technologies involved; it's more of a crash-course. Another, more detailed tutorial, is available at [http://developer.mozilla.org/en/docs/Building_an_Extension developer.mozilla.org].

It's a wiki page, so feel free to make improvements to this page and to add your feedback on the Talk page. However questions and requests for help are better suited for the [http://forums.mozillazine.org/viewforum.php?f=19 forums].

'''Extensions created in this way will only work on Firefox/Thunderbird 1.5 and later''', but you should be able to make changes to ensure your extension is compatible with Firefox 1.0 quite easily.

'''Again, this will work only in Firefox/Thunderbird 1.5 or later, not 1.0.x!''' Not 1.0.6, 1.0.7 or anything like that. Only 1.5 or later.

== Setting up your environment ==
This article focuses on Firefox extensions, although it also applies to other Toolkit applications, such as Thunderbird.

The first thing you need to do is download a recent version of your application. You can get Firefox [http://mozilla.com/firefox here]. As was mentioned above, you need Firefox 1.5 or later, setup tips from this article will not work in earlier versions.

For further instructions, see [[Setting up extension development environment]]. '''Do read that page, it will save you many hours when developing and debugging your extension.''' In particular, you must set the '''javascript.options.showInConsole''' pref to '''true'''.

=== What this Extension Does ===
This extension adds an item called 'Hello World!' to the Tools Menu in Firefox.   It's a good example of creating an extension that pops up a new window when you activate it.

=== Planning your extension ===
You should plan what you need for your extension; we will use an example that provides a new menu option that creates a message in a window. The following files are required, choose your own names if you like (but if you change any names remember to update all references to them), except for the folders and files ''''chrome.manifest'''' and ''''install.rdf''''.

{| {{prettytable}}
!Filename!!Purpose
|-
|chrome.manifest||Tells Firefox where your chrome files are and what to do with them
|-
|install.rdf||The description file for your extension ("Install manifest")
|-
|overlay.xul||The file describing UI elements to add to the browser window
|-
|overlay.js||The file with scripts to run in the browser window
|-
|overlay.dtd||Contains translation for text string codes in overlay.xul
|-
|hello.dtd||Contains translation for the strings in hello.xul
|-
|overlay.css||Lets you adjust appearance of UI elements with CSS
|-
|hello.xul||The file describing the UI of the new window
|-
|helloworld@mozilla.doslash.org||A pointer to your extension files
|}

== Creating stub extension files ==
As you should already know, extensions usually modify an application's UI ("''chrome''") and behavior by providing ''overlays'' to already existent windows/documents. Those overlays are a part of the extension's ''content'' package (''content provider''). Most extensions also have one or more ''locales'' and ''skins''. (If you didn't know that, we advise you to read [https://developer.mozilla.org/en-US/docs/XUL/Tutorial The Developer.Mozilla.org XUL Tutorial]. 

This section describes what directory structure and what files are needed in order to make Firefox register your extension's files.

You can download the [http://mozilla.doslash.org/stuff/helloworld.zip ZIP file] with all necessary stub files and appropriate folder structure and skip to [[#reg-em|Registering your extension in the Extension Manager]]. It's recommended that you nonetheless read the below subsections, as they explain the function of each file in the package and provide links to other resources.

=== Folder structure ===
Below is the folder structure we will use. You may use a different structure, as long as you also update your chrome.manifest (see below) accordingly. Create the following structure in the folder where you intend to develop your project:
 '''helloworld/'''
   chrome.manifest
   install.rdf
   '''content/'''
     overlay.js
     overlay.xul
     hello.xul
   '''locale/'''
     '''en-US/'''
       overlay.dtd
       hello.dtd
   '''skin/'''
       overlay.css

The folders are traditionally named "content", "locale" and "skin", and you should follow the tradition. You may call the files inside those folders whatever you want (except '''chrome.manifest''' and '''install.rdf''').

'''Note:''' This folder structure is for development, you'll need different folder structure when [[#Packaging|packaging your extension]].

=== Stub files ===
==== chrome.manifest ====
Recent versions of Firefox read a simple plaintext chrome.manifest file (instead of the old and confusing [[contents.rdf]]) to determine what packages and overlays your extension provides. The format of this file is described in the [http://developer.mozilla.org/en/docs/Chrome_Registration Chrome Registration] document. In the following example we'll create a chrome.manifest file for our folder structure.

It looks like this (assuming your extension's package name is "''helloworld''"):

{| {{prettytable}}
! <tt>
1<br>2<br>3<br>4<br>5<br>6<br>7
</tt>
||
<tt>
content	helloworld content/ <br>
overlay	chrome://browser/content/browser.xul	chrome://helloworld/content/overlay.xul<br>
<br>
locale	helloworld	en-US	locale/en-US/<br>
<br>
skin	helloworld	classic/1.0	skin/<br>
style	chrome://global/content/customizeToolbar.xul	chrome://helloworld/skin/overlay.css<br>
</tt>
|}

'''What each line of the file does:'''
* Line 1 registers a content provider: it maps the contents of <code>chrome://helloworld/content/</code> to the ''content'' folder.
* Line 2 registers an overlay for <code>chrome://browser/content/browser.xul</code> location, allowing you to modify Firefox's main window UI from your overlay.xul file.
* Line 4 registers a en-US locale provider.
* Line 6 registers a default skin provider.
* Line 7 applies your ''overlay.css'' style file to <code>chrome://global/content/customizeToolbar.xul</code> document (used, for example, when [[creating toolbar buttons]]). You could instead register an overlay and include the stylesheet in the overlay using the <code><?xml-stylesheet?></code> processing instruction.

'''Warning''': Don't forget the end slash at the end of the paths : "content/" works, whereas "content" doesn't. Also note that the package name ('helloworld' in this case) has to be all lowercase.

'''Note:''' this file will be a bit different when you create an XPI for your extension, see the [[#Packaging|Packaging section]] below.

==== overlay.xul ====
overlay.xul is a simple XUL overlay. You can read more about overlays at [http://xulplanet.com/tutorials/xultu/overlay.html XUL Planet] and [http://developer.mozilla.org/en/docs/XUL_Overlays MDC].

A simple overlay looks like this:

{| {{prettytable}}
! <tt>
1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br>9<br>10<br>11<br>12
</tt>
||
<tt>
&lt;?xml version="1.0"?&gt; <br>
&lt;?xml-stylesheet href="chrome://helloworld/skin/overlay.css" type="text/css"?&gt; <br>
&lt;!DOCTYPE overlay SYSTEM "chrome://helloworld/locale/overlay.dtd"&gt; <br>
&lt;overlay id="helloworld-overlay" <br>
&nbsp;&nbsp;&nbsp;&nbsp;xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt; <br>
&nbsp;&nbsp;&lt;script src="overlay.js"/&gt; <br>
<br>
&nbsp;&nbsp;&lt;menupopup id="menu_ToolsPopup"&gt; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;menuitem id="helloworld-hello" label="&helloworld;" <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;oncommand="Helloworld.onMenuItemCommand(event);"/&gt; <br>
&nbsp;&nbsp;&lt;/menupopup&gt; <br>
&lt;/overlay&gt; <br>
</tt>
|}

'''What each line of the file does:'''
* Line 1 is the '''XML declaration''', specifying the version of XML being used. It can also be used to specify file's encoding, but that should seldom be needed, as you should put localizable strings in the DTD file.
* Line 2 is optional and can be used to apply a stylesheet to the base document.
* Line 3 is also optional, but recommended if you include any user-visible strings in your overlay. It is used to make your overlay localizable.
* Lines 4-5 define the root element of the overlay. It must be a XUL <code><overlay></code> element.
* Line 6 is optional and can be used to attach a JavaScript file to the base document. See next section for more information.
* Lines 8-10 add a menu item to the Tools menu in Firefox main window. See [[Adding items to menus]] for more information.

==== overlay.js ====
As you may know, JavaScript files are used to define application's behavior. Please refer to the list of [[Development resources#JavaScript|JavaScript development resources]] for information on JavaScript in general.

An important issue you should be aware of is that all scripts that are loaded for a given document (the scripts used by the window itself, and scripts loaded from overlays to that document) share the same scope. This means you should use unique names for global identifiers in your extensions to avoid clashing with other extensions. It's usually accomplished by prefixing all global identifiers with the name of your extension or by putting most/all of your variables and functions in an object with an unique name.

Typical JavaScript file for an overlay looks like this:
<pre>
var Helloworld = {
  onLoad: function() {
    // initialization code
    this.initialized = true;
  },

  onMenuItemCommand: function() {
    window.open("chrome://helloworld/content/hello.xul", "", "chrome");
  }
};

window.addEventListener("load", function(e) { Helloworld.onLoad(e); }, false); 
</pre>

==== overlay.dtd ====
DTD files are used to make XUL/XBL/XHTML and other XML files in Mozilla chrome localizable. Basically, instead of hard-coding the strings in your XUL file, you use '''XML entities''', which expand to the values declared in the DTD file referenced at the top of the XUL file.

It makes your extension localizable, because there may be a few different locale providers for your extension, and Mozilla is able to choose between them at run-time.

DTD files used for localization purposes consist of entity declarations like the one below:
 <!ENTITY helloworld "Hello World!">

==== hello.dtd ====
This is the file for the new window.
 <!ENTITY title.label "Hello World">
 <!ENTITY separate.label "This is a separate window!">
 <!ENTITY close.label "Close">

==== hello.xul ====
In addition to modifying existing windows, you can create new windows for your extensions. The UI of your own windows is also described in XUL files, but unlike overlays, the root element is a <window> or a <dialog>, and not <overlay>. Another difference from overlays is that you don't have to register each of new windows in chrome.manifest.

The example package includes file hello.xul, which is used to describe a simple window.
<pre>
<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/global.css"  type="text/css"?>
<!DOCTYPE window SYSTEM "chrome://helloworld/locale/hello.dtd">

<window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" 
        title="&title.label;">

<hbox align="center">
  <description flex="1">&separate.label;</description>
  <button label="&close.label;" oncommand="close();"/>
</hbox>

</window>
</pre>

==== install.rdf ====
install.rdf file is used by the Extension Manager when installing an XPI file and when registering an extension at specified location. In Firefox 1.5 and later it's only used to provide EM metadata, such as extension's ID, version, description, author etc. For more information, see [[install.rdf]] article.

<pre>
<?xml version="1.0"?>
<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>helloworld@mozilla.doslash.org</em:id>
    <em:name>Hello World (Firefox 1.5 or later edition)</em:name>
    <em:version>1.0</em:version>
    <em:description>Classic first extension from MozillaZine KB</em:description>
    <em:creator>Nickolay Ponomarev</em:creator>
    <!-- optional items -->
    <em:contributor>A person who helped you</em:contributor>
    <em:contributor>Another one</em:contributor>
    
    <em:homepageURL>http://kb.mozillazine.org/Getting_started_with_extension_development</em:homepageURL>
    <!-- em:optionsURL>chrome://sampleext/content/settings.xul</em:optionsURL>
    <em:aboutURL>chrome://sampleext/content/about.xul</em:aboutURL>
    <em:iconURL>chrome://sampleext/skin/mainicon.png</em:iconURL>
    
    <em:updateURL>http://sampleextension.mozdev.org/update.rdf</em:updateURL-->
    
    <!-- Firefox -->
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>2.0.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
    
  </Description>

</RDF>
</pre>

====overlay.css====
overlay.css is used by Firefox to apply a specific look to the extension component(s) you are installing.  In this case, we want to color the helloworld menuitem red.

'''NOTE:''' The coloring of menuitems is <u>not</u> recommended.  This is only an example.

<pre>
/* This is just an example. You shouldn't do this. */
menuitem#helloworld-hello {
  color: red !important;
}
</pre>

<i id="reg-em"></i>

== Registering your extension in the Extension Manager ==
Before releasing your extension to the public you must thoroughly test it. To avoid problems during this phase it is advisable to create and use a [[profile manager|new profile]] for testing it.

Once you have created the files described above and have placed them in the appropriate folder structure, registering them in the Extension Manager is trivial. With Firefox closed, create a "pointer" file with the same name as your extension's ID in <code>[[profile folder]]/extensions/</code> and edit it so that it contains the path to your folder containing '''install.rdf''' and '''chrome.manifest''' files.

E.g. helloworld's ID is <tt>helloworld@mozilla.doslash.org</tt> and we would like to register it in <tt>X:\Dev\helloworld\</tt> (i.e. there is <tt>X:\Dev\helloworld\install.rdf</tt> file etc.). Just put a single line into the file at this path: <tt>[[profile folder]]/extensions/helloworld@mozilla.doslash.org</tt>
 X:\Dev\helloworld

Start Firefox, and check that your extension is installed. Then test it.

== Development cycle ==
Once you have registered your extension following the steps above, developing your extension is quite easy. If you've set the [[Setting up extension development environment|development preferences]], your development cycle will be like this:
# Edit your extension files.
# Reopen the window(s) that modified files apply to, or use Reload chrome feature of Extension Developer Extension.  Because the Reload Chrome feature of the Extension Developer Extension does not work for Thunderbird, you can alternately use the [https://addons.mozilla.org/extensions/moreinfo.php?id=964&application=firefox Reloadchromezilla] extension for Thunderbird and Firefox 1.5.
#* If you changed '''chrome.manifest''', you'll have to restart.
#* If you changed '''install.rdf''', you need to ''touch'' the extension folder specified in your "pointer" file (update its ''Last modified'' time) and restart.
::(i.e. If you update c:\dev\helloworld\install.rdf you need to make sure the folder c:\dev\helloworld has a different timestamp.
::A quick way to do this on windows is to rename c:\dev\helloworld to c:\dev\helloworld-tmp, make a new helloworld folder, then copy the contents of the helloworld-tmp folder into the new helloworld folder. Alternatively, display the folder in Explorer, right click on the right hand side pane, and select New>Folder - then just delete the New Folder.
::On linux you could just use the <tt>touch</tt> command.)


It's much more convenient compared to the edit-rezip-restart cycle many extension authors were using or the pleasure of [[Dev_:_Tips_:_Disable_XUL_cache|editing chrome.rdf file or similar setup tricks]].

== Packaging ==
As it was mentioned, the folder structure and '''chrome.manifest''' file must be changed before packaging. Compare:
<table {{prettytable}}>
<tr><th>Developing</th><th>Packaging</th></tr>
<tr><th colspan="2">Folder structure</th></tr>
<tr valign="top">
<td>
 helloworld/
   chrome.manifest
   install.rdf
   components/
   defaults/
     preferences/
       mydefaults.js
   content/
     overlay.js
     overlay.xul
   locale/
     en-US/
       overlay.dtd
   skin/
     overlay.css
</td>
<td>
 helloworld.xpi/
   chrome.manifest
   install.rdf
   components/
   defaults/
     preferences/
       mydefaults.js
   '''chrome/'''
     '''helloworld.jar'''
       content/
         overlay.js
         overlay.xul
       locale/
         en-US/
           overlay.dtd
       skin/
         overlay.css
</td>
</tr>
<tr><th colspan="2">chrome.manifest (note extra "jar:chrome/helloworld.jar!/" in the right column)</th></tr>
<tr>
<td width="50%">
<div style="overflow: auto;">
<pre>
content	helloworld content/
overlay	chrome://browser/content/browser.xul	chrome://helloworld/content/overlay.xul

locale	helloworld	en-US	locale/en-US/

skin	helloworld	classic/1.0	skin/
style	chrome://global/content/customizeToolbar.xul	chrome://helloworld/skin/overlay.css
</pre>
</div>
</td>
<td width="50%">
<div style="overflow: auto;">
<pre>
content	helloworld jar:chrome/helloworld.jar!/content/
overlay	chrome://browser/content/browser.xul	chrome://helloworld/content/overlay.xul

locale	helloworld	en-US	jar:chrome/helloworld.jar!/locale/en-US/

skin	helloworld	classic/1.0	jar:chrome/helloworld.jar!/skin/
style	chrome://global/content/customizeToolbar.xul	chrome://helloworld/skin/overlay.css
</pre>
</div>
</td>
</tr>
</table>

Packaging your chrome files into a JAR file brings some benefits such a smaller download size however it also introduces unnecessary complexity and for many starting out it is generally easier to not use JAR files.

Some links and tools are available at [[Packaging extensions]].

== Resources ==
* Learn more about [[extension development]].
* Take a look at [[development resources]].
* See [[:Category:Example code|solutions to common XUL/JS/XPCOM programming problems]].
* Download the [http://mozilla.doslash.org/stuff/helloworld.zip ZIP file] with the stub files described in this article. (This only works in Firefox 1.5 or later, not in 1.0.x!)
** There's also a [http://mozilla.doslash.org/stuff/helloworld-tb.zip Thunderbird version of the template].
** Last, but not least, there's brilliant [http://ted.mielczarek.org/code/mozilla/extensionwiz/ Extension Wizard] by Ted Mielczarek, which helps you create a stub for your extension.
* If you have any problems try asking at the [http://forums.mozillazine.org/viewforum.php?f=19 forums] (after searching both the forums and Google!)

[[Category:Development]]