mozilla

Compare Revisions

Building an extension

Change Revisions

Revision 33399:

Revision 33399 by Sheppy on

Revision 33400:

Revision 33400 by Juiceyred on

Title:
Building an extension
Building an extension
Slug:
Building_an_Extension
Building_an_Extension
Tags:
NeedsTechnicalReview, Extensions, Add-ons, NeedsEditorialReview, NeedsUpdate
NeedsTechnicalReview, Extensions, Add-ons, NeedsEditorialReview, NeedsUpdate
Content:

Revision 33399
Revision 33400
n11      This tutorial will take you through the steps required to bn11      This tutorial will take you through the steps required to b
>uild a very basic <a href="en/Extensions">extension</a> - one whi>uild a very basic <a href="en/Extensions">extension</a> - one whi
>ch adds a status bar panel to the Firefox browser containing the >ch adds a status bar panel to the Firefox browser
>text "Hello, World!" 
n15        <b>Note</b> This tutorial is about building extensions fon15        <b>Bold text</b> THIS YOUR GIRL JUICEYRED WELCOME TO THE 
>r Firefox 1.5 or 2.0. Other tutorials exist for building extensio>JUICEY SPOT
>ns for earlier versions of Firefox. 
n17    </div>n
18    <h4 name="Setting_up_the_Development_Environment">17      <h4 name="Setting_up_the_Development_Environment">
19      Setting up the Development Environment18        Setting up the Development Environment
20    </h4>19      </h4>
21    <p>20      <p>
22      Extensions are packaged and distributed in ZIP files, or <a21        Extensions are packaged and distributed in ZIP files, or 
> href="en/Bundles">Bundles</a>, with the <tt>xpi</tt> (<i>pronoun><a href="en/Bundles">Bundles</a>, with the <tt>xpi</tt> (<i>prono
>ced “zippy”</i>) file extension. The layout of content within the>unced “zippy”</i>) file extension. The layout of content within t
> XPI file is like so:>he XPI file is like so:
23    </p>22      </p>
24    <pre class="eval">23      <pre class="eval">
n38    <p>n37      <p>
39      Because of this, it is easiest if we lay out our source fil38        Because of this, it is easiest if we lay out our source f
>es in a similar fashion, unless you want to write some sort of Ma>iles in a similar fashion, unless you want to write some sort of 
>kefile or shell script to package and zip all of your files. Even>Makefile or shell script to package and zip all of your files. Ev
> if you are prepared to do that, testing is much simpler if you l>en if you are prepared to do that, testing is much simpler if you
>ay out your files like this because of a feature of the Add-on Sy> lay out your files like this because of a feature of the Add-on 
>stem provided by Firefox 1.5 and later.>System provided by Firefox 1.5 and later.
40    </p>39      </p>
41    <p>40      <p>
42      So let's get started. Create a folder for your extension so41        So let's get started. Create a folder for your extension 
>mewhere on your hard disk, e.g. <tt>C:\extensions\myExtension\</t>somewhere on your hard disk, e.g. <tt>C:\extensions\myExtension\<
>t> or <tt>~/extensions/myExtension/</tt>. Inside this folder crea>/tt> or <tt>~/extensions/myExtension/</tt>. Inside this folder cr
>te another folder called <tt>chrome</tt>, inside the <tt>chrome</>eate another folder called <tt>chrome</tt>, inside the <tt>chrome
>tt> folder create a folder called <tt>content</tt>. (On Unix-like></tt> folder create a folder called <tt>content</tt>. (On Unix-li
> systems you can usually create all three directories just by run>ke systems you can usually create all three directories just by r
>ning <tt>mkdir -p chrome/content</tt> from within the extension's>unning <tt>mkdir -p chrome/content</tt> from within the extension
> root directory.)>'s root directory.)
43    </p>42      </p>
44    <p>43      <p>
45      Inside the <b>root</b> of your extension folder, alongside 44        Inside the <b>root</b> of your extension folder, alongsid
>the <tt>chrome</tt> folder, create two new empty text files, one >e the <tt>chrome</tt> folder, create two new empty text files, on
>called <tt>chrome.manifest</tt> and the other called <tt>install.>e called <tt>chrome.manifest</tt> and the other called <tt>instal
>rdf</tt>.>l.rdf</tt>.
46    </p>45      </p>
47    <p>46      <p>
48      More tips on setting up the development environment can be 47        More tips on setting up the development environment can b
>found on <a class="external" href="http://kb.mozillazine.org/Sett>e found on <a class="external" href="http://kb.mozillazine.org/Se
>ing_up_extension_development_environment">Mozillazine Knowledge B>tting_up_extension_development_environment">Mozillazine Knowledge
>ase</a>.> Base</a>.
49    </p>48      </p>
50    <h4 name="Create_the_Install_Manifest">49      <h4 name="Create_the_Install_Manifest">
51      Create the Install Manifest50        Create the Install Manifest
52    </h4>51      </h4>
53    <p>52      <p>
54      Open the file called <tt><a href="en/Install_Manifests">ins53        Open the file called <tt><a href="en/Install_Manifests">i
>tall.rdf</a></tt> that you created at the top of your extension's>nstall.rdf</a></tt> that you created at the top of your extension
> folder hierarchy and put this inside:>'s folder hierarchy and put this inside:
55    </p>54      </p>
56    <pre class="eval">55      <pre class="eval">
n85    <ul>n84      <ul>
86      <li>85        <li>
87        <b>sample@foo.net</b> - the ID of the extension. This is 86          <b>sample@foo.net</b> - the ID of the extension. This i
>some value you come up with to identify your extension in email a>s some value you come up with to identify your extension in email
>ddress format (note that it should not be <i>your</i> email). Mak> address format (note that it should not be <i>your</i> email). M
>e it unique. You could also use a GUID.>ake it unique. You could also use a GUID.
88      </li>87        </li>
89      <li>Specify <tt>&lt;em:type&gt;2&lt;/em:type&gt;</tt> -- th88        <li>Specify <tt>&lt;em:type&gt;2&lt;/em:type&gt;</tt> -- 
>e 2 declares that it is installing a extension. If you were to in>the 2 declares that it is installing a extension. If you were to 
>stall a theme it would be 4 (see <a href="en/Install_Manifests#ty>install a theme it would be 4 (see <a href="en/Install_Manifests#
>pe">Install Manifests#type</a> for other type codes).>type">Install Manifests#type</a> for other type codes).
90      </li>89        </li>
91      <li>90        <li>
92        <b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b> - Firefox's91          <b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b> - Firefox
> application ID.>'s application ID.
93      </li>92        </li>
94      <li>93        <li>
95        <b>1.5</b> - the minimum version of Firefox you're saying94          <b>1.5</b> - the minimum version of Firefox you're sayi
> this extension will work with. Set this as the minimum version y>ng this extension will work with. Set this as the minimum version
>ou're going to commit to testing and fixing bugs with.> you're going to commit to testing and fixing bugs with.
96      </li>95        </li>
97      <li>96        <li>
98        <b>2.0.0.*</b> - the maximum version of Firefox you're sa97          <b>2.0.0.*</b> - the maximum version of Firefox you're 
>ying this extension will work with. Set this to be no newer than >saying this extension will work with. Set this to be no newer tha
>the newest currently available version! In this case, "2.0.0.*" i>n the newest currently available version! In this case, "2.0.0.*"
>ndicates that the extension works with versions of Firefox 2.0.0.> indicates that the extension works with versions of Firefox 2.0.
>0 through 2.0.0.x.>0.0 through 2.0.0.x.
99      </li>98        </li>
100    </ul>99      </ul>
101    <p>100      <p>
102      Extensions designed to work with Firefox 1.5.0.x at the lat101        Extensions designed to work with Firefox 1.5.0.x at the l
>est should set the maximum version to "1.5.0.*".>atest should set the maximum version to "1.5.0.*".
103    </p>102      </p>
104    <p>103      <p>
105      See <a href="en/Install_Manifests">Install Manifests</a> fo104        See <a href="en/Install_Manifests">Install Manifests</a> 
>r a complete listing of the required and optional properties.>for a complete listing of the required and optional properties.
106    </p>105      </p>
107    <p>106      <p>
108      Save the file.107        Save the file.
109    </p>108      </p>
110    <h4 name="Extending_the_Browser_with_XUL">109      <h4 name="Extending_the_Browser_with_XUL">
111      Extending the Browser with XUL110        Extending the Browser with XUL
112    </h4>111      </h4>
113    <p>112      <p>
114      Firefox's user interface is written in XUL and JavaScript. 113        Firefox's user interface is written in XUL and JavaScript
><a href="en/XUL">XUL</a> is an XML grammar that provides user int>. <a href="en/XUL">XUL</a> is an XML grammar that provides user i
>erface widgets like buttons, menus, toolbars, trees etc. User act>nterface widgets like buttons, menus, toolbars, trees etc. User a
>ions are bound to functionality using JavaScript.>ctions are bound to functionality using JavaScript.
115    </p>114      </p>
116    <p>115      <p>
117      To extend the browser, we modify parts of the browser UI by116        To extend the browser, we modify parts of the browser UI 
> adding or modifying widgets. We add widgets by inserting new XUL>by adding or modifying widgets. We add widgets by inserting new X
> DOM elements into the browser window, and modify them by using s>UL DOM elements into the browser window, and modify them by using
>cript and attaching event handlers.> script and attaching event handlers.
118    </p>117      </p>
119    <p>118      <p>
120      The browser is implemented in a XUL file called <tt>browser119        The browser is implemented in a XUL file called <tt>brows
>.xul</tt> (<tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt> conta>er.xul</tt> (<tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt> con
>ins <tt>content/browser/browser.xul</tt>). In browser.xul we can >tains <tt>content/browser/browser.xul</tt>). In browser.xul we ca
>find the status bar, which looks something like this:>n find the status bar, which looks something like this:
121    </p>120      </p>
122    <pre class="eval">121      <pre class="eval">
n127    <p>n126      <p>
128      <tt>&lt;statusbar id="status-bar"&gt;</tt> is a "merge poin127        <tt>&lt;statusbar id="status-bar"&gt;</tt> is a "merge po
>t" for a XUL Overlay.>int" for a XUL Overlay.
129    </p>128      </p>
130    <h5 name="XUL_Overlays">129      <h5 name="XUL_Overlays">
131      XUL Overlays130        XUL Overlays
132    </h5>131      </h5>
133    <p>132      <p>
134      <a href="en/XUL_Overlays">XUL Overlays</a> are a way of att133        <a href="en/XUL_Overlays">XUL Overlays</a> are a way of a
>aching other UI widgets to a XUL document at run time. A XUL Over>ttaching other UI widgets to a XUL document at run time. A XUL Ov
>lay is a .xul file that specifies XUL fragments to insert at spec>erlay is a .xul file that specifies XUL fragments to insert at sp
>ific merge points within a "master" document. These fragments can>ecific merge points within a "master" document. These fragments c
> specify widgets to be inserted, removed, or modified.>an specify widgets to be inserted, removed, or modified.
135    </p>134      </p>
136    <p>135      <p>
137      <b>Example XUL Overlay Document</b>136        <b>Example XUL Overlay Document</b>
138    </p>137      </p>
139    <pre class="eval">138      <pre class="eval">
n148    <p>n147      <p>
149      The <tt>&lt;statusbar&gt;</tt> called <tt><b>status-bar</b>148        The <tt>&lt;statusbar&gt;</tt> called <tt><b>status-bar</
></tt> specifies the "merge point" within the browser window that >b></tt> specifies the "merge point" within the browser window tha
>we want to attach to.>t we want to attach to.
150    </p>149      </p>
151    <p>150      <p>
152      The <tt>&lt;statusbarpanel&gt;</tt> child is a new widget t151        The <tt>&lt;statusbarpanel&gt;</tt> child is a new widget
>hat we want to insert within the merge point.> that we want to insert within the merge point.
153    </p>152      </p>
154    <p>153      <p>
155      Take this sample code above and save it into a file called 154        Take this sample code above and save it into a file calle
><tt><b>sample.xul</b></tt> inside the <tt>chrome/content</tt> fol>d <tt><b>sample.xul</b></tt> inside the <tt>chrome/content</tt> f
>der you created.>older you created.
156    </p>155      </p>
157    <p>156      <p>
158      For more information about merging widgets and modifying th157        For more information about merging widgets and modifying 
>e user interface using Overlays, see below.>the user interface using Overlays, see below.
159    </p>158      </p>
160    <h4 name="Chrome_URIs">159      <h4 name="Chrome_URIs">
161      Chrome URIs160        Chrome URIs
162    </h4>161      </h4>
163    <p>162      <p>
164      XUL files are part of "<a href="en/Chrome_Registration">Chr163        XUL files are part of "<a href="en/Chrome_Registration">C
>ome Packages</a>" - bundles of user interface components which ar>hrome Packages</a>" - bundles of user interface components which 
>e loaded via <tt>chrome://</tt> URIs. Rather than load the browse>are loaded via <tt>chrome://</tt> URIs. Rather than load the brow
>r from disk using a <tt>file://</tt> URI (since the location of F>ser from disk using a <tt>file://</tt> URI (since the location of
>irefox on the system can change from platform to platform and sys> Firefox on the system can change from platform to platform and s
>tem to system), Mozilla developers came up with a solution for cr>ystem to system), Mozilla developers came up with a solution for 
>eating URIs to XUL content that the installed application knows a>creating URIs to XUL content that the installed application knows
>bout.> about.
165    </p>164      </p>
166    <p>165      <p>
167      The browser window is: <tt>chrome://browser/content/browser166        The browser window is: <tt>chrome://browser/content/brows
>.xul</tt> Try typing this URL into the location bar in Firefox!>er.xul</tt> Try typing this URL into the location bar in Firefox!
168    </p>167      </p>
169    <p>168      <p>
170      Chrome URIs consist of several components:169        Chrome URIs consist of several components:
171    </p>170      </p>
172    <ul>171      <ul>
173      <li>Firstly, the <b>URI scheme</b> (<tt>chrome</tt>) which 172        <li>Firstly, the <b>URI scheme</b> (<tt>chrome</tt>) whic
>tells Firefox's networking library that this is a Chrome URI. It >h tells Firefox's networking library that this is a Chrome URI. I
>indicates that the content of the URI should be handled as a (<tt>t indicates that the content of the URI should be handled as a (<
>>chrome</tt>). Compare (<tt>chrome</tt>) to (<tt>http</tt>) which>tt>chrome</tt>). Compare (<tt>chrome</tt>) to (<tt>http</tt>) whi
> tells Firefox to treat the URI as a web page.>ch tells Firefox to treat the URI as a web page.
174      </li>173        </li>
175      <li>Secondly, a package name (in the example above, <tt><b>174        <li>Secondly, a package name (in the example above, <tt><
>browser</b></tt>) which identifies the bundle of user interface c>b>browser</b></tt>) which identifies the bundle of user interface
>omponents. This should be as unique to your application as possib> components. This should be as unique to your application as poss
>le to avoid collisions between extensions.>ible to avoid collisions between extensions.
176      </li>175        </li>
177      <li>Thirdly, the type of data being requested. There are th176        <li>Thirdly, the type of data being requested. There are 
>ree types: <tt>content</tt> (XUL, JavaScript, XBL bindings, etc. >three types: <tt>content</tt> (XUL, JavaScript, XBL bindings, etc
>that form the structure and behavior of an application UI), <tt>l>. that form the structure and behavior of an application UI), <tt
>ocale</tt> (DTD, .properties files etc that contain strings for t>>locale</tt> (DTD, .properties files etc that contain strings for
>he UI's <a href="en/Localization">localization</a>), and <tt>skin> the UI's <a href="en/Localization">localization</a>), and <tt>sk
></tt> (CSS and images that form the <a href="en/Theme">theme</a> >in</tt> (CSS and images that form the <a href="en/Theme">theme</a
>of the UI)>> of the UI)
178      </li>177        </li>
179      <li>Finally, the path of a file to load.178        <li>Finally, the path of a file to load.
180      </li>179        </li>
181    </ul>180      </ul>
182    <p>181      <p>
183      So, <tt>chrome://foo/skin/bar.png</tt> loads the file <tt>b182        So, <tt>chrome://foo/skin/bar.png</tt> loads the file <tt
>ar.png</tt> from the <tt>foo</tt> theme's <tt>skin</tt> section.>>bar.png</tt> from the <tt>foo</tt> theme's <tt>skin</tt> section
 >.
184    </p>183      </p>
185    <p>184      <p>
186      When you load content using a Chrome URI, Firefox uses the 185        When you load content using a Chrome URI, Firefox uses th
>Chrome Registry to translate these URIs into the actual source fi>e Chrome Registry to translate these URIs into the actual source 
>les on disk (or in JAR packages).>files on disk (or in JAR packages).
187    </p>186      </p>
188    <h4 name="Create_a_Chrome_Manifest">187      <h4 name="Create_a_Chrome_Manifest">
189      Create a Chrome Manifest188        Create a Chrome Manifest
190    </h4>189      </h4>
191    <p>190      <p>
192      For more information on Chrome Manifests and the properties191        For more information on Chrome Manifests and the properti
> they support, see the <a href="en/Chrome_Manifest">Chrome Manife>es they support, see the <a href="en/Chrome_Manifest">Chrome Mani
>st</a> Reference.>fest</a> Reference.
193    </p>192      </p>
194    <p>193      <p>
195      Open the file called <tt><b>chrome.manifest</b></tt> that y194        Open the file called <tt><b>chrome.manifest</b></tt> that
>ou created alongside the <tt>chrome</tt> directory at the root of> you created alongside the <tt>chrome</tt> directory at the root 
> your extension's source folder hierarchy.>of your extension's source folder hierarchy.
196    </p>195      </p>
197    <p>196      <p>
198      Add in this code:197        Add in this code:
199    </p>198      </p>
200    <pre class="eval">199      <pre class="eval">
n203    <p>n202      <p>
204      (<b>Don't forget the trailing slash, "<tt>/</tt>"!</b> With203        (<b>Don't forget the trailing slash, "<tt>/</tt>"!</b> Wi
>out it, the extension won't get loaded.)>thout it, the extension won't get loaded.)
205    </p>204      </p>
206    <p>205      <p>
207      Note: Make sure you use all lowercase characters for the pa206        Note: Make sure you use all lowercase characters for the 
>ckage name ("sample") as Firefox/Thunderbird 1.5 doesn't support >package name ("sample") as Firefox/Thunderbird 1.5 doesn't suppor
>mixed/camel case. Apparently it will in version 2.>t mixed/camel case. Apparently it will in version 2.
208    </p>207      </p>
209    <p>208      <p>
210      This specifies the:209        This specifies the:
211    </p>210      </p>
212    <ol>211      <ol>
213      <li>type of material within a chrome package212        <li>type of material within a chrome package
214      </li>213        </li>
215      <li>name of the chrome package214        <li>name of the chrome package
216      </li>215        </li>
217      <li>location of the chrome packages' files216        <li>location of the chrome packages' files
218      </li>217        </li>
219    </ol>218      </ol>
220    <p>219      <p>
221      So, this line says that for a chrome package <b>sample</b>,220        So, this line says that for a chrome package <b>sample</b
> we can find its <b>content</b> files at the location <tt>chrome/>>, we can find its <b>content</b> files at the location <tt>chrom
>content</tt> which is a path relative to the location of <tt>chro>e/content</tt> which is a path relative to the location of <tt>ch
>me.manifest</tt>.>rome.manifest</tt>.
222    </p>221      </p>
223    <p>222      <p>
224      Note that content, locale and skin files must be kept insid223        Note that content, locale and skin files must be kept ins
>e folders called content, locale and skin within your <tt>chrome<>ide folders called content, locale and skin within your <tt>chrom
>/tt> subdirectory.>e</tt> subdirectory.
225    </p>224      </p>
226    <p>225      <p>
227      Save the file. When you launch Firefox with your extension,226        Save the file. When you launch Firefox with your extensio
> (later in this tutorial), this will register the chrome package.>n, (later in this tutorial), this will register the chrome packag
 >e.
228    </p>227      </p>
229    <h4 name="Register_an_Overlay">228      <h4 name="Register_an_Overlay">
230      Register an Overlay229        Register an Overlay
231    </h4>230      </h4>
232    <p>231      <p>
233      You need Firefox to merge your overlay with the browser win232        You need Firefox to merge your overlay with the browser w
>dow whenever it displays one. So add this line to your <tt>chrome>indow whenever it displays one. So add this line to your <tt>chro
>.manifest</tt> file:>me.manifest</tt> file:
234    </p>233      </p>
235    <pre class="eval">234      <pre class="eval">
n238    <p>n237      <p>
239      This tells Firefox to merge <tt>sample.xul</tt> into <tt>br238        This tells Firefox to merge <tt>sample.xul</tt> into <tt>
>owser.xul</tt> when <tt>browser.xul</tt> loads.>browser.xul</tt> when <tt>browser.xul</tt> loads.
240    </p>239      </p>
241    <h4 name="Test">240      <h4 name="Test">
242      Test241        Test
243    </h4>242      </h4>
244    <p>243      <p>
245      First, we need to tell Firefox about your extension. In the244        First, we need to tell Firefox about your extension. In t
> bad old days of Firefox 1.0 this meant packaging your extension >he bad old days of Firefox 1.0 this meant packaging your extensio
>as a XPI and installing it through the user interface, which was >n as a XPI and installing it through the user interface, which wa
>a real pain. Now, it's much simpler.>s a real pain. Now, it's much simpler.
246    </p>245      </p>
247    <ol>246      <ol>
248      <li>Open your <a class="external" href="http://kb.mozillazi247        <li>Open your <a class="external" href="http://kb.mozilla
>ne.org/Profile_folder">Profile Folder</a>>zine.org/Profile_folder">Profile Folder</a>
249      </li>248        </li>
250      <li>Open the <b>extensions</b> folder (create it if it does249        <li>Open the <b>extensions</b> folder (create it if it do
>n't exist)>esn't exist)
251      </li>250        </li>
252      <li>Create a new text file, and put the path to your extens251        <li>Create a new text file, and put the path to your exte
>ion folder inside, e.g. <tt>C:\extensions\myExtension\</tt> or <t>nsion folder inside, e.g. <tt>C:\extensions\myExtension\</tt> or 
>t>~/extensions/myExtension</tt>. Save the file with the id of you><tt>~/extensions/myExtension</tt>. Save the file with the id of y
>r extension as its name, e.g. <tt>sample@foo.net</tt>>our extension as its name, e.g. <tt>sample@foo.net</tt>
253      </li>252        </li>
254    </ol>253      </ol>
255    <p>254      <p>
256      Now you're ready to test your extension!255        Now you're ready to test your extension!
257    </p>256      </p>
258    <p>257      <p>
259      Start Firefox. Firefox will detect the text link to your ex258        Start Firefox. Firefox will detect the text link to your 
>tension directory and install the Extension. When the browser win>extension directory and install the Extension. When the browser w
>dow appears you should see the text "Hello, World!" on the right >indow appears you should see the text "Hello, World!" on the righ
>side of the status bar panel.>t side of the status bar panel.
260    </p>259      </p>
261    <p>260      <p>
262      You can now go back and make changes to the .xul file, clos261        You can now go back and make changes to the .xul file, cl
>e and restart Firefox and they should appear.>ose and restart Firefox and they should appear.
263    </p>262      </p>
264    <p>263      <p>
265      <span class="comment">These don't actually match the descri264        <span class="comment">These don't actually match the desc
>bed extension and confuse people. -Nickolay CENTER&gt; {{mediawik>ribed extension and confuse people. -Nickolay CENTER&gt; {{mediaw
>i.internal('Image:Helloworld_tools_menu.PNG', "en")}} {{mediawiki>iki.internal('Image:Helloworld_tools_menu.PNG', "en")}} {{mediawi
>.internal('Image:Helloworld_extensions_wnd.PNG', "en")}} &lt;/CEN>ki.internal('Image:Helloworld_extensions_wnd.PNG', "en")}} &lt;/C
>TER</span>>ENTER</span>
266    </p>265      </p>
267    <h4 name="Package">266      <h4 name="Package">
268      Package267        Package
269    </h4>268      </h4>
270    <p>269      <p>
271      Now that your extension works, you can <a href="en/Extensio270        Now that your extension works, you can <a href="en/Extens
>n_Packaging">package</a> it for deployment and installation.>ion_Packaging">package</a> it for deployment and installation.
272    </p>271      </p>
273    <p>272      <p>
274      Zip up the <b>contents</b> of your extension's folder (not 273        Zip up the <b>contents</b> of your extension's folder (no
>the extension folder itself), and rename the zip file to have a .>t the extension folder itself), and rename the zip file to have a
>xpi extension. In Windows XP, you can do this easily by selecting> .xpi extension. In Windows XP, you can do this easily by selecti
> all the files and subfolders in your extension folder, right cli>ng all the files and subfolders in your extension folder, right c
>ck and choose "Send To -&gt; Compressed (Zipped) Folder". A .zip >lick and choose "Send To -&gt; Compressed (Zipped) Folder". A .zi
>file will be created for you. Just rename it and you're done!>p file will be created for you. Just rename it and you're done!
275    </p>274      </p>
276    <p>275      <p>
277      On Mac OS X, you can right-click on the extension's folder 276        On Mac OS X, you can right-click on the extension's folde
>and choose "Create Archive of..." to make the zip file. However, >r and choose "Create Archive of..." to make the zip file. However
>since Mac OS X adds hidden files to folders in order to track fil>, since Mac OS X adds hidden files to folders in order to track f
>e metadata, you should instead use the Terminal, delete the hidde>ile metadata, you should instead use the Terminal, delete the hid
>n files (whose names begin with a period), and then use the <tt>z>den files (whose names begin with a period), and then use the <tt
>ip</tt> command on the command line to create the zip file.>>zip</tt> command on the command line to create the zip file.
278    </p>277      </p>
279    <p>278      <p>
280      On Linux, you would likewise use the command-line Zip tool.279        On Linux, you would likewise use the command-line Zip too
 >l.
281    </p>280      </p>
282    <p>281      <p>
283      If you have the 'Extension Builder' extension installed it 282        If you have the 'Extension Builder' extension installed i
>can compile the .xpi file for you (Tools -&gt; Extension Develope>t can compile the .xpi file for you (Tools -&gt; Extension Develo
>r -&gt; Extension Builder). Merely navigate to the directory wher>per -&gt; Extension Builder). Merely navigate to the directory wh
>e your extension is (install.rdf etc.), and hit the Build Extensi>ere your extension is (install.rdf etc.), and hit the Build Exten
>on button. This extension has a slew of tools to make development>sion button. This extension has a slew of tools to make developme
> easier.>nt easier.
284    </p>283      </p>
285    <p>284      <p>
286      Now upload the .xpi file to your server, making sure it's s285        Now upload the .xpi file to your server, making sure it's
>erved as <tt>application/x-xpinstall</tt>. You can link to it and> served as <tt>application/x-xpinstall</tt>. You can link to it a
> allow people to download and install it in Firefox. For the purp>nd allow people to download and install it in Firefox. For the pu
>oses of just testing our .xpi file we can just drag it into the e>rposes of just testing our .xpi file we can just drag it into the
>xtensions window via Tools -&gt; Extensions or Add-Ons -&gt; Exte> extensions window via Tools -&gt; Extensions or Add-Ons -&gt; Ex
>nsions in FireFox 2.>tensions in FireFox 2.
287    </p>286      </p>
288    <h5 name="Using_addons.mozilla.org">287      <h5 name="Using_addons.mozilla.org">
289      Using addons.mozilla.org288        Using addons.mozilla.org
290    </h5>289      </h5>
291    <p>290      <p>
292      Mozilla Update is a distribution site where you can host yo291        Mozilla Update is a distribution site where you can host 
>ur extension for free. Your extension will be hosted on Mozilla's>your extension for free. Your extension will be hosted on Mozilla
> mirror network to guarantee your download even though it might b>'s mirror network to guarantee your download even though it might
>e very popular. Mozilla's site also provides users easier install> be very popular. Mozilla's site also provides users easier insta
>ation, and will automatically make your newer versions available >llation, and will automatically make your newer versions availabl
>to users of your existing versions when you upload them. In addit>e to users of your existing versions when you upload them. In add
>ion Mozilla Update allows users to comment and provide feedback o>ition Mozilla Update allows users to comment and provide feedback
>n your extension. It is highly recommended that you use Mozilla U> on your extension. It is highly recommended that you use Mozilla
>pdate to distribute your extensions!> Update to distribute your extensions!
293    </p>292      </p>
294    <p>293      <p>
295      Visit http://addons.mozilla.org/developers/ to create an ac294        Visit http://addons.mozilla.org/developers/ to create an 
>count and begin distributing your extensions!>account and begin distributing your extensions!
296    </p>295      </p>
297    <p>296      <p>
298      <i>Note:</i> Your Extension will be passed faster and downl297        <i>Note:</i> Your Extension will be passed faster and dow
>oaded more if you have a good description and some screenshots of>nloaded more if you have a good description and some screenshots 
> the extension in action.>of the extension in action.
299    </p>298      </p>
300    <h5 name="Registering_Extensions_in_the_Windows_Registry">299      <h5 name="Registering_Extensions_in_the_Windows_Registry">
301      Registering Extensions in the Windows Registry300        Registering Extensions in the Windows Registry
302    </h5>301      </h5>
303    <p>302      <p>
304      On Windows, information about extensions can be added to th303        On Windows, information about extensions can be added to 
>e registry, and the extensions will automatically be picked up th>the registry, and the extensions will automatically be picked up 
>e next time the applications starts. This allows application inst>the next time the applications starts. This allows application in
>allers to easily add integration hooks as extensions. See <a href>stallers to easily add integration hooks as extensions. See <a hr
>="en/Adding_Extensions_using_the_Windows_Registry">Adding Extensi>ef="en/Adding_Extensions_using_the_Windows_Registry">Adding Exten
>ons using the Windows Registry</a> for more information.>sions using the Windows Registry</a> for more information.
305    </p>304      </p>
306    <h4 name="More_on_XUL_Overlays">305      <h4 name="More_on_XUL_Overlays">
307      More on XUL Overlays306        More on XUL Overlays
308    </h4>307      </h4>
309    <p>308      <p>
310      In addition to appending UI widgets to the merge point, you309        In addition to appending UI widgets to the merge point, y
> can use XUL fragments within Overlays to:>ou can use XUL fragments within Overlays to:
311    </p>310      </p>
312    <ul>311      <ul>
313      <li>Modify attributes on the merge point, e.g. <tt>&lt;stat312        <li>Modify attributes on the merge point, e.g. <tt>&lt;st
>usbar id="status-bar" hidden="true"/&gt;</tt> (hides the status b>atusbar id="status-bar" hidden="true"/&gt;</tt> (hides the status
>ar)> bar)
314      </li>313        </li>
315      <li>Remove the merge point from the master document, e.g. <314        <li>Remove the merge point from the master document, e.g.
>tt>&lt;statusbar id="status-bar" removeelement="true"/&gt;</tt>> <tt>&lt;statusbar id="status-bar" removeelement="true"/&gt;</tt>
316      </li>315        </li>
317      <li>Control the position of the inserted widgets:316        <li>Control the position of the inserted widgets:
318      </li>317        </li>
319    </ul>318      </ul>
320    <pre class="eval">319      <pre class="eval">
n327    <h4 name="Creating_New_User_Interface_Components">n326      <h4 name="Creating_New_User_Interface_Components">
328      Creating New User Interface Components327        Creating New User Interface Components
329    </h4>328      </h4>
330    <p>329      <p>
331      You can create your own windows and dialog boxes as separat330        You can create your own windows and dialog boxes as separ
>e .xul files, provide functionality by implementing user actions >ate .xul files, provide functionality by implementing user action
>in .js files, using DOM methods to manipulate UI widgets. You can>s in .js files, using DOM methods to manipulate UI widgets. You c
> use style rules in .css files to attach images, set colors etc.>an use style rules in .css files to attach images, set colors etc
 >.
332    </p>331      </p>
333    <p>332      <p>
334      View the <a href="en/XUL">XUL</a> documentation for more re333        View the <a href="en/XUL">XUL</a> documentation for more 
>sources for XUL developers.>resources for XUL developers.
335    </p>334      </p>
336    <h4 name="Defaults_Files">335      <h4 name="Defaults_Files">
337      Defaults Files336        Defaults Files
338    </h4>337      </h4>
339    <p>338      <p>
340      Defaults files that you use to seed a user's profile with s339        Defaults files that you use to seed a user's profile with
>hould be placed in <tt>defaults/</tt> under the root of your exte> should be placed in <tt>defaults/</tt> under the root of your ex
>nsion's folder hierarchy. Default preferences .js files should be>tension's folder hierarchy. Default preferences .js files should 
> stored in <tt>defaults/preferences/</tt> - when you place them h>be stored in <tt>defaults/preferences/</tt> - when you place them
>ere they will be automatically loaded by Firefox's preferences sy> here they will be automatically loaded by Firefox's preferences 
>stem when it starts so that you can access them using the <a href>system when it starts so that you can access them using the <a hr
>="en/Preferences_API">Preferences API</a>.>ef="en/Preferences_API">Preferences API</a>.
341    </p>340      </p>
342    <h4 name="XPCOM_Components">341      <h4 name="XPCOM_Components">
343      XPCOM Components342        XPCOM Components
344    </h4>343      </h4>
345    <p>344      <p>
346      Firefox supports <a href="en/XPCOM">XPCOM</a> components in345        Firefox supports <a href="en/XPCOM">XPCOM</a> components 
> extensions. You can create your own components easily in JavaScr>in extensions. You can create your own components easily in JavaS
>ipt or in C++ (using the <a href="en/Gecko_SDK">Gecko SDK</a>).>cript or in C++ (using the <a href="en/Gecko_SDK">Gecko SDK</a>).
347    </p>346      </p>
348    <p>347      <p>
349      Place all of your .js or .dll files in the <tt>components/<348        Place all of your .js or .dll files in the <tt>components
>/tt> directory - they are automatically registered the first time>/</tt> directory - they are automatically registered the first ti
> Firefox runs after your extension is installed.>me Firefox runs after your extension is installed.
350    </p>349      </p>
351    <p>350      <p>
352      For more information see <a href="en/How_to_Build_an_XPCOM_351        For more information see <a href="en/How_to_Build_an_XPCO
>Component_in_Javascript">How to Build an XPCOM Component in Javas>M_Component_in_Javascript">How to Build an XPCOM Component in Jav
>cript</a> and the <a href="en/Creating_XPCOM_Components">Creating>ascript</a> and the <a href="en/Creating_XPCOM_Components">Creati
> XPCOM Components</a> book.>ng XPCOM Components</a> book.
353    </p>352      </p>
354    <h5 name="Application_Command_Line">353      <h5 name="Application_Command_Line">
355      Application Command Line354        Application Command Line
356    </h5>355      </h5>
357    <p>356      <p>
358      One of the possible uses of custom XPCOM components is addi357        One of the possible uses of custom XPCOM components is ad
>ng a command line handler to Firefox or Thundebird. You can use t>ding a command line handler to Firefox or Thundebird. You can use
>his technique to run your extension as an application:> this technique to run your extension as an application:
359    </p>358      </p>
360    <pre class="eval">359      <pre class="eval">
n363    <p>n362      <p>
364      <span class="comment">I should move the useful parts of thi363        <span class="comment">I should move the useful parts of t
>s to the Command Line page. -Nickolay This is done by adding a co>his to the Command Line page. -Nickolay This is done by adding a 
>mponent containing the function... function NSGetModule(comMgr, f>component containing the function... function NSGetModule(comMgr,
>ileSpec) { return myAppHandlerModule; } This function is run by f> fileSpec) { return myAppHandlerModule; } This function is run by
>irefox each time firefox is started. Firefox registers the myAppH> firefox each time firefox is started. Firefox registers the myAp
>andlerModule's by calling its 'registerSelf()'. Then it obtains t>pHandlerModule's by calling its 'registerSelf()'. Then it obtains
>he myAppHandlerModule's handler factory via 'getClassObject()'. T> the myAppHandlerModule's handler factory via 'getClassObject()'.
>he handler factory is then used to create the handle using its 'c> The handler factory is then used to create the handle using its 
>reateInstance(). Finally, the handle's 'handle(cmdline)' processe>'createInstance(). Finally, the handle's 'handle(cmdline)' proces
>s the command line cmdline's handleFlagWithParam() and handleFlag>ses the command line cmdline's handleFlagWithParam() and handleFl
>().</span> See <a href="en/Chrome/Command_Line">Chrome: Command L>ag().</span> See <a href="en/Chrome/Command_Line">Chrome: Command
>ine</a> and a <a class="external" href="http://forums.mozillazine> Line</a> and a <a class="external" href="http://forums.mozillazi
>.org/viewtopic.php?t=365297">forum discussion</a> for details.>ne.org/viewtopic.php?t=365297">forum discussion</a> for details.
365    </p>364      </p>
366    <h4 name="Localization">365      <h4 name="Localization">
367      Localization366        Localization
368    </h4>367      </h4>
369    <p>368      <p>
370      To support more than one language, you should separate stri369        To support more than one language, you should separate st
>ngs from your content using <a href="en/XUL_Tutorial/Localization>rings from your content using <a href="en/XUL_Tutorial/Localizati
>">entities</a> and <a href="en/XUL_Tutorial/Property_Files">strin>on">entities</a> and <a href="en/XUL_Tutorial/Property_Files">str
>g bundles</a>. It is much easier to do this as you are developing>ing bundles</a>. It is much easier to do this as you are developi
> your extension than to come back and do it later!>ng your extension than to come back and do it later!
371    </p>370      </p>
372    <p>371      <p>
373      Localization information is stored in the locale directory 372        Localization information is stored in the locale director
>for the extension. For example, to add a locale to our sample ext>y for the extension. For example, to add a locale to our sample e
>ension, create a directory named "locale" in chrome (where the "c>xtension, create a directory named "locale" in chrome (where the 
>ontent" directory is located) and add the following line to the c>"content" directory is located) and add the following line to the
>hrome.manifest file:> chrome.manifest file:
374    </p>373      </p>
375    <pre class="eval">374      <pre class="eval">
n378    <p>n377      <p>
379      To create localizable attribute values in XUL, you put the 378        To create localizable attribute values in XUL, you put th
>values in a <tt>.ent</tt> (or a <tt>.dtd</tt>) file, which should>e values in a <tt>.ent</tt> (or a <tt>.dtd</tt>) file, which shou
> be placed in the locale directory and looks like this:>ld be placed in the locale directory and looks like this:
380    </p>379      </p>
381    <pre class="eval">380      <pre class="eval">
n385    <p>n384      <p>
386      And then include it at the top of your XUL document (but un385        And then include it at the top of your XUL document (but 
>derneath the "&lt;?xml version"1.0"?&gt;") like so:>underneath the "&lt;?xml version"1.0"?&gt;") like so:
387    </p>386      </p>
388    <pre class="eval">387      <pre class="eval">
n391    <p>n390      <p>
392      where <code><b>window</b></code> is the <code><a href="en/D391        where <code><b>window</b></code> is the <code><a href="en
>OM/element.localName">localName</a></code> value of the root elem>/DOM/element.localName">localName</a></code> value of the root el
>ent of the XUL document, and the value of the <tt>SYSTEM</tt> pro>ement of the XUL document, and the value of the <tt>SYSTEM</tt> p
>perty is the chrome URI to the entity file. For our sample extens>roperty is the chrome URI to the entity file. For our sample exte
>ion, the root element is <code><b>overlay</b></code>.>nsion, the root element is <code><b>overlay</b></code>.
393    </p>392      </p>
394    <p>393      <p>
395      To use the entities, modify your XUL to look like this:394        To use the entities, modify your XUL to look like this:
396    </p>395      </p>
397    <pre class="eval">396      <pre class="eval">
n400    <p>n399      <p>
401      The Chrome Registry will make sure the entity file is loade400        The Chrome Registry will make sure the entity file is loa
>d from the localization bundle corresponding to the selected loca>ded from the localization bundle corresponding to the selected lo
>le.>cale.
402    </p>401      </p>
403    <p>402      <p>
404      For strings that you use in script, create a .properties fi403        For strings that you use in script, create a .properties 
>le, a text file that has a string on each line in this format:>file, a text file that has a string on each line in this format:
405    </p>404      </p>
406    <pre class="eval">405      <pre class="eval">
t409    <p>t408      <p>
410      and then use <tt><a href="en/NsIStringBundleService">nsIStr409        and then use <tt><a href="en/NsIStringBundleService">nsIS
>ingBundleService</a></tt>/<tt><a href="en/NsIStringBundle">nsIStr>tringBundleService</a></tt>/<tt><a href="en/NsIStringBundle">nsIS
>ingBundle</a></tt> or the <tt><a class="external" href="http://xu>tringBundle</a></tt> or the <tt><a class="external" href="http://
>lplanet.com/references/elemref/ref_stringbundle.html">&lt;stringb>xulplanet.com/references/elemref/ref_stringbundle.html">&lt;strin
>undle&gt;</a></tt> tag to load the values into script.>gbundle&gt;</a></tt> tag to load the values into script.
411    </p>410      </p>
412    <h4 name="Understanding_the_Browser">411      <h4 name="Understanding_the_Browser">
413      Understanding the Browser412        Understanding the Browser
414    </h4>413      </h4>
415    <p>414      <p>
416      Use the <a href="en/DOM_Inspector">DOM Inspector</a> (not p415        Use the <a href="en/DOM_Inspector">DOM Inspector</a> (not
>art of the <b>Standard</b> Firefox installation, you must reinsta> part of the <b>Standard</b> Firefox installation, you must reins
>ll with the Custom install path and choose <b>Developer Tools</b>>tall with the Custom install path and choose <b>Developer Tools</
> if there is not a "DOM Inspector" item in your browser's Tools m>b> if there is not a "DOM Inspector" item in your browser's Tools
>enu) to inspect the browser window or any other XUL window you wa> menu) to inspect the browser window or any other XUL window you 
>nt to extend.>want to extend.
417    </p>416      </p>
418    <p>417      <p>
419      Use the point-and-click node finder button at the top left 418        Use the point-and-click node finder button at the top lef
>of the DOM Inspector's toolbar to click on a node in the XUL wind>t of the DOM Inspector's toolbar to click on a node in the XUL wi
>ow visually to select it. When you do this the DOM inspector's DO>ndow visually to select it. When you do this the DOM inspector's 
>M hierarchy tree view will jump to the node you clicked on.>DOM hierarchy tree view will jump to the node you clicked on.
420    </p>419      </p>
421    <p>420      <p>
422      Use the DOM Inspector's right side panel to discover merge 421        Use the DOM Inspector's right side panel to discover merg
>points with ids that you can use to insert your elements from ove>e points with ids that you can use to insert your elements from o
>rlays. If you cannot discover an element with an id that you can >verlays. If you cannot discover an element with an id that you ca
>merge into, you may need to attach a script in your overlay and i>n merge into, you may need to attach a script in your overlay and
>nsert your elements when the <tt>load</tt> event fires on the mas> insert your elements when the <tt>load</tt> event fires on the m
>ter XUL window.>aster XUL window.
423    </p>422      </p>
424    <h4 name="Debugging_Extensions">423      <h4 name="Debugging_Extensions">
425      Debugging Extensions424        Debugging Extensions
426    </h4>425      </h4>
427    <p>426      <p>
428      <b>Analytical Tools for Debugging</b>427        <b>Analytical Tools for Debugging</b>
429    </p>428      </p>
430    <ul>429      <ul>
431      <li>The <a href="en/DOM_Inspector">DOM Inspector</a> - insp430        <li>The <a href="en/DOM_Inspector">DOM Inspector</a> - in
>ect attributes, DOM structure, CSS style rules that are in effect>spect attributes, DOM structure, CSS style rules that are in effe
> (e.g. find out why your style rules don't seem to be working for>ct (e.g. find out why your style rules don't seem to be working f
> an element - an invaluable tool!)>or an element - an invaluable tool!)
432      </li>431        </li>
433      <li>432        <li>
434        <a href="en/Venkman">Venkman</a> - set breakpoints in Jav433          <a href="en/Venkman">Venkman</a> - set breakpoints in J
>aScript and inspect call stacks>avaScript and inspect call stacks
435      </li>434        </li>
436      <li>435        <li>
437        <code><a href="en/Core_JavaScript_1.5_Reference/Objects/F436          <code><a href="en/Core_JavaScript_1.5_Reference/Objects
>unction/arguments/callee">arguments.callee</a>.<a href="en/Core_J>/Function/arguments/callee">arguments.callee</a>.<a href="en/Core
>avaScript_1.5_Reference/Objects/Function/caller">caller</a></code>_JavaScript_1.5_Reference/Objects/Function/caller">caller</a></co
>> in JavaScript - access a function's call stack>de> in JavaScript - access a function's call stack
438      </li>437        </li>
439    </ul>438      </ul>
440    <p>439      <p>
441      <b>printf debugging</b>440        <b>printf debugging</b>
442    </p>441      </p>
443    <ul>442      <ul>
444      <li>Run Firefox with <tt>-console</tt> at the command line 443        <li>Run Firefox with <tt>-console</tt> at the command lin
>and use <code><a href="en/DOM/window.dump">dump</a>("string")</co>e and use <code><a href="en/DOM/window.dump">dump</a>("string")</
>de> (see the link for details)>code> (see the link for details)
445      </li>444        </li>
446      <li>Use <code><a href="en/NsIConsoleService">nsIConsoleServ445        <li>Use <code><a href="en/NsIConsoleService">nsIConsoleSe
>ice</a></code> to log to the JavaScript console>rvice</a></code> to log to the JavaScript console
447      </li>446        </li>
448    </ul>447      </ul>
449    <p>448      <p>
450      <b>Advanced debugging</b>449        <b>Advanced debugging</b>
451    </p>450      </p>
452    <ul>451      <ul>
453      <li>Run a debug Firefox build and set breakpoints in Firefo452        <li>Run a debug Firefox build and set breakpoints in Fire
>x itself, or your C++ components. For the experienced developer, >fox itself, or your C++ components. For the experienced developer
>this is often the fastest way to diagnose a problem. See <a href=>, this is often the fastest way to diagnose a problem. See <a hre
>"en/Build_Documentation">Build Documentation</a> and <a href="en/>f="en/Build_Documentation">Build Documentation</a> and <a href="e
>Developing_Mozilla">Developing Mozilla</a> for more information.>n/Developing_Mozilla">Developing Mozilla</a> for more information
 >.
454      </li>453        </li>
455      <li>See <a href="en/Debugging_a_XULRunner_Application">Debu454        <li>See <a href="en/Debugging_a_XULRunner_Application">De
>gging a XULRunner Application</a> for more helpful tips.>bugging a XULRunner Application</a> for more helpful tips.
456      </li>455        </li>
457    </ul>456      </ul>
458    <h3 name="Quick_Start">457      <h3 name="Quick_Start">
459      Quick Start458        Quick Start
460    </h3>459      </h3>
461    <p>460      <p>
462      You can use the <a class="external" href="http://ted.mielcz461        You can use the <a class="external" href="http://ted.miel
>arek.org/code/mozilla/extensionwiz/">Extension Wizard</a> online >czarek.org/code/mozilla/extensionwiz/">Extension Wizard</a> onlin
>tool to generate a simple extension to work with.>e tool to generate a simple extension to work with.
463    </p>462      </p>
464    <p>463      <p>
465      A <a class="external" href="http://mozilla.doslash.org/stuf464        A <a class="external" href="http://mozilla.doslash.org/st
>f/helloworld.zip">Hello World extension</a> similar to what you c>uff/helloworld.zip">Hello World extension</a> similar to what you
>an generate with the Extension Wizard is explained line-by-line i> can generate with the Extension Wizard is explained line-by-line
>n <a class="external" href="http://kb.mozillazine.org/Getting_sta> in <a class="external" href="http://kb.mozillazine.org/Getting_s
>rted_with_extension_development">another tutorial from MozillaZin>tarted_with_extension_development">another tutorial from MozillaZ
>e Knowledge Base</a>.>ine Knowledge Base</a>.
466    </p>465      </p>
467    <h3 name="Further_information">466      <h3 name="Further_information">
468      Further information467        Further information
469    </h3>468      </h3>
470    <ul>469      <ul>
471      <li>470        <li>
472        <a href="en/Extension_FAQ">Extension FAQ</a>471          <a href="en/Extension_FAQ">Extension FAQ</a>
473      </li>472        </li>
474      <li>473        <li>
475        <a href="en/Extensions">Extensions</a>474          <a href="en/Extensions">Extensions</a>
476      </li>475        </li>
476      </ul>
477    </ul>{{ wiki.languages( { "de": "de/Erweiterung_erstellen", "477    </div>{{ wiki.languages( { "de": "de/Erweiterung_erstellen", 
>es": "es/Creando_una_extensi\u00f3n", "fr": "fr/Construire_une_ex>"es": "es/Creando_una_extensi\u00f3n", "fr": "fr/Construire_une_e
>tension", "ja": "ja/Building_an_Extension", "pl": "pl/Tworzymy_ro>xtension", "ja": "ja/Building_an_Extension", "pl": "pl/Tworzymy_r
>zszerzenie", "it": "it/Sviluppare_un\'Estensione" } ) }}>ozszerzenie", "it": "it/Sviluppare_un\'Estensione" } ) }}

Back to History