path: root/files/pt-br/mozilla/add-ons/sdk/low-level_apis/ui_sidebar/index.html

---
title: ui/sidebar
slug: Mozilla/Add-ons/SDK/Low-Level_APIs/ui_sidebar
translation_of: Archive/Add-ons/Add-on_SDK/Low-Level_APIs/ui_sidebar
---
<p>{{AddonSidebar}}</p>

<div class="note">
<p>Experimental</p>
</div>

<p><span class="seoSummary">Enables you to create sidebars.</span> A sidebar is a vertical strip of user interface real estate for your add-on that's attached to the left-hand side of the browser window. You specify its content using HTML, CSS, and JavaScript, and the user can show or hide it in the same way they can show or hide the built-in sidebars.</p>

<h2 id="Usage">Usage</h2>

<h3 id="Creating_showing_and_hiding_sidebars">Creating, showing, and hiding sidebars</h3>

<p>You construct a <code>Sidebar</code> object using the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#Sidebar(options)"><code>Sidebar()</code></a> constructor.</p>

<p>Once you've done that, you can show the sidebar by calling the Sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show()"><code>show()</code></a> method. If a new window is opened from a window that has a sidebar visible, the new window gets a sidebar, too.</p>

<p>You can hide the sidebar by calling its <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#hide()"><code>hide()</code></a> method.</p>

<p>Called with no arguments, <code>show()</code> and <code>hide()</code> will operate on the currently active window. From Firefox 33 onwards you can pass a <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow"><code>BrowserWindow</code></a> into these methods, and they will then operate on the specified window.</p>

<p>Alternatively, the View-&gt;Sidebar submenu in Firefox will contain a new item which the user can use to show or hide the sidebar:</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/6667/sidebar-menu.png" style="display: block; height: 229px; margin-left: auto; margin-right: auto; width: 518px;">The sidebar generates a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show"><code>show</code></a> event when it is shown and a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#hide"><code>hide</code></a> event when it is hidden.</p>

<p>Once you've finished using the sidebar you can destroy it by calling its <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#dispose()"><code>dispose()</code></a> method.</p>

<p>To show what a sidebar looks like, here's a sidebar that displays the results of running the <a href="http://validator.w3.org/">W3C Validator</a> on the current page:</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/6669/sidebar.png" style="display: block; margin-left: auto; margin-right: auto;"></p>

<h3 id="Specifying_sidebar_content">Specifying sidebar content</h3>

<p>O conteúdo de uma barra lateral é especificado usando HTML, que é carregado a partir da URL fornecida na opção url do construtor da barra lateral. Ao contrário de módulos como <a href="/en-US/Add-ons/SDK/High-Level_APIs/panel"><code>panel</code></a>,  o conteúdo deve ser local, normalmente carregado do diretório de dados ('data') da extensão, através de um URL contruída usando <a href="/en-US/Add-ons/SDK/High-Level_APIs/self#data"><code>self.data.url()</code></a>:</p>

<pre class="brush: js">var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My sidebar',
  url: require("sdk/self").data.url("sidebar.html")
});</pre>

<div class="note">
<p>From Firefox 34, you can use <code>"./sidebar.html"</code> as an alias for <code>self.data.url("sidebar.html")</code>. So you can rewrite the above code like this:</p>

<pre class="brush: js">var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My sidebar',
  url: "./sidebar.html"
});</pre>
</div>

<p>Você pode incluir JavaScript e CSS no HTML como faria com qualquer página da web, por exemplo, usando tags &lt;script&gt; e &lt;link&gt; contendo o caminho relativo ao próprio arquivo HTML.</p>

<pre class="brush: html">&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;link href="stuff.css" type="text/css" rel="stylesheet"&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;script type="text/javascript" src="stuff.js"&gt;&lt;/script&gt;
  &lt;/body&gt;
&lt;/html&gt;

</pre>

<p>You can update the sidebar's content by setting the sidebar's <code>url</code> property. This will change the sidebar's content across all windows.</p>

<h3 id="Communicating_with_sidebar_scripts">Communicating with sidebar scripts</h3>

<p>You can't directly access your sidebar's content from your main add-on code, but you can send messages between your main add-on code and scripts loaded into your sidebar.</p>

<p>On the sidebar end of the conversation, sidebar scripts get a global variable <code>addon</code> that contains a <code>port</code> for sending and receiving messages.</p>

<p>On the add-on side, you need to get a <code>worker</code> object for the sidebar before you can send or receive messages. There are two events emitted by the sidebar which will give you a worker: <code>attach</code> and <code>ready</code>. Listen to <code>attach</code> if the first message in your add-on goes from the sidebar scripts to the main add-on code, and listen to <code>ready</code> if the first message goes from the main add-on code to the sidebar script.</p>

<h4 id="Using_attach">Using attach</h4>

<p>The  <code>attach</code> event is triggered whenever the DOM for a new sidebar instance is loaded and its scripts are attached. The sidebar script may not be initialized yet, so you can't reliably send messages to the sidebar script right away: however, you can start listening to messages from the script.</p>

<p>Here's a simple but complete add-on that shows how to set up communication between main.js and a script in a sidebar, in the case where the sidebar script initiates communication:</p>

<p>The HTML file includes just a script, "sidebar.js":</p>

<pre class="brush: html">&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
  &lt;body&gt;
    Content for my sidebar
    &lt;script type="text/javascript" src="sidebar.js"&gt;&lt;/script&gt;
  &lt;/body&gt;
&lt;/html&gt;

</pre>

<p>The "sidebar.js" file sends a <code>ping</code> message to main.js using <code>port.emit()</code> as soon as it loads, and adds a listener to the <code>pong</code> message.</p>

<pre class="brush: js">addon.port.emit("ping");

addon.port.on("pong", function() {
  console.log("sidebar script got the reply");
});</pre>

<p>The "main.js" file creates a sidebar object and adds a listener to its <code>attach</code> event. On attach, "main.js" starts listening to the <code>ping</code> message, and responds with a <code>pong</code>:</p>

<pre class="brush: js">var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My sidebar',
  url: require("sdk/self").data.url("sidebar.html"),
  onAttach: function (worker) {
    worker.port.on("ping", function() {
      console.log("add-on script got the message");
      worker.port.emit("pong");
    });
  }
});</pre>

<p>Try running the add-on, and showing the sidebar using the "View-&gt;Sidebar-&gt;My sidebar" menu item. You should see console output like:</p>

<pre>console.log: add-on: add-on script got the message
console.log: add-on: sidebar script got the reply
</pre>

<h4 id="Using_ready">Using ready</h4>

<p>The <code>ready</code> event is emitted when the DOM for the sidebar's content is ready. It is equivalent to the <code>DOMContentLoaded</code> event. At this point the sidebar script is initialized, so you  can send messages to the sidebar script and be confident that they will not be lost. Listen to this event if your add-on initiates the conversation.</p>

<p>Here's a simple but complete add-on that shows how to set up communication between main.js and a script in a sidebar, in the case where the main.js script initiates communication:</p>

<p>The HTML file includes just a script, "sidebar.js":</p>

<pre class="brush: html">&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
  &lt;body&gt;
    Content for my sidebar
    &lt;script type="text/javascript" src="sidebar.js"&gt;&lt;/script&gt;
  &lt;/body&gt;
&lt;/html&gt;

</pre>

<p>The "sidebar.js" file listens to the <code>ping</code> message from main.js, and responds with a <code>pong</code> message.</p>

<pre class="brush: js">addon.port.on("ping", function() {
  console.log("sidebar script got the message");
  addon.port.emit("pong");
});</pre>

<p>The "main.js" file creates a sidebar object and adds a listener to its <code>attach</code> event. On attach, "main.js" sends the <code>ping</code> message, and starts listening for the <code>pong</code>:</p>

<pre class="brush: js">var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My sidebar',
  url: require("sdk/self").data.url("sidebar.html"),
  onReady: function (worker) {
    worker.port.emit("ping");
    worker.port.on("pong", function() {
      console.log("add-on script got the reply");
    });
  }
});</pre>

<p>Try running the add-on, and showing the sidebar using the "View-&gt;Sidebar-&gt;My sidebar" menu item. You should see console output like:</p>

<pre>console.log: add-on: sidebar script got the message
console.log: add-on: add-on script got the reply
</pre>

<p> </p>

<h2 id="Globals">Globals</h2>

<h3 id="Constructors">Constructors</h3>

<h4 class="addon-sdk-api-name" id="Sidebar(options)"><code>Sidebar(options)</code></h4>

<p>Creates a sidebar.</p>

<pre class="brush: js">var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My sidebar',
  url: require("sdk/self").data.url("sidebar.html"),
  onAttach: function (worker) {
    console.log("attaching");
  },
  onShow: function () {
    console.log("showing");
  },
  onHide: function () {
    console.log("hiding");
  },
  onDetach: function () {
    console.log("detaching");
  }
});</pre>

<h5 id="Parameters">Parameters</h5>

<p><strong>options : object</strong><br>
 Required options:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col"> </th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>title</td>
   <td>string</td>
   <td>
    <p>A title for the sidebar. This will be used for the label for your sidebar in the "Sidebar" submenu in Firefox, and will be shown at the top of your sidebar when it is open.</p>
   </td>
  </tr>
  <tr>
   <td>url</td>
   <td>string</td>
   <td>
    <p>The URL of the content to load in the sidebar. This must be a local URL (typically, loaded from the "data" folder using <code>self.data.url()</code>).</p>

    <div class="note">
    <p>From Firefox 34, you can use <code>"./myFile.html"</code> as an alias for <code>self.data.url("myFile.html")</code>.</p>
    </div>
   </td>
  </tr>
 </tbody>
</table>

<p>Optional options:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col"> </th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>id</td>
   <td>string</td>
   <td>
    <p>The <code>id</code> of the sidebar. This used to identify this sidebar in its chrome window. It must be unique.</p>

    <div class="geckoVersionNote">
    <p>This option was mandatory before Firefox 28.</p>
    </div>
   </td>
  </tr>
  <tr>
   <td>onAttach</td>
   <td>function</td>
   <td>
    <p>Listener for the sidebar's <code>attach</code> event.</p>
   </td>
  </tr>
  <tr>
   <td>onDetach</td>
   <td>function</td>
   <td>
    <p>Listener for the sidebar's <code>detach</code> event.</p>
   </td>
  </tr>
  <tr>
   <td>onShow</td>
   <td>function</td>
   <td>
    <p>Listener for the sidebar's <code>show</code> event.</p>
   </td>
  </tr>
  <tr>
   <td>onHide</td>
   <td>function</td>
   <td>
    <p>Listener for the sidebar's <code>hide</code> event.</p>
   </td>
  </tr>
 </tbody>
</table>

<h2 id="Sidebar">Sidebar</h2>

<p>The Sidebar object. Once a sidebar has been created it can be shown and hidden in the active window using its <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show()"><code>show()</code></a> and <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#hide()"><code>hide()</code></a> methods. Once a sidebar is no longer needed it can be destroyed using <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#dispose()"><code>dispose()</code></a>.</p>

<h3 id="Methods">Methods</h3>

<h4 class="addon-sdk-api-name" id="dispose()"><code>dispose()</code></h4>

<p>Destroys the sidebar. Once destroyed, the sidebar can no longer be used.</p>

<h4 class="addon-sdk-api-name" id="show(window)"><code>show(window)</code></h4>

<p>Displays the sidebar.</p>

<h5 id="Parameters_2">Parameters</h5>

<p><strong>window : BrowserWindow</strong><br>
 The window in which to show the sidebar, specified as a <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow"><code>BrowserWindow</code></a>. This parameter is optional. If it is omitted, then the sidebar will be shown in the currently active window. This parameter is new in Firefox 33.</p>

<h4 class="addon-sdk-api-name" id="hide(window)"><code>hide(window)</code></h4>

<p>Hides the sidebar.</p>

<h5 id="Parameters_3">Parameters</h5>

<p><strong>window : BrowserWindow</strong><br>
 The window for which to hide the sidebar, specified as a <a href="/en-US/Add-ons/SDK/High-Level_APIs/windows#BrowserWindow"><code>BrowserWindow</code></a>. This parameter is optional. If it is omitted, then the sidebar will be hidden for the currently active window. This parameter is new in Firefox 33.</p>

<h4 class="addon-sdk-api-name" id="on(type_listener)"><code>on(type, listener)</code></h4>

<p>Registers an event listener with the sidebar.</p>

<h5 id="Parameters_4">Parameters</h5>

<p><strong>type : string</strong><br>
 The type of event to listen for.</p>

<p><strong>listener : function</strong><br>
 The listener function that handles the event.</p>

<h4 class="addon-sdk-api-name" id="once(type_listener)"><code>once(type, listener)</code></h4>

<p>Registers an event listener with the sidebar. The difference between <code>on</code> and <code>once</code> is that <code>on</code> will continue listening until it is removed, whereas <code>once</code> is removed automatically upon the first event it catches.</p>

<h5 id="Parameters_5">Parameters</h5>

<p><strong>type : string</strong><br>
 The type of event to listen for.</p>

<p><strong>listener : function</strong><br>
 The listener function that handles the event.</p>

<h4 class="addon-sdk-api-name" id="removeListener(type_listener)"><code>removeListener(type, listener)</code></h4>

<p>Unregisters/removes an event listener from the sidebar.</p>

<h5 id="Parameters_6">Parameters</h5>

<p><strong>type : string</strong><br>
 The type of event for which <code>listener</code> was registered.</p>

<p><strong>listener : function</strong><br>
 The listener function that was registered.</p>

<h3 id="Properties">Properties</h3>

<h4 class="addon-sdk-api-name" id="id"><code>id</code></h4>

<p>The id of the sidebar. This used to identify this sidebar in its chrome window. It must be unique.</p>

<h4 class="addon-sdk-api-name" id="title"><code>title</code></h4>

<p>The title of the sidebar. This will be used for the label for your sidebar in the "Sidebar" submenu in Firefox, and will be shown at the top of your sidebar when it is open.</p>

<h4 class="addon-sdk-api-name" id="url"><code>url</code></h4>

<p>The URL of the content to load in the sidebar. This must be a local URL (typically, loaded from the "data" folder using <code>self.data.url()</code>).</p>

<h3 id="Events">Events</h3>

<h4 class="addon-sdk-api-name" id="attach"><code>attach</code></h4>

<p>This event is emitted when a worker is attached to a sidebar, as a result of any of the following:</p>

<ul>
 <li>calling the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show()"><code>show()</code></a> method, when the sidebar is not shown in the currently active window</li>
 <li>changing the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#url"><code>url</code></a> property</li>
 <li>the user switching the sidebar on using the "Sidebar" submenu in Firefox, when the sidebar is not shown in the currently active window</li>
 <li>the user opening a new window from a window that has the sidebar showing</li>
</ul>

<p>It is passed a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker"><code>worker</code></a> as an argument, which defines <code>port.emit()</code> and <code>port.on()</code> methods that you can use to send messages to, and receive messages from, scripts loaded into the sidebar.</p>

<p>This is the event you should listen to if your main add-on code needs to communicate with the scripts loaded into the sidebar, and the sidebar scripts start the conversation.</p>

<p>See <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#Using_attach">Using attach</a> for an example.</p>

<h4 class="addon-sdk-api-name" id="ready"><code>ready</code></h4>

<p>This event is emitted after the DOM content for a sidebar has been loaded, as a result of any of:</p>

<ul>
 <li>calling the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show()"><code>show()</code></a> method, when the sidebar is not shown in the currently active window</li>
 <li>changing the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#url"><code>url</code></a> property</li>
 <li>the user switching the sidebar on using the "Sidebar" submenu in Firefox, when the sidebar is not shown in the currently active window</li>
 <li>the user opening a new window from a window that has the sidebar showing</li>
</ul>

<p>It is passed a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker"><code>worker</code></a> as an argument, which defines <code>port.emit()</code> and <code>port.on()</code> methods that you can use to send messages to, and receive messages from, scripts loaded into the sidebar.</p>

<p>This is the event you should listen to if your main add-on code needs to communicate with the scripts loaded into the sidebar and the main add-on code starts the conversation.</p>

<p>See <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#Using_ready">Using ready</a> for an example.</p>

<h4 class="addon-sdk-api-name" id="detach"><code>detach</code></h4>

<p>This event is emitted when a worker is detached from a sidebar, as a result of either of the following:</p>

<ul>
 <li>calling the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#hide()"><code>hide()</code></a> method, when the sidebar is being shown in the currently active window</li>
 <li>the user switching the sidebar off using the "Sidebar" submenu in Firefox, when the sidebar is being shown in the currently active window</li>
</ul>

<p>The <code>detach</code> listener receives a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/content_worker"><code>worker</code></a> object as a parameter. This object is the same as the worker passed into the corresponding <code>attach</code> event. After <code>detach</code>, this worker can no longer be used to communicate with the scripts in that sidebar instance, because it has been unloaded.</p>

<p>If you listen to <code>attach</code>, and in the listener take a reference to the worker object that's passed into it, so you can send it messages later on, then you should probably listen to <code>detach</code>, and in its handler, remove your reference to the worker.</p>

<p>Here's an add-on that adds each worker to an array in the <code>attach</code> handler, and makes sure that its references are cleaned up by listening to <code>detach</code> and removing workers as they are detached:</p>

<pre class="brush: js">var workerArray = [];

function attachWorker(worker) {
  workerArray.push(worker);
}

function detachWorker(worker) {
  var index = workerArray.indexOf(worker);
  if(index != -1) {
    workerArray.splice(index, 1);
  }
}

var sidebar = require("sdk/ui/sidebar").Sidebar({
  id: 'my-sidebar',
  title: 'My Sidebar',
  url: require("sdk/self").data.url("sidebar.html"),
  onAttach: attachWorker,
  onDetach: detachWorker
});</pre>

<h4 class="addon-sdk-api-name" id="show"><code>show</code></h4>

<p>This event is emitted when the sidebar is shown, as a result of any of the following:</p>

<ul>
 <li>calling the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#show()"><code>show()</code></a> method, when the sidebar is not shown in the currently active window</li>
 <li>changing the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#url"><code>url</code></a> property</li>
 <li>the user switching the sidebar on using the "Sidebar" submenu in Firefox, when the sidebar is not shown in the currently active window</li>
 <li>the user opening a new window from a window that has the sidebar showing</li>
</ul>

<h4 class="addon-sdk-api-name" id="hide"><code>hide</code></h4>

<p>This event is emitted when the sidebar is hidden, as a result of either of the following:</p>

<ul>
 <li>calling the sidebar's <a href="/en-US/Add-ons/SDK/Low-Level_APIs/ui_sidebar#hide()"><code>hide()</code></a> method, when the sidebar is being shown in the currently active window</li>
 <li>the user switching the sidebar off using the "Sidebar" submenu in Firefox, when the sidebar is being shown in the currently active window</li>
</ul>