Compare Revisions

Creating a Firefox sidebar

Change Revisions

Revision 453317:

Revision 453317 by kohei.yoshino on

Revision 454625:

Revision 454625 by kohei.yoshino on

Title:
Creating a Firefox sidebar
Creating a Firefox sidebar
Slug:
Creating_a_Firefox_sidebar
Creating_a_Firefox_sidebar
Tags:
"Extensions", "Add-ons", "Firefox"
"Extensions", "Add-ons", "Firefox"
Content:

Revision 453317
Revision 454625
n8      {{outdated("It was last updated in 2011.")}}n8      Web publishers can offer visitors a <strong>Firefox sidebar
 ></strong> to encourage their engagement. There are two ways to cr
 >eate a sidebar for Firefox users: the Social API and an extension
 >. You can choose either depending on your needs and resources.
9    </p>
10    <h2>
11      The Social API
12    </h2>
13    <p>
14      {{ Fx_minversion_section(17) }}
n11      This article describes how to create a registered sidebar fn17      The <a href="/en-US/docs/Social_API">Social API</a> is a ne
>or Firefox 2 or greater. See the references section for informati>w API from Mozilla that allows social media services to integrate
>on on creating extension in earlier browsers.> their content into the browser window. At this time, <a href="ht
 >tps://blog.mozilla.org/blog/2012/12/03/firefox-gets-social-w-face
 >book/">Facebook</a>, <a href="https://blog.mozilla.org/blog/2013/
 >05/14/stay-social-with-firefox/">Cliqz, mixi and MSN</a> are part
 >nering with Mozilla as social providers. Now the <a href="https:/
 >/blog.mozilla.org/futurereleases/2013/06/27/social-api-for-all/">
 >API is available to all Web developers</a> so it's worth checking
 > out if you are offering a social service.
n13    <h2 id="Introduction" name="Introduction">n19    <h2>
14      Introduction20      An extension
n17      This article is a quick start for the creation of a new sidn23      An <a href="/en-US/docs/Extensions">extension</a> is a kind
>ebar for Firefox. What we will do is create a sidebar and registe> of <a href="/en-US/docs/Mozilla/Add-ons">add-ons</a> that adds n
>r it so it will be available in the menu. The goal is creating an>ew functionalities to Firefox. There is a wide range of extension
> empty sidebar that can be used as start for new sidebar applicat>s available, and <a href="https://addons.mozilla.org/en-US/firefo
>ions.>x/search/?q=sidebar">some of them provide a sidebar</a>. Such kin
 >d of sidebar can be a simple Web panel or a full-featured extensi
 >on that is completely integrated with the browser. You can find a
 > <a href="https://github.com/kyoshino/simple-sidebar">sample exte
 >nsion to add a Web panel</a> as a starter.
24    </p>
25    <h2>
26      The <code>window.sidebar</code> API
27    </h2>
28    <p>
29      {{ obsolete_header(23) }}
t20      Creating a sidebar requires some GUI creation and registratt32      As of <a href="/en-US/docs/Mozilla/Firefox/Releases/23">Fir
>ion in the destination application. First a simple XUL page is cr>efox&nbsp;23</a>, the <code>addPanel</code> and <code>addPersiste
>eated. Then the registration files are made and finally the sideb>ntPanel</code> functions have been removed from the deprecated, N
>ar is packed into an installable XPI file.>etscape-derived {{ domxref("window.sidebar") }} object. That mean
 >s <a href="/en-US/docs/Creating_a_Firefox_sidebar_extension">the 
 >ability to add a traditional sidebar panel</a> is no longer avail
 >able from Web content. The new Social API or an extension can be 
 >used instead as described above.
21    </p>
22    <h2 id="Pre-requisites" name="Pre-requisites">
23      Pre-requisites
24    </h2>
25    <p>
26      This article is a quick start, it won't explain all element
>s of <a href="/en/XUL" title="en/XUL">XUL</a>, packaging and XPI' 
>s. It's preferable you have some basic knowledge of how XUL works 
> and how Firefox handles extensions. See <a href="/en/Building_an 
>_Extension" title="en/Building_an_Extension">Building an Extensio 
>n</a> for more detailed information about structuring, packaging, 
> and deploying extensions. 
27    </p>
28    <h2 id="Packages" name="Packages">
29      Packages
30    </h2>
31    <p>
32      Extensions to Firefox are installed with packages ("<a href
>="/en/Bundles" title="en/Bundles">Bundles</a>"). An extension pac 
>kage usually contains a "content" provider, which contains the XU 
>L code and application logic. Optionally locales and skins can be 
> included. Most additions are provided with a default tree struct 
>ure, although not required it is recommended to use this structur 
>e. Here the package for the sidebar is created, the files include 
>d are listed below. 
33    </p>
34    <div class="example" id="package_structure">
35      <p>
36        <strong>Example&nbsp;1.&nbsp;Package structure</strong>
37      </p>
38      <pre>
39emptysidebar
40\- chrome
41   |- content
42   |- locale
43   | \- en-US 
44   \- skin
45</pre>
46    </div>
47    <p>
48      Create all folders, except for <code>skin</code>. It is not
> used for this tutorial. 
49    </p>
50    <p>
51      The <code>locale</code> holds the locale, only the <code>en
>-US</code> locale is created. It is listed in <a href="#en-us_emp 
>tysidebar.dtd">Example 2</a>. The locale includes the name and sh 
>ortcut keys for the sidebar. 
52    </p>
53    <div class="example" id="en-us_emptysidebar.dtd">
54      <p>
55        <strong>Example&nbsp;2.&nbsp;chrome/locale/en-US/emptysid
>ebar.dtd</strong> 
56      </p>
57      <pre class="eval">
58&lt;!ENTITY emptysidebar.title "EmptySidebar"&gt;
59&lt;!ENTITY openEmptySidebar.commandkey "E"&gt;
60&lt;!ENTITY openEmptySidebar.modifierskey "shift accel"&gt;
61</pre>
62      <p>
63        The content folder includes our sidebar, the <code>emptys
>idebar.xul</code> is shown in <a href="#emptysidebar_xul">Example 
> 3</a>. It creates a <a class="external" href="http://books.mozde 
>v.org/html/appc-77238.html">page</a> holding one label. Other ele 
>ments can be included, please read the XUL tutorials for more inf 
>ormation. 
64      </p>
65      <div class="example" id="emptysidebar_xul">
66        <p>
67          <strong>Example&nbsp;3.&nbsp;chrome/content/emptysideba
>r.xul</strong> 
68        </p>
69        <pre>
70&lt;?xml version="1.0"?&gt;
71&lt;?xml-stylesheet href="chrome://global/skin/" type="text/css" 
>?&gt; 
72&lt;?xml-stylesheet href="chrome://browser/skin/browser.css" type
>="text/css" ?&gt; 
73&lt;!DOCTYPE page SYSTEM "chrome://emptysidebar/locale/emptysideb
>ar.dtd"&gt; 
74 
75&lt;page id="sbEmptySidebar" title="&amp;emptysidebar.title;"
76         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there
>.is.only.xul" &gt; 
77  &lt;vbox flex="1"&gt;
78    &lt;label id="atest" value="&amp;emptysidebar.title;" /&gt;
79  &lt;/vbox&gt;
80&lt;/page&gt;
81</pre>
82      </div>
83      <p>
84        New extensions can be registered in the menus or popups, 
>Firefox uses overlays for extending menus. This is an separate XU 
>L file that specifies the location of menu items. The sidebar her 
>e is added to the View | Sidebar menu. The overlay file is listed 
> in <a href="#overlay_xul">Example 4</a>. 
85      </p>
86      <div class="example" id="overlay_xul">
87        <p>
88          <strong>Example&nbsp;4.&nbsp;chrome/content/firefoxOver
>lay.xul</strong> 
89        </p>
90        <pre>
91&lt;?xml version="1.0"?&gt;
92 
93&lt;!DOCTYPE overlay SYSTEM "chrome://emptysidebar/locale/emptysi
>debar.dtd"&gt; 
94&lt;overlay id="emptySidebarOverlay"
95         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there
>.is.only.xul"&gt; 
96  
97  &lt;menupopup id="viewSidebarMenu"&gt;
98    &lt;menuitem key="key_openEmptySidebar" observes="viewEmptySi
>debar"  /&gt; 
99  &lt;/menupopup&gt;
100  
101  &lt;keyset id="mainKeyset"&gt;
102    &lt;key id="key_openEmptySidebar" command="viewEmptySidebar"
103         key="&amp;openEmptySidebar.commandkey;" 
104         modifiers="&amp;openEmptySidebar.modifierskey;" /&gt;
105  &lt;/keyset&gt;
106  
107  &lt;broadcasterset id="mainBroadcasterSet"&gt; 
108    &lt;broadcaster id="viewEmptySidebar" 
109                 label="&amp;emptysidebar.title;"
110                 autoCheck="false"
111                 type="checkbox"
112                 group="sidebar"
113                 sidebarurl="chrome://emptysidebar/content/emptys
>idebar.xul" 
114                 sidebartitle="&amp;emptysidebar.title;"
115                 oncommand="toggleSidebar('viewEmptySidebar');" /
>&gt; 
116  &lt;/broadcasterset&gt;
117&lt;/overlay&gt;
118</pre>
119      </div>
120      <p>
121        The overlay file consists of three entries, the menu defi
>nition, shortcut keys and the broadcaster. 
122      </p>
123      <p>
124        The broadcaster serves two purposes. The first is it indi
>rectly provides the arguments for the toggleSidebar function. The 
> second is it provides attributes to the menuitem, some of which  
>are changed automatically when toggleSidebar is called. See <a hr 
>ef="/En/Code_snippets/Sidebar" title="En/Code snippets/Sidebar">C 
>ode_snippets/Sidebar</a> for more information. 
125      </p>
126      <p>
127        If the sidebar is not going to have a command-key, one ca
>n remove the <code>openEmptySidebar.commandkey</code> and <code>o 
>penEmptySidebar.modifierskey</code> keys from the dtd, remove the 
> <code>&lt;keyset&gt;</code> from the <code>firefoxOverlay.xul</c 
>ode> file. One must then set the key attribute of the menuitem to 
> "". 
128      </p>
129      <p>
130        The extension needs to provide some special manifest file
>s that control how it is installed and where its chrome resources 
> are stored. The first is <code>install.rdf</code>, the install m 
>anifest. See <a href="/en/Install_Manifests" title="en/Install_Ma 
>nifests">Install Manifests</a> for a complete listing of the requ 
>ired and optional properties. The install manifest is listed in < 
>a href="#install_manifest">Example 5</a>. 
131      </p>
132      <div class="example" id="install_manifest">
133        <p>
134          <strong>Example&nbsp;5.&nbsp;install.rdf</strong>
135        </p>
136        <pre>
137&lt;?xml version="1.0" encoding="UTF-8"?&gt;
138 
139&lt;RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
140 xmlns:em="http://www.mozilla.org/2004/em-rdf#"&gt;
141  &lt;Description about="urn:mozilla:install-manifest"&gt;
142    &lt;em:id&gt;emptysidebar@yourdomain.com&lt;/em:id&gt;
143    &lt;em:name&gt;EmptySidebar Extension&lt;/em:name&gt;
144    &lt;em:version&gt;1.0&lt;/em:version&gt;
145    &lt;em:creator&gt;Your Name&lt;/em:creator&gt;
146    &lt;em:description&gt;Example extension for creation and regi
>stration of a sidebar.&lt;/em:description&gt; 
147    &lt;em:targetApplication&gt;
148      &lt;Description&gt;
149        &lt;em:id&gt;{ec8030f7-c20a-464f-9b0e-13a3a9e97384}&lt;/e
>m:id&gt; &lt;!-- firefox --&gt; 
150        &lt;em:minVersion&gt;1.5&lt;/em:minVersion&gt;
151        &lt;em:maxVersion&gt;2.0.0.*&lt;/em:maxVersion&gt;
152      &lt;/Description&gt;
153    &lt;/em:targetApplication&gt;
154  &lt;/Description&gt;
155&lt;/RDF&gt;
156</pre>
157      </div>
158      <p>
159        The other manifest file is <code>chrome.manifest</code>, 
>the chrome manifest file. The chrome manifest creates a lookup fo 
>r all the resource types used by the extension. The manifest also 
> tells Firefox that the extension has an overlay that needs to be 
> merged into the browser. For more information on chrome manifest 
>s and the properties they support, see the <a href="/en/Chrome_Re 
>gistration" title="en/Chrome_Registration">Chrome Manifest</a> re 
>ference. The manifest used in this extension is listed in <a href 
>="#chrome_manifest">Example 6</a>. 
160      </p>
161      <div class="example" id="chrome_manifest">
162        <p>
163          <strong>Example&nbsp;6.&nbsp;chrome.manifest</strong>
164        </p>
165        <pre>
166content emptysidebar    chrome/content/
167locale  emptysidebar    en-US   chrome/locale/en-US/
168skin    emptysidebar    classic/1.0     chrome/skin/
169overlay chrome://browser/content/browser.xul    chrome://emptysid
>ebar/content/firefoxOverlay.xul 
170</pre>
171      </div>
172      <h2 id="Test" name="Test">
173        Test
174      </h2>
175      <p>
176        While you're developing your sidebar, you will need to te
>st it frequently from Firefox. There is a simple way to do this.  
>First, we need to tell Firefox about your extension. 
177      </p>
178      <ol>
179        <li>Open your <a class="external" href="http://support.mo
>zilla.com/en-US/kb/Profiles" title="http://support.mozilla.com/en 
>-US/kb/Profiles">Profile Folder</a> 
180        </li>
181        <li>Open the extensions folder (create it if it doesn't e
>xist) 
182        </li>
183        <li>Create a new text file, and put the path to your exte
>nsion folder inside, e.g. <code>C:\extensions\myExtension</code>  
>or <code>~/extensions/myExtension</code>. Save the file with the  
>id of your extension as its name, e.g. <code><a class="link-mailt 
>o" href="mailto:emptysidebar@yourdomain.com" rel="freelink">empty 
>sidebar@yourdomain.com</a></code> 
184        </li>
185      </ol>
186      <p>
187        Now you're ready to test your extension! Restart Firefox 
>and the sidebar is included in the menu. 
188      </p>
189      <p>
190        <img alt="Image:sidebar-test.png" class="internal" src="/
>@api/deki/files/850/=Sidebar-test.png"> 
191      </p>
192      <p>
193        You can now go back and make changes to the XUL file, clo
>se and restart Firefox and they should appear. 
194      </p>
195      <h2 id="Deployment" name="Deployment">
196        Deployment
197      </h2>
198      <p>
199        Now that we have a sidebar it is time to make it availabl
>e to the world. Installation requires the creation of an XPI file 
> which is identified as extension in Firefox. The XPI is a ZIP fi 
>le containing the content, locale and manifest files. 
200      </p>
201      <p>
202        The content, locale and skin folders are packed into <cod
>e>emptysidebar.jar</code>, which should be created in the <code>c 
>hrome</code> folder. On unix systems: 
203      </p>
204      <pre class="eval">
205~/src/emptysidebar$ <strong>cd chrome</strong>
206~/src/emptysidebar/chrome$ <strong>zip -r emptysidebar.jar conten
>t/ locale/</strong> 
207</pre>
208      <p>
209        On Windows systems, use a ZIP tool to create <code>emptys
>idebar.zip</code> and then rename to <code>emptysidebar.jar</code 
>>. 
210      </p>
211      <p>
212        Since we are packaging the extension with a JAR file, we 
>need to update the chrome.manifest file to take to JAR file into  
>consideration: 
213      </p>
214      <div class="example" id="chrome_manifest_jar">
215        <p>
216          <strong>Example&nbsp;7.&nbsp;chrome.manifest</strong>
217        </p>
218        <pre>
219content emptysidebar    jar:chrome/emptysidebar.jar!/content/
220locale  emptysidebar    en-US   jar:chrome/emptysidebar.jar!/loca
>le/en-US/ 
221skin    emptysidebar    classic/1.0     jar:chrome/emptysidebar.j
>ar!/skin/ 
222overlay chrome://browser/content/browser.xul    chrome://emptysid
>ebar/content/firefoxOverlay.xul 
223</pre>
224      </div>
225      <p>
226        Finally, create the XPI file. This is a ZIP file containi
>ng the JAR file in the chrome folder and the manifest files. On u 
>nix systems: 
227      </p>
228      <pre class="eval">
229~/src/emptysidebar/chrome$ <strong>cd ..</strong>
230~/src/emptysidebar$ <strong>zip emptysidebar.xpi install.rdf chro
>me.manifest chrome/emptysidebar.jar</strong> 
231</pre>
232      <p>
233        Open Firefox and browse to the folder containing <code>em
>ptysidebar.xpi</code>. Click on the file and the Extension instal 
>lation window pops up. After a restart of Firefox, the sidebar is 
> installed. 
234      </p>
235      <p>
236        You can download the <a class="external" href="http://dev
>eloper.mozilla.org/samples/extension-samples/emptysidebar.zip">em 
>pty sidebar project</a> to use as a basis for your own sidebars. 
237      </p>
238      <div class="figure" id="emptysidebar_extension">
239        <p>
240          <img alt="Image:sidebar-installed.png" class="internal"
> src="/@api/deki/files/849/=Sidebar-installed.png"><br> 
241          <strong>The EmptySidebar extension</strong>
242        </p>
243      </div>
244      <h2 id="Resources" name="Resources">
245        Resources
246      </h2>
247      <ul>
248        <li>
249          <a href="/en/Code_snippets/Sidebar" title="en/Code_snip
>pets/Sidebar">Code snippets:Sidebar</a> 
250        </li>
251        <li>
252          <a href="/en/Building_an_Extension" title="en/Building_
>an_Extension">Building an Extension</a> 
253        </li>
254        <li>
255          <a class="external" href="http://books.mozdev.org/html/
>index.html">Creating Applications with Mozilla</a> 
256        </li>
257        <li>
258          <a class="external" href="http://www.bengoodger.com/sof
>tware/mb/extensions/packaging/extensions.html">Packaging Firefox/ 
>Thunderbird Extensions</a> 
259        </li>
260        <li>
261          <a class="external" href="http://occidopagus.nl/firefox
>/emptysidebar/">Creating a Firefox 1 Sidebar</a> 
262        </li>
263      </ul>
264      <div class="originaldocinfo">
265        <h2 id="Original_Document_Information" name="Original_Doc
>ument_Information"> 
266          Original Document Information
267        </h2>
268        <ul>
269          <li>Author: J.C. Wesdorp &lt;jcwesdorp&nbsp;.&nbsp;at&n
>bsp;.&nbsp;occidopagus.nl&gt; - May 30, 2005. 
270          </li>
271          <li>Updated for Firefox 2 - Dec 12, 2006.
272          </li>
273          <li>Permission granted to migrate in Jan 2006, includin
>g permission to relicense under the CC:By-SA. 
274          </li>
275          <li>Original Source: <a class="external" href="http://o
>ccidopagus.nl/firefox/emptysidebar/" rel="freelink">http://occido 
>pagus.nl/firefox/emptysidebar/</a> 
276          </li>
277        </ul>
278      </div>
279    </div>
280    <p>
281      {{ languages( { "es": "es/Crear_un_panel_lateral_en_Firefox
>" } ) }} 

Back to History