mozilla

Compare Revisions

Building an extension

Change Revisions

Revision 33491:

Revision 33491 by Amanladdha on

Revision 33492:

Revision 33492 by Amanladdha 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 33491
Revision 33492
n10    <h3 name="Orkut_Tool.5D.5D">n10    <p>
11      <b>Orkut Tool</b>]]11      <br>
12    </h3>12    </p>
t71    <h4 name="Setting_up_the_Development_Environment">t
72      Setting up the Development Environment
73    </h4>
74    <p>
75      Extensions are packaged and distributed in ZIP files, or <a
> href="en/Bundles">Bundles</a>, with the <tt>xpi</tt> (<i>pronoun 
>ced “zippy”</i>) file extension. The layout of content within the 
> XPI file is like so: 
76    </p>
77    <pre class="eval">
78extension.xpi:
79              /<a href="en/Install.rdf">install.rdf</a>          
>          
80              <a href="#XPCOM_Components">/components/*</a>  
81              <a href="#Application_Command_Line">/components/cmd
>line.js</a>                    
82              <a href="#Defaults_Files">/defaults/</a>
83              <a href="#Defaults_Files">/defaults/preferences/*.j
>s</a>      
84              /plugins/*                        
85              /<a href="en/Chrome.manifest">chrome.manifest</a>  
>               
86              /<a href="en/Chrome_window_icons">chrome/icons/defa
>ult/*</a>        
87              /chrome/
88              /chrome/content/
89     
90</pre>
91    <p>
92      Because of this, it is easiest if we lay out our source fil
>es in a similar fashion, unless you want to write some sort of Ma 
>kefile or shell script to package and zip all of your files. Even 
> if you are prepared to do that, testing is much simpler if you l 
>ay out your files like this because of a feature of the Add-on Sy 
>stem provided by Firefox 1.5 and later. 
93    </p>
94    <p>
95      So let's get started. Create a folder for your extension so
>mewhere on your hard disk, e.g. <tt>C:\extensions\my_extension\</ 
>tt> or <tt>~/extensions/my_extension/</tt>. (note: use all lower  
>case) Inside this folder create another folder called <tt>chrome< 
>/tt>, inside the <tt>chrome</tt> folder create a folder called <t 
>t>content</tt>. (On Unix-like systems you can usually create both 
> directories just by running <tt>mkdir -p chrome/content</tt> fro 
>m within the extension's root directory.) 
96    </p>
97    <p>
98      Inside the <b>root</b> of your extension folder, alongside 
>the <tt>chrome</tt> folder, create two new empty text files, one  
>called <tt>chrome.manifest</tt> and the other called <tt>install. 
>rdf</tt>. 
99    </p>
100    <p>
101      For example:
102    </p>
103    <pre>
104#!/bin/sh
105h=$HOME/moExt
106mkdir -p $h/my_extension/chrome/content
107touch $h/my_extension/chrome.manifest $h/my_extension/install.rdf
108</pre>
109    <p>
110      More tips on setting up the development environment can be 
>found in the article <a href="en/Setting_up_extension_development 
>_environment">Setting up extension development environment</a>. 
111    </p>
112    <h4 name="Create_the_Install_Manifest">
113      Create the Install Manifest
114    </h4>
115    <p>
116      Open the file called <tt><a href="en/Install_Manifests">ins
>tall.rdf</a></tt> that you created at the top of your extension's 
> folder hierarchy and put this inside: 
117    </p>
118    <pre class="eval">
119&lt;?xml version="1.0"?&gt;
120 
121&lt;RDF xmlns="<span class="plain">http://www.w3.org/1999/02/22-r
>df-syntax-ns#</span>" 
122     xmlns:em="<span class="plain">http://www.mozilla.org/2004/em
>-rdf#</span>"&gt; 
123 
124  &lt;Description about="urn:mozilla:install-manifest"&gt;
125    &lt;em:id&gt;<b>sample@foo.net</b>&lt;/em:id&gt;
126    &lt;em:version&gt;<b>1.0</b>&lt;/em:version&gt;
127    &lt;em:type&gt;2&lt;/em:type&gt;
128   
129    &lt;!-- Target Application this extension can install into, 
130         with minimum and maximum supported versions. --&gt; 
131    &lt;em:targetApplication&gt;
132      &lt;Description&gt;
133        &lt;em:id&gt;<b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b
>>&lt;/em:id&gt; 
134        &lt;em:minVersion&gt;<b>1.5</b>&lt;/em:minVersion&gt;
135        &lt;em:maxVersion&gt;<b>2.0.0.*</b>&lt;/em:maxVersion&gt;
136      &lt;/Description&gt;
137    &lt;/em:targetApplication&gt;
138   
139    &lt;!-- Front End MetaData --&gt;
140    &lt;em:name&gt;<b>Sample!</b>&lt;/em:name&gt;
141    &lt;em:description&gt;<b>A test extension</b>&lt;/em:descript
>ion&gt; 
142    &lt;em:creator&gt;<b>Your Name Here</b>&lt;/em:creator&gt;
143    &lt;em:homepageURL&gt;<b><span class="plain">http://www.foo.c
>om/</span></b>&lt;/em:homepageURL&gt; 
144  &lt;/Description&gt;      
145&lt;/RDF&gt;
146</pre>
147    <ul>
148      <li>
149        <b>sample@foo.net</b> - the ID of the extension. This is 
>some value you come up with to identify your extension in email a 
>ddress format (note that it should not be <i>your</i> email). Mak 
>e it unique. You could also use a GUID. NOTE: This parameter MUST 
> be in the format of an email address, although it does NOT have  
>to be a valid email address. (something@something.something) 
150      </li>
151      <li>Specify <tt>&lt;em:type&gt;2&lt;/em:type&gt;</tt> -- th
>e 2 declares that it is installing an extension. If you were to i 
>nstall a theme it would be 4 (see <a href="en/Install_Manifests#t 
>ype">Install Manifests#type</a> for other type codes). 
152      </li>
153      <li>
154        <b>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</b> - Firefox's
> application ID. 
155      </li>
156      <li>
157        <b>1.5</b> - the minimum version of Firefox you're saying
> this extension will work with. Set this as the minimum version y 
>ou're going to commit to testing and fixing bugs with. 
158      </li>
159      <li>
160        <b>2.0.0.*</b> - the maximum version of Firefox you're sa
>ying this extension will work with. Set this to be no newer than  
>the newest currently available version! In this case, "2.0.0.*" i 
>ndicates that the extension works with versions of Firefox 2.0.0. 
>0 through 2.0.0.x. 
161      </li>
162    </ul>
163    <p>
164      Extensions designed to work with Firefox 1.5.0.x at the lat
>est should set the maximum version to "1.5.0.*". 
165    </p>
166    <p>
167      See <a href="en/Install_Manifests">Install Manifests</a> fo
>r a complete listing of the required and optional properties. 
168    </p>
169    <p>
170      Save the file.
171    </p>
172    <h4 name="Extending_the_Browser_with_XUL">
173      Extending the Browser with XUL
174    </h4>
175    <p>
176      Firefox's user interface is written in XUL and JavaScript. 
><a href="en/XUL">XUL</a> is an XML grammar that provides user int 
>erface widgets like buttons, menus, toolbars, trees etc. User act 
>ions are bound to functionality using JavaScript. 
177    </p>
178    <p>
179      To extend the browser, we modify parts of the browser UI by
> adding or modifying widgets. We add widgets by inserting new XUL 
> DOM elements into the browser window, and modify them by using s 
>cript and attaching event handlers. 
180    </p>
181    <p>
182      The browser is implemented in a XUL file called <tt>browser
>.xul</tt> (<tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt> conta 
>ins <tt>content/browser/browser.xul</tt>). In browser.xul we can  
>find the status bar, which looks something like this: 
183    </p>
184    <pre class="eval">
185&lt;statusbar id="status-bar"&gt;
186 ... &lt;statusbarpanel&gt;s ...
187&lt;/statusbar&gt;
188</pre>
189    <p>
190      <tt>&lt;statusbar id="status-bar"&gt;</tt> is a "merge poin
>t" for a XUL Overlay. 
191    </p>
192    <h5 name="XUL_Overlays">
193      XUL Overlays
194    </h5>
195    <p>
196      <a href="en/XUL_Overlays">XUL Overlays</a> are a way of att
>aching other UI widgets to a XUL document at run time. A XUL Over 
>lay is a .xul file that specifies XUL fragments to insert at spec 
>ific merge points within a "master" document. These fragments can 
> specify widgets to be inserted, removed, or modified. 
197    </p>
198    <p>
199      <b>Example XUL Overlay Document</b>
200    </p>
201    <pre class="eval">
202&lt;?xml version="1.0"?&gt;
203&lt;overlay id="sample" 
204         xmlns="<span class="plain">http://www.mozilla.org/keymas
>ter/gatekeeper/there.is.only.xul</span>"&gt; 
205 &lt;statusbar id="<b>status-bar</b>"&gt;
206  &lt;statusbarpanel id="my-panel" label="Hello, World"/&gt;
207 &lt;/statusbar&gt;
208&lt;/overlay&gt;
209</pre>
210    <p>
211      The <tt>&lt;statusbar&gt;</tt> called <tt><b>status-bar</b>
></tt> specifies the "merge point" within the browser window that  
>we want to attach to. 
212    </p>
213    <p>
214      The <tt>&lt;statusbarpanel&gt;</tt> child is a new widget t
>hat we want to insert within the merge point. 
215    </p>
216    <p>
217      Take this sample code above and save it into a new file cal
>led <tt><b>sample.xul</b></tt> inside the <tt>chrome/content</tt> 
> folder you created. 
218    </p>
219    <p>
220      For more information about merging widgets and modifying th
>e user interface using Overlays, see below. 
221    </p>
222    <h4 name="Chrome_URIs">
223      Chrome URIs
224    </h4>
225    <p>
226      XUL files are part of "<a href="en/Chrome_Registration">Chr
>ome Packages</a>" - bundles of user interface components which ar 
>e loaded via <tt>chrome://</tt> URIs. Rather than load the browse 
>r from disk using a <tt>file://</tt> URI (since the location of F 
>irefox on the system can change from platform to platform and sys 
>tem to system), Mozilla developers came up with a solution for cr 
>eating URIs to XUL content that the installed application knows a 
>bout. 
227    </p>
228    <p>
229      The browser window is: <tt>chrome://browser/content/browser
>.xul</tt> Try typing this URL into the location bar in Firefox! 
230    </p>
231    <p>
232      Chrome URIs consist of several components:
233    </p>
234    <ul>
235      <li>Firstly, the <b>URI scheme</b> (<tt>chrome</tt>) which 
>tells Firefox's networking library that this is a Chrome URI. It  
>indicates that the content of the URI should be handled as a (<tt 
>>chrome</tt>). Compare (<tt>chrome</tt>) to (<tt>http</tt>) which 
> tells Firefox to treat the URI as a web page. 
236      </li>
237      <li>Secondly, a package name (in the example above, <tt><b>
>browser</b></tt>) which identifies the bundle of user interface c 
>omponents. This should be as unique to your application as possib 
>le to avoid collisions between extensions. 
238      </li>
239      <li>Thirdly, the type of data being requested. There are th
>ree types: <tt>content</tt> (XUL, JavaScript, XBL bindings, etc.  
>that form the structure and behavior of an application UI), <tt>l 
>ocale</tt> (DTD, .properties files etc that contain strings for t 
>he UI's <a href="en/Localization">localization</a>), and <tt>skin 
></tt> (CSS and images that form the <a href="en/Theme">theme</a>  
>of the UI) 
240      </li>
241      <li>Finally, the path of a file to load.
242      </li>
243    </ul>
244    <p>
245      So, <tt>chrome://foo/skin/bar.png</tt> loads the file <tt>b
>ar.png</tt> from the <tt>foo</tt> theme's <tt>skin</tt> section. 
246    </p>
247    <p>
248      When you load content using a Chrome URI, Firefox uses the 
>Chrome Registry to translate these URIs into the actual source fi 
>les on disk (or in JAR packages). 
249    </p>
250    <h4 name="Create_a_Chrome_Manifest">
251      Create a Chrome Manifest
252    </h4>
253    <p>
254      For more information on Chrome Manifests and the properties
> they support, see the <a href="en/Chrome_Manifest">Chrome Manife 
>st</a> Reference. 
255    </p>
256    <p>
257      Open the file called <b>chrome.manifest</b> that you create
>d alongside the <tt>chrome</tt> directory at the root of your ext 
>ension's source folder hierarchy. 
258    </p>
259    <p>
260      Add in this code:
261    </p>
262    <pre class="eval">
263content     sample    chrome/content/
264</pre>
265    <p>
266      (<b>Don't forget the trailing slash, "<tt>/</tt>"!</b> With
>out it, the package won't be registered.) 
267    </p>
268    <p>
269      This specifies the:
270    </p>
271    <ol>
272      <li>type of material within a chrome package
273      </li>
274      <li>name of the chrome package (make sure you use all lower
>case characters for the package name ("sample") as Firefox/Thunde 
>rbird doesn't support mixed/camel case in version 2 and earlier - 
> {{template.Bug(132183)}}) 
275      </li>
276      <li>location of the chrome packages' files
277      </li>
278    </ol>
279    <p>
280      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/ 
>content</tt> which is a path relative to the location of <tt>chro 
>me.manifest</tt>. 
281    </p>
282    <p>
283      Note that content, locale and skin files must be kept insid
>e folders called content, locale and skin within your <tt>chrome< 
>/tt> subdirectory. 
284    </p>
285    <p>
286      Save the file. When you launch Firefox with your extension,
> (later in this tutorial), this will register the chrome package. 
287    </p>
288    <h4 name="Register_an_Overlay">
289      Register an Overlay
290    </h4>
291    <p>
292      You need Firefox to merge your overlay with the browser win
>dow whenever it displays one. So add this line to your <tt>chrome 
>.manifest</tt> file: 
293    </p>
294    <pre class="eval">
295overlay chrome://browser/content/browser.xul chrome://sample/cont
>ent/sample.xul 
296</pre>
297    <p>
298      This tells Firefox to merge <tt>sample.xul</tt> into <tt>br
>owser.xul</tt> when <tt>browser.xul</tt> loads. 
299    </p>
300    <h4 name="Test">
301      Test
302    </h4>
303    <p>
304      First, we need to tell Firefox about your extension. In the
> bad old days of Firefox 1.0 this meant packaging your extension  
>as a XPI and installing it through the user interface, which was  
>a real pain. Now, it's much simpler. 
305    </p>
306    <ol>
307      <li>Open your <a class="external" href="http://kb.mozillazi
>ne.org/Profile_folder">Profile Folder</a> 
308      </li>
309      <li>Open the <b>extensions</b> folder (create it if it does
>n't exist) 
310      </li>
311      <li>Create a new text file, and put the path to your extens
>ion folder inside, e.g. <tt>C:\extensions\my_extension\</tt> or < 
>tt>~/extensions/my_extension/</tt>. Save the file with the id of  
>your extension as its name, e.g. <tt>sample@foo.net</tt> 
312      </li>
313    </ol>
314    <p>
315      (<b>Don't forget the trailing slash, "<tt>/</tt>"!</b> With
>out it, the extension won't get registered.) 
316    </p>
317    <p>
318      Now you're ready to test your extension!
319    </p>
320    <p>
321      Start Firefox. Firefox will detect the text link to your ex
>tension directory and install the Extension. When the browser win 
>dow appears you should see the text "Hello, World!" on the right  
>side of the status bar panel. 
322    </p>
323    <p>
324      You can now go back and make changes to the .xul file, clos
>e and restart Firefox and they should appear. 
325    </p>
326    <p>
327      <span class="comment">These don't actually match the descri
>bed extension and confuse people. -Nickolay CENTER&gt; {{mediawik 
>i.internal('Image:Helloworld_tools_menu.PNG', "en")}} {{mediawiki 
>.internal('Image:Helloworld_extensions_wnd.PNG', "en")}} &lt;/CEN 
>TER</span> 
328    </p>
329    <h4 name="Package">
330      Package
331    </h4>
332    <p>
333      Now that your extension works, you can <a href="en/Extensio
>n_Packaging">package</a> it for deployment and installation. 
334    </p>
335    <p>
336      Zip up the <b>contents</b> of your extension's folder (not 
>the extension folder itself), and rename the zip file to have a . 
>xpi extension. In Windows XP, you can do this easily by selecting 
> all the files and subfolders in your extension folder, right cli 
>ck and choose "Send To -&gt; Compressed (Zipped) Folder". A .zip  
>file will be created for you. Just rename it and you're done! 
337    </p>
338    <p>
339      On Mac OS X, you can right-click on the <b>contents</b> of 
>the extension's folder and choose "Create Archive of..." to make  
>the zip file. However, since Mac OS X adds hidden files to folder 
>s in order to track file metadata, you should instead use the Ter 
>minal, delete the hidden files (whose names begin with a period), 
> and then use the <tt>zip</tt> command on the command line to cre 
>ate the zip file. 
340    </p>
341    <p>
342      On Linux, you would likewise use the command-line Zip tool.
343    </p>
344    <p>
345      If you have the 'Extension Builder' extension installed it 
>can compile the .xpi file for you (Tools -&gt; Extension Develope 
>r -&gt; Extension Builder). Merely navigate to the directory wher 
>e your extension is (install.rdf etc.), and hit the Build Extensi 
>on button. This extension has a slew of tools to make development 
> easier. 
346    </p>
347    <p>
348      Now upload the .xpi file to your server, making sure it's s
>erved as <tt>application/x-xpinstall</tt>. You can link to it and 
> allow people to download and install it in Firefox. For the purp 
>oses of just testing our .xpi file we can just drag it into the e 
>xtensions window via Tools -&gt; Extensions, or Tools -&gt; Add-o 
>ns in FireFox 2. 
349    </p>
350    <h5 name="Installing_from_a_web_page">
351      Installing from a web page
352    </h5>
353    <p>
354      There are a variety of ways you can install extensions from
> web pages, including direct linking to the XPI files and using t 
>he InstallTrigger object. Extension and web authors are encourage 
>d to use the <a href="en/Installing_Extensions_and_Themes_From_We 
>b_Pages">InstallTrigger method</a> to install XPIs, as it provide 
>s the best experience to users. 
355    </p>
356    <h5 name="Using_addons.mozilla.org">
357      Using addons.mozilla.org
358    </h5>
359    <p>
360      Mozilla Update is a distribution site where you can host yo
>ur extension for free. Your extension will be hosted on Mozilla's 
> mirror network to guarantee your download even though it might b 
>e very popular. Mozilla's site also provides users easier install 
>ation, and will automatically make your newer versions available  
>to users of your existing versions when you upload them. In addit 
>ion Mozilla Update allows users to comment and provide feedback o 
>n your extension. It is highly recommended that you use Mozilla U 
>pdate to distribute your extensions! 
361    </p>
362    <p>
363      Visit http://addons.mozilla.org/developers/ to create an ac
>count and begin distributing your extensions! 
364    </p>
365    <p>
366      <i>Note:</i> Your Extension will be passed faster and downl
>oaded more if you have a good description and some screenshots of 
> the extension in action. 
367    </p>
368    <h5 name="Registering_Extensions_in_the_Windows_Registry">
369      Registering Extensions in the Windows Registry
370    </h5>
371    <p>
372      On Windows, information about extensions can be added to th
>e registry, and the extensions will automatically be picked up th 
>e next time the applications starts. This allows application inst 
>allers to easily add integration hooks as extensions. See <a href 
>="en/Adding_Extensions_using_the_Windows_Registry">Adding Extensi 
>ons using the Windows Registry</a> for more information. 
373    </p>
374    <h4 name="More_on_XUL_Overlays">
375      More on XUL Overlays
376    </h4>
377    <p>
378      In addition to appending UI widgets to the merge point, you
> can use XUL fragments within Overlays to: 
379    </p>
380    <ul>
381      <li>Modify attributes on the merge point, e.g. <tt>&lt;stat
>usbar id="status-bar" hidden="true"/&gt;</tt> (hides the status b 
>ar) 
382      </li>
383      <li>Remove the merge point from the master document, e.g. <
>tt>&lt;statusbar id="status-bar" removeelement="true"/&gt;</tt> 
384      </li>
385      <li>Control the position of the inserted widgets:
386      </li>
387    </ul>
388    <pre class="eval">
389&lt;statusbarpanel position="1" .../&gt;
390 
391&lt;statusbarpanel insertbefore="other-id" .../&gt;
392 
393&lt;statusbarpanel insertafter="other-id" .../&gt;
394</pre>
395    <h4 name="Creating_New_User_Interface_Components">
396      Creating New User Interface Components
397    </h4>
398    <p>
399      You can create your own windows and dialog boxes as separat
>e .xul files, provide functionality by implementing user actions  
>in .js files, using DOM methods to manipulate UI widgets. You can 
> use style rules in .css files to attach images, set colors etc. 
400    </p>
401    <p>
402      View the <a href="en/XUL">XUL</a> documentation for more re
>sources for XUL developers. 
403    </p>
404    <h4 name="Defaults_Files">
405      Defaults Files
406    </h4>
407    <p>
408      Defaults files that you use to seed a user's profile with s
>hould be placed in <tt>defaults/</tt> under the root of your exte 
>nsion's folder hierarchy. Default preferences .js files should be 
> stored in <tt>defaults/preferences/</tt> - when you place them h 
>ere they will be automatically loaded by Firefox's preferences sy 
>stem when it starts so that you can access them using the <a href 
>="en/Preferences_API">Preferences API</a>. 
409    </p>
410    <p>
411      An example default preference file:
412    </p>
413    <pre class="eval">
414pref("extensions.sample.username", "Joe"); //a string pref
415pref("extensions.sample.sort", 2); //an int pref
416pref("extensions.sample.showAdvanced", true); //a boolean pref
417</pre>
418    <h4 name="XPCOM_Components">
419      XPCOM Components
420    </h4>
421    <p>
422      Firefox supports <a href="en/XPCOM">XPCOM</a> components in
> extensions. You can create your own components easily in JavaScr 
>ipt or in C++ (using the <a href="en/Gecko_SDK">Gecko SDK</a>). 
423    </p>
424    <p>
425      Place all of your .js or .dll files in the <tt>components/<
>/tt> directory - they are automatically registered the first time 
> Firefox runs after your extension is installed. 
426    </p>
427    <p>
428      For more information see <a href="en/How_to_Build_an_XPCOM_
>Component_in_Javascript">How to Build an XPCOM Component in Javas 
>cript</a>, <a href="en/How_to_build_a_binary_XPCOM_component_usin 
>g_Visual_Studio">How to build a binary XPCOM component using Visu 
>al Studio</a> and the <a href="en/Creating_XPCOM_Components">Crea 
>ting XPCOM Components</a> book. 
429    </p>
430    <h5 name="Application_Command_Line">
431      Application Command Line
432    </h5>
433    <p>
434      One of the possible uses of custom XPCOM components is addi
>ng a command line handler to Firefox or Thunderbird. You can use  
>this technique to run your extension as an application: 
435    </p>
436    <pre class="eval">
437 firefox.exe -myapp
438</pre>
439    <p>
440      <span class="comment">I should move the useful parts of thi
>s to the Command Line page. -Nickolay This is done by adding a co 
>mponent containing the function... function NSGetModule(comMgr, f 
>ileSpec) { return myAppHandlerModule; } This function is run by f 
>irefox each time firefox is started. Firefox registers the myAppH 
>andlerModule's by calling its 'registerSelf()'. Then it obtains t 
>he myAppHandlerModule's handler factory via 'getClassObject()'. T 
>he handler factory is then used to create the handle using its 'c 
>reateInstance(). Finally, the handle's 'handle(cmdline)' processe 
>s the command line cmdline's handleFlagWithParam() and handleFlag 
>().</span> See <a href="en/Chrome/Command_Line">Chrome: Command L 
>ine</a> and a <a class="external" href="http://forums.mozillazine 
>.org/viewtopic.php?t=365297">forum discussion</a> for details. 
441    </p>
442    <h4 name="Localization">
443      Localization
444    </h4>
445    <p>
446      To support more than one language, you should separate stri
>ngs from your content using <a href="en/XUL_Tutorial/Localization 
>">entities</a> and <a href="en/XUL_Tutorial/Property_Files">strin 
>g bundles</a>. It is much easier to do this while you are develop 
>ing your extension, rather than come back and do it later! 
447    </p>
448    <p>
449      Localization information is stored in the locale directory 
>for the extension. For example, to add a locale to our sample ext 
>ension, create a directory named "locale" in chrome (where the "c 
>ontent" directory is located) and add the following line to the c 
>hrome.manifest file: 
450    </p>
451    <pre class="eval">
452locale sample sampleLocale chrome/locale/
453</pre>
454    <p>
455      To create localizable attribute values in XUL, you put the 
>values in a <tt>.ent</tt> (or a <tt>.dtd</tt>) file, which should 
> be placed in the locale directory and looks like this: 
456    </p>
457    <pre class="eval">
458&lt;!ENTITY  button.label     "Click Me!"&gt;
459&lt;!ENTITY  button.accesskey "C"&gt;
460</pre>
461    <p>
462      And then include it at the top of your XUL document (but un
>derneath the "&lt;?xml version"1.0"?&gt;") like so: 
463    </p>
464    <pre class="eval">
465&lt;!DOCTYPE <b>window</b> SYSTEM "chrome://packagename/locale/fi
>lename.ent"&gt; 
466</pre>
467    <p>
468      where <code><b>window</b></code> is the <code><a href="en/D
>OM/element.localName">localName</a></code> value of the root elem 
>ent of the XUL document, and the value of the <tt>SYSTEM</tt> pro 
>perty is the chrome URI to the entity file. For our sample extens 
>ion, the root element is <code><b>overlay</b></code>. 
469    </p>
470    <p>
471      To use the entities, modify your XUL to look like this:
472    </p>
473    <pre class="eval">
474&lt;button label="&amp;button.label;" accesskey="&amp;button.acce
>sskey;"/&gt; 
475</pre>
476    <p>
477      The Chrome Registry will make sure the entity file is loade
>d from the localization bundle corresponding to the selected loca 
>le. 
478    </p>
479    <p>
480      For strings that you use in script, create a .properties fi
>le, a text file that has a string on each line in this format: 
481    </p>
482    <pre class="eval">
483key=value
484</pre>
485    <p>
486      and then use <tt><a href="en/NsIStringBundleService">nsIStr
>ingBundleService</a></tt>/<tt><a href="en/NsIStringBundle">nsIStr 
>ingBundle</a></tt> or the <tt><a class="external" href="http://xu 
>lplanet.com/references/elemref/ref_stringbundle.html">&lt;stringb 
>undle&gt;</a></tt> tag to load the values into script. 
487    </p>
488    <h4 name="Understanding_the_Browser">
489      Understanding the Browser
490    </h4>
491    <p>
492      Use the <a href="en/DOM_Inspector">DOM Inspector</a> (not p
>art of the <b>Standard</b> Firefox installation, you must reinsta 
>ll with the Custom install path and choose <b>Developer Tools</b> 
> if there is not a "DOM Inspector" item in your browser's Tools m 
>enu) to inspect the browser window or any other XUL window you wa 
>nt to extend. 
493    </p>
494    <p>
495      Use the point-and-click node finder button at the top left 
>of the DOM Inspector's toolbar to click on a node in the XUL wind 
>ow visually to select it. When you do this the DOM inspector's DO 
>M hierarchy tree view will jump to the node you clicked on. 
496    </p>
497    <p>
498      Use the DOM Inspector's right side panel to discover merge 
>points with ids that you can use to insert your elements from ove 
>rlays. If you cannot discover an element with an id that you can  
>merge into, you may need to attach a script in your overlay and i 
>nsert your elements when the <tt>load</tt> event fires on the mas 
>ter XUL window. 
499    </p>
500    <h4 name="Debugging_Extensions">
501      Debugging Extensions
502    </h4>
503    <p>
504      <b>Analytical Tools for Debugging</b>
505    </p>
506    <ul>
507      <li>The <a href="en/DOM_Inspector">DOM Inspector</a> - insp
>ect attributes, DOM structure, CSS style rules that are in effect 
> (e.g. find out why your style rules don't seem to be working for 
> an element - an invaluable tool!) 
508      </li>
509      <li>
510        <a href="en/Venkman">Venkman</a> - set breakpoints in Jav
>aScript and inspect call stacks 
511      </li>
512      <li>
513        <code><a href="en/Core_JavaScript_1.5_Reference/Objects/F
>unction/arguments/callee">arguments.callee</a>.<a href="en/Core_J 
>avaScript_1.5_Reference/Objects/Function/caller">caller</a></code 
>> in JavaScript - access a function's call stack 
514      </li>
515    </ul>
516    <p>
517      <b>printf debugging</b>
518    </p>
519    <ul>
520      <li>Run Firefox with <tt>-console</tt> at the command line 
>and use <code><a href="en/DOM/window.dump">dump</a>("string")</co 
>de> (see the link for details) 
521      </li>
522      <li>Use <code><a href="en/NsIConsoleService">nsIConsoleServ
>ice</a></code> to log to the JavaScript console 
523      </li>
524    </ul>
525    <p>
526      <b>Advanced debugging</b>
527    </p>
528    <ul>
529      <li>Run a debug Firefox build and set breakpoints in Firefo
>x itself, or your C++ components. For the experienced developer,  
>this is often the fastest way to diagnose a problem. See <a href= 
>"en/Build_Documentation">Build Documentation</a> and <a href="en/ 
>Developing_Mozilla">Developing Mozilla</a> for more information. 
530      </li>
531      <li>See <a href="en/Debugging_a_XULRunner_Application">Debu
>gging a XULRunner Application</a> for more helpful tips. 
532      </li>
533    </ul>

Back to History