Revision 1012177 of Example WebExtensions

<p>{{AddonSidebar}}</p>

<p>To help illustrate how to develop WebExtensions, we maintain a repository of simple example WebExtensions at <a href="https://github.com/mdn/webextensions-examples">https://github.com/mdn/webextensions-examples</a>. This article describes the extensions in that repository.</p>

<p>These examples work in Firefox Nightly. A recommended way to install these add-ons is to use <a href="/en-US/docs/">about:debugging</a>, which was added in Firefox 45, these will load the add-on straight from the directory so no zip or sign step is needed.</p>

<p>Extensions <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#borderify" rel="internal">borderify</a> and <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#page-to-extension-messaging" rel="internal">page-to-extension-messaging</a> work on Nightly Firefox OS as well. The others don't work since browser_action and notifications don't seem to be available there.</p>

<p>If you want to contribute to the repository, send us a pull request!</p>

<hr />
<h2 id="beastify"><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></h2>

<table class=" fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>The extension includes:</p>

    <ul>
     <li>a browser action with a popup including HTML, CSS, and JS</li>
     <li>a content script</li>
     <li>three images, each of a different beast, packaged as web accessible resources</li>
    </ul>

    <p>When the user clicks the browser action button, the popup is shown, enabling the user to choose one of three beasts.</p>

    <p>When they choose a beast, the extension injects the content script into the current page, and sends the content script a message containing the name of the chosen beast.</p>

    <p>When the content script receives this message, it replaces the current page content with an image of the chosen beast.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to write a browser action with a popup</li>
     <li>how to give the popup style and behavior using CSS and JS</li>
     <li>how to inject a content script programmatically into a tab using tabs.executeScript()</li>
     <li>how to send a message from the main extension to a content script</li>
     <li>how to use web accessible resources to enable web pages to load packaged content</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs#executeScript()">tabs.executeScript()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs#sendMessage()">tabs.sendMessage()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs#query()">tabs.query()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime#onMessage">runtime.onMessage</a></code></li>
    </ul>
   </td>
  </tr>
 </tbody>
</table>

<ul>
</ul>

<hr />
<h2 id="borderify"><a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">borderify</a></h2>

<table class=" fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>This extension just includes:</p>

    <ul>
     <li>a content script, "borderify.js", that is injected into any pages under "mozilla.org/" or any of its subdomains</li>
    </ul>

    <p>The content script draws a border around the document.body.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to inject content scripts declaratively using manifest.json</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>None.</td>
  </tr>
 </tbody>
</table>

<hr />
<h2 id="notify-link-clicks"><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks">notify-link-clicks</a></h2>

<table class=" fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>This extension includes:</p>

    <ul>
     <li>a content script, "content-script.js", that is injected into all pages</li>
     <li>a background script, "background-script.js"</li>
    </ul>

    <p>The content script listens for clicks in the page it's attached to. If a click is on a link, the content script sends the link's href to the background script.</p>

    <p>The background script listens for this message. When the background script receives the message, it displays a notification containing the href.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to inject content scripts declaratively using manifest.json</li>
     <li>how to send messages from a content script to a background script</li>
     <li>how to display system notifications using the notifications API</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications#create()">notifications.create()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime#onMessage">runtime.onMessage</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime#sendMessage()">runtime.sendMessage()</a></code></li>
    </ul>
   </td>
  </tr>
 </tbody>
</table>

<hr />
<h2 id="open-my-page-button"><a href="https://github.com/mdn/webextensions-examples/tree/master/open-my-page-button">open-my-page-button</a></h2>

<table class=" fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>This extension includes:</p>

    <ul>
     <li>a background script, "background.js"</li>
     <li>a browser action</li>
     <li>a page "my-page.html"</li>
    </ul>

    <p>All it does is: when the user clicks the button, open "my-page.html" in a new tab.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to listen for browser action clicks in a background script</li>
     <li>how to open a page packaged with your extension</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction#onClicked">browserAction.onClicked</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs#create()">tabs.create()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/extension#getURL()">extension.getURL()</a></code></li>
    </ul>
   </td>
  </tr>
 </tbody>
</table>

<hr />
<h2 id="page-to-extension-messaging"><a href="https://github.com/mdn/webextensions-examples/tree/master/page-to-extension-messaging">page-to-extension-messaging</a></h2>

<table class=" fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>This extension includes:</p>

    <ul>
     <li>a content script, which is injected only into: "<a href="https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html">https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html</a>"</li>
    </ul>

    <p>The content script listens for messages from the same window posted using <a href="/en-US/docs/Web/API/Window/postMessage">window.postMessage</a>. When the content script receives such a message, it displays an alert.</p>

    <p>To test it out, visit <a href="https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html">https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html</a> and press the buttons. One button sends a message from the page script to the content script, the other button sends a message in the other direction.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to send messages between page scripts and content scripts</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>
    <p>None.</p>
   </td>
  </tr>
 </tbody>
</table>

<hr />
<h2 id="user-agent-rewriter"><a href="https://github.com/mdn/webextensions-examples/tree/master/user-agent-rewriter">user-agent-rewriter</a></h2>

<table class="fullwidth-table standard-table">
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">What it does</th>
   <td>
    <p>This extension uses the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a> API to rewrite the browser's <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#The_User-Agent.3A_header">User Agent header</a>, but only when visiting pages under "https://useragentstring.com/".</p>

    <p>It adds a browser action. The browser action has a popup that lets the user choose one of three browsers: Firefox 41, Chrome 41, and IE 11. When the user chooses a browser, the extension then rewrites the User Agent header so the real browser identifies itself as the chosen browser on the site <a href="https://useragentstring.com/">https://useragentstring.com/</a>.</p>
   </td>
  </tr>
  <tr>
   <th scope="row">What it shows</th>
   <td>
    <ul>
     <li>how to intercept and modify HTTP requests</li>
     <li>how to write a browser action with a popup</li>
     <li>how to give the popup style and behavior using CSS and JS</li>
     <li>how to send a message from a popup script to a background script</li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">manifest.json keys</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code></li>
    </ul>
   </td>
  </tr>
  <tr>
   <th scope="row">APIs</th>
   <td>
    <ul>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/extension/getBackgroundPage">chrome.extension.getBackgroundPage()</a></code></li>
     <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest#onBeforeSendHeaders">webRequest.onBeforeSendHeaders</a></code></li>
    </ul>
   </td>
  </tr>
 </tbody>
</table>

<hr />