-<!doctype HTML> -<!-- panel.html --> - -<html> - <head></head> - <body> - <div id="forecast_summary"></div> - </body> -</html> -- -The "panel-script.js" uses [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest) -to fetch the latest forecast: - - // panel-script.js - - var url = "http://datapoint.metoffice.gov.uk/public/data/txt/wxfcs/regionalforecast/json/500?key=YOUR-API-KEY"; - - self.port.on("show", function () { - var request = new XMLHttpRequest(); - request.open("GET", url, true); - request.onload = function () { - var jsonResponse = JSON.parse(request.responseText); - var summary = getSummary(jsonResponse); - var element = document.getElementById("forecast_summary"); - element.textContent = summary; - }; - request.send(); - }); - - function getSummary(forecast) { - return forecast.RegionalFcst.FcstPeriods.Period[0].Paragraph[0].$; - } - - -Finally, we need to add the `"cross-domain-content"` key to "package.json": - -
-"permissions": {
- "cross-domain-content": ["http://datapoint.metoffice.gov.uk"]
-}
-
-
-## Content Permissions and unsafeWindow ##
-
-If you use `"cross-domain-content"`, then JavaScript values in content
-scripts will not be available from pages. Suppose your content script includes
-a line like:
-
- // content-script.js:
- unsafeWindow.myCustomAPI = function () {};
-
-If you have included the `"cross-domain-content"` key, when the page script
-tries to access `myCustomAPI` this will result in a "permission denied"
-exception.
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/index.md b/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/index.md
deleted file mode 100644
index 8dd377ff69a7..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/index.md
+++ /dev/null
@@ -1,98 +0,0 @@
-
-
-# Content Scripts #
-
-Almost all interesting add-ons will need to interact with web content or the
-browser's user interface. For example, they may need to access and modify the
-content of web pages or be notified when the user clicks a link.
-
-The SDK provides several core modules to support this:
-
-**[context-menu](modules/sdk/context-menu.html)**-Add items to the browser's context menu. - -**[panel](modules/sdk/panel.html)**
-Create a dialog that can host web content. - -**[page-worker](modules/sdk/page-worker.html)**
-Retrieve a page and access its content, without displaying it to the user. - -**[page-mod](modules/sdk/page-mod.html)**
-Execute scripts in the context of selected web pages. - -**[tabs](modules/sdk/tabs.html)**
-Manipulate the browser's tabs, including the web content displayed in the tab. - -**[widget](modules/sdk/widget.html)**
-Host an add-on's user interface, including web content. - -Firefox is moving towards a model in which it uses separate -processes to display the UI, handle web content, and execute add-ons. The main -add-on code will run in the add-on process and will not have direct access to -any web content. - -This means that an add-on which needs to interact with web content needs to be -structured in two parts: - -* the main script runs in the add-on process -* any code that needs to interact with web content is loaded into the web -content process as a separate script. These separate scripts are called -_content scripts_. - -A single add-on may use multiple content scripts, and content scripts loaded -into the same context can interact directly with each other as well as with -the web content itself. See the chapter on - -communicating with other scripts. - -The add-on script and content script can't directly access each other's state. -Instead, you can define your own events which each side can emit, and the -other side can register listeners to handle them. The interfaces are similar -to the event-handling interfaces described in the -[Working with Events](dev-guide/guides/events.html) guide. - -The diagram below shows an overview of the main components and their -relationships. The gray fill represents code written by the add-on developer. - -
-
-This might sound complicated but it doesn't need to be. The following add-on
-uses the [page-mod](modules/sdk/page-mod.html) module to replace the
-content of any web page in the `.co.uk` domain by executing a content script
-in the context of that page:
-
- var pageMod = require("sdk/page-mod");
-
- pageMod.PageMod({
- include: ["*.co.uk"],
- contentScript: 'document.body.innerHTML = ' +
- '"this page has been eaten
";' - }); - -In this example the content script is supplied directly to the page mod via -the `contentScript` option in its constructor, and does not need to be -maintained as a separate file at all. - -The next few chapters explain content scripts in detail: - -* [Loading Content Scripts](dev-guide/guides/content-scripts/loading.html): -how to attach content scripts to web pages, and how to control the point at -which they are executed -* [Accessing the DOM](dev-guide/guides/content-scripts/accessing-the-dom.html): -detail about the access content scripts get to the DOM -* [Communicating With Other Scripts](dev-guide/guides/content-scripts/communicating-with-other-scripts.html): -detail about how content scripts can communicate with "main.js", with other -content scripts, and with scripts loaded by the web page itself -* [Communicating Usingport](dev-guide/guides/content-scripts/using-port.html):
-how to communicate between your add-on and its content scripts using the
-port object
-* [Communicating using postMessage()](dev-guide/guides/content-scripts/using-postmessage.html):
-how to communicate between your add-on and its content scripts using the
-postMessage() API
-* [Cross-domain Content Scripts](dev-guide/guides/content-scripts/cross-domain.html):
-how to enable a content script to interact with content served from other domains.
-* [Example](dev-guide/guides/content-scripts/reddit-example.html):
-a simple example add-on using content scripts
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/loading.md b/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/loading.md
deleted file mode 100644
index ced006555d1f..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/loading.md
+++ /dev/null
@@ -1,79 +0,0 @@
-
-
-
-# Loading Content Scripts #
-
-The constructors for content-script-using objects such as panel and page-mod
-define a group of options for loading content scripts:
-
-- contentScript string, array - contentScriptFile string, array - contentScriptWhen string - contentScriptOptions object -- -We have already seen the `contentScript` option, which enables you to pass -in the text of the script itself as a string literal. This version of the API -avoids the need to maintain a separate file for the content script. - -The `contentScriptFile` option enables you to pass in the local file URL from -which the content script will be loaded. To supply the file -"my-content-script.js", located in the /data subdirectory under your add-on's -root directory, use a line like: - - // "data" is supplied by the "self" module - var data = require("sdk/self").data; - ... - contentScriptFile: data.url("my-content-script.js") - -Both `contentScript` and `contentScriptFile` accept an array of strings, so you -can load multiple scripts, which can also interact directly with each other in -the content process: - - // "data" is supplied by the "self" module - var data = require("sdk/self").data; - ... - contentScriptFile: - [data.url("jquery-1.4.2.min.js"), data.url("my-content-script.js")] - -Scripts specified using contentScriptFile are loaded before those specified -using contentScript. This enables you to load a JavaScript library like jQuery -by URL, then pass in a simple script inline that can use jQuery. - -
-
-
-The `contentScriptWhen` option specifies when the content script(s) should be
-loaded. It takes one of three possible values:
-
-* "start" loads the scripts immediately after the document element for the
-page is inserted into the DOM. At this point the DOM content hasn't been
-loaded yet, so the script won't be able to interact with it.
-
-* "ready" loads the scripts after the DOM for the page has been loaded: that
-is, at the point the
-[DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events)
-event fires. At this point, content scripts are able to interact with the DOM
-content, but externally-referenced stylesheets and images may not have finished
-loading.
-
-* "end" loads the scripts after all content (DOM, JS, CSS, images) for the page
-has been loaded, at the time the
-[window.onload event](https://developer.mozilla.org/en/DOM/window.onload)
-fires.
-
-The default value is "end".
-
-The `contentScriptOptions` is a json that is exposed to content scripts as a read
-only value under `self.options` property.
-
-Any kind of jsonable value (object, array, string, etc.) can be used here.
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/reddit-example.md b/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/reddit-example.md
deleted file mode 100644
index 067034ef1870..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/reddit-example.md
+++ /dev/null
@@ -1,71 +0,0 @@
-
-
-# Reddit Example #
-
-This example add-on creates a panel containing the mobile version of Reddit.
-When the user clicks on the title of a story in the panel, the add-on opens
-the linked story in a new tab in the main browser window.
-
-To accomplish this the add-on needs to run a content script in the context of
-the Reddit page which intercepts mouse clicks on each title link and fetches the
-link's target URL. The content script then needs to send the URL to the add-on
-script.
-
-This is the complete add-on script:
-
- var data = require("sdk/self").data;
-
- var reddit_panel = require("sdk/panel").Panel({
- width: 240,
- height: 320,
- contentURL: "http://www.reddit.com/.mobile?keep_extension=True",
- contentScriptFile: [data.url("jquery-1.4.4.min.js"),
- data.url("panel.js")]
- });
-
- reddit_panel.port.on("click", function(url) {
- require("sdk/tabs").open(url);
- });
-
- require("sdk/widget").Widget({
- id: "open-reddit-btn",
- label: "Reddit",
- contentURL: "http://www.reddit.com/static/favicon.ico",
- panel: reddit_panel
- });
-
-This code supplies two content scripts to the panel's constructor in the
-`contentScriptFile` option: the jQuery library and the script that intercepts
-link clicks.
-
-Finally, it registers a listener to the user-defined `click` event which in
-turn passes the URL into the `open` function of the
-[tabs](modules/sdk/tabs.html) module.
-
-This is the `panel.js` content script that intercepts link clicks:
-
- $(window).click(function (event) {
- var t = event.target;
-
- // Don't intercept the click if it isn't on a link.
- if (t.nodeName != "A")
- return;
-
- // Don't intercept the click if it was on one of the links in the header
- // or next/previous footer, since those links should load in the panel itself.
- if ($(t).parents('#header').length || $(t).parents('.nextprev').length)
- return;
-
- // Intercept the click, passing it to the addon, which will load it in a tab.
- event.stopPropagation();
- event.preventDefault();
- self.port.emit('click', t.toString());
- });
-
-This script uses jQuery to interact with the DOM of the page and the
-`self.port.emit` function to pass URLs back to the add-on script.
-
-See the `examples/reddit-panel` directory for the complete example (including
-the content script containing jQuery).
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-port.md b/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-port.md
deleted file mode 100644
index 07d3df57d96b..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-port.md
+++ /dev/null
@@ -1,292 +0,0 @@
-
-
-
-# Communicating using "port" #
-
-To enable add-on scripts and content scripts to communicate with each other,
-each end of the conversation has access to a `port` object.
-
-* to send messages from one side to the other, use `port.emit()`
-* to receive messages sent from the other side, use `port.on()`
-
-Unless your content script is extremely simple and consists only of a
-static string, don't use contentScript: if you do, you may
-have problems getting your add-on approved on AMO.
Instead, keep the script in a separate file and load it using
-contentScriptFile. This makes your code easier to maintain,
-secure, debug and review.
-
-Messages are asynchronous: that is, the sender does not wait for a reply from
-the recipient but just emits the message and continues processing.
-
-Here's a simple add-on that sends a message to a content script using `port`:
-
- var tabs = require("sdk/tabs");
-
- var alertContentScript = "self.port.on('alert', function(message) {" +
- " window.alert(message);" +
- "})";
-
- tabs.on("ready", function(tab) {
- worker = tab.attach({
- contentScript: alertContentScript
- });
- worker.port.emit("alert", "Message from the add-on");
- });
-
- tabs.open("http://www.mozilla.org");
-
-In total, the `port` object defines four functions:
-
-* [`emit()`](dev-guide/guides/content-scripts/using-port.html#port.emit()):
-emit a message.
-* [`on()`](dev-guide/guides/content-scripts/using-port.html#port.on()):
-listen to a message.
-* [`removeListener()`](dev-guide/guides/content-scripts/using-port.html#port.removeListener()):
-stop listening to a message.
-* [`once()`](dev-guide/guides/content-scripts/using-port.html#port.once()):
-listen to only the first occurrence of a message.
-
-## Accessing `port` ##
-
-### Accessing `port` in the Content Script ###
-
-Note that the global `self` object is completely
-different from the [`self` module](modules/sdk/self.html), which
-provides an API for an add-on to access its data files and ID.
-
-In the content script the `port` object is available as a property of the
-global `self` object. Thus, to emit a message from a content script:
-
- self.port.emit("myContentScriptMessage", myContentScriptMessagePayload);
-
-To receive a message from the add-on code:
-
- self.port.on("myAddonMessage", function(myAddonMessagePayload) {
- // Handle the message
- });
-
-Compare this to the technique used to receive _built-in_ messages in the
-content script. For example, to receive the `context` message in a content script
-associated with a [context menu](modules/sdk/context-menu.html)
-object, you would call the `on` function attached to the global `self` object:
-
- self.on("context", function() {
- // Handle the message
- });
-
-So the `port` property is essentially used here as a namespace for
-user-defined messages.
-
-### Accessing `port` in the Add-on Script ###
-
-In the add-on code, the channel of communication between the add-on and a
-particular content script context is encapsulated by the
-[`worker`](modules/sdk/content/worker.html#Worker) object. Thus
-the `port` object for communicating with a content script is a property of the
-corresponding `worker` object.
-
-However, the worker is not exposed to add-on code in quite the same way
-in all modules. The `panel` and `page-worker` objects integrate the
-worker API directly. So to receive messages from a content script associated
-with a panel you use `panel.port.on()`:
-
- var panel = require("sdk/panel").Panel({
- contentScript: "self.port.emit('showing', 'panel is showing');"
- });
-
- panel.port.on("showing", function(text) {
- console.log(text);
- });
-
- panel.show();
-
-Conversely, to emit user-defined messages from your add-on you can just call
-`panel.port.emit()`:
-
- var panel = require("sdk/panel").Panel({
- contentScript: "self.port.on('alert', function(text) {" +
- " console.log(text);" +
- "});"
- });
-
- panel.show();
- panel.port.emit("alert", "panel is showing");
-
-The `panel` and `page-worker` objects only host a single page at a time,
-so each distinct page object only needs a single channel of communication
-to its content scripts. But some modules, such as `page-mod`, might need to
-handle multiple pages, each with its own context in which the content scripts
-are executing, so it needs a separate channel (worker) for each page.
-
-So `page-mod` does not integrate the worker API directly: instead, each time a
-content script is attached to a page, the
-[worker](modules/sdk/content/worker.html#Worker) associated with the page is
-supplied to the page-mod in its `onAttach` function. By supplying a target for
-this function in the page-mod's constructor you can register to receive
-messages from the content script, and take a reference to the worker so as to
-emit messages to the content script.
-
- var pageModScript = "window.addEventListener('click', function(event) {" +
- " self.port.emit('click', event.target.toString());" +
- " event.stopPropagation();" +
- " event.preventDefault();" +
- "}, false);" +
- "self.port.on('warning', function(message) {" +
- "window.alert(message);" +
- "});"
-
- var pageMod = require('sdk/page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.port.on('click', function(html) {
- worker.port.emit('warning', 'Do not click this again');
- });
- }
- });
-
-In the add-on above there are two user-defined messages:
-
-* `click` is sent from the page-mod to the add-on, when the user clicks an
-element in the page
-* `warning` sends a silly string back to the page-mod
-
-## port.emit() ##
-
-The `port.emit()` function sends a message from the "main.js", or another
-add-on module, to a content script, or vice versa.
-
-It may be called with any number of parameters, but is most likely to be
-called with a name for the message and an optional payload.
-The payload can be any value that is
-serializable to JSON.
-
-From the content script to the main add-on code:
-
- var myMessagePayload = "some data";
- self.port.emit("myMessage", myMessagePayload);
-
-From the main add-on code (in this case a panel instance)
-to the content script:
-
- var myMessagePayload = "some data";
- panel.port.emit("myMessage", myMessagePayload);
-
-## port.on() ##
-
-The `port.on()` function registers a function as a listener for a specific
-named message sent from the other side using `port.emit()`.
-
-It takes two parameters: the name of the message and a function to handle it.
-
-In a content script, to listen for "myMessage" sent from the main
-add-on code:
-
- self.port.on("myMessage", function handleMyMessage(myMessagePayload) {
- // Handle the message
- });
-
-In the main add-on code (in this case a panel instance), to listen for
-"myMessage" sent from a a content script:
-
- panel.port.on("myMessage", function handleMyMessage(myMessagePayload) {
- // Handle the message
- });
-
-## port.removeListener() ##
-
-You can uses `port.on()` to listen for messages. To stop listening for a
-particular message, use `port.removeListener()`. This takes the
-same two parameters as `port.on()`: the name of the message, and the name
-of the listener function.
-
-For example, here's an add-on that creates a page-worker and a widget.
-The page-worker loads
-[http://en.wikipedia.org/wiki/Chalk](http://en.wikipedia.org/wiki/Chalk)
-alongside a content script "listener.js". The widget sends the content script
-a message called "get-first-para" when it is clicked:
-
- pageWorker = require("sdk/page-worker").Page({
- contentScriptFile: require("sdk/self").data.url("listener.js"),
- contentURL: "http://en.wikipedia.org/wiki/Chalk"
- });
-
- require("sdk/widget").Widget({
- id: "mozilla-icon",
- label: "My Mozilla Widget",
- contentURL: "http://www.mozilla.org/favicon.ico",
- onClick: function() {
- console.log("sending 'get-first-para'");
- pageWorker.port.emit("get-first-para");
- }
- });
-
-The content script "listener.js" listens for "get-first-para". When it
-receives this message, the script logs the first paragraph of the document
-and then calls `removeListener()` to stop listening.
-
- function getFirstParagraph() {
- var paras = document.getElementsByTagName('p');
- console.log(paras[0].textContent);
- self.port.removeListener("get-first-para", getFirstParagraph);
- }
-
- self.port.on("get-first-para", getFirstParagraph);
-
-The result is that the paragraph is only logged the first time the widget
-is clicked.
-
-Due to [bug 816272](https://bugzilla.mozilla.org/show_bug.cgi?id=816272)
-the [`page-mod`](modules/sdk/page-mod.html)'s `removeListener()` function
-does not prevent the listener from receiving messages that are already queued.
-This means that if "main.js" sends the message twice in successive lines, and
-the listener stops listening as soon as it receives the first message, then
-the listener will still receive the second message.
-
-## port.once() ##
-
-Often you'll want to receive a message just once, then stop listening. The
-`port` object offers a shortcut to do this: the `once()` method.
-
-This example rewrites the "listener.js" content script in the
-[`port.removeListener()` example](dev-guide/guides/content-scripts/using-port.html#port.removeListener())
-so that it uses `once()`:
-
- function getFirstParagraph() {
- var paras = document.getElementsByTagName('p');
- console.log(paras[0].textContent);
- }
-
- self.port.once("get-first-para", getFirstParagraph);
-
-## JSON-Serializable Values ##
-
-The payload for an message can be any JSON-serializable value. When messages
-are sent their payloads are automatically serialized, and when messages are
-received their payloads are automatically deserialized, so you don't need to
-worry about serialization.
-
-However, you _do_ have to ensure that the payload can be serialized to JSON.
-This means that it needs to be a string, number, boolean, null, array of
-JSON-serializable values, or an object whose property values are themselves
-JSON-serializable. This means you can't send functions, and if the object
-contains methods they won't be encoded.
-
-For example, to include an array of strings in the payload:
-
- var pageModScript = "self.port.emit('loaded'," +
- " [" +
- " document.location.toString()," +
- " document.title" +
- " ]" +
- ");"
-
- var pageMod = require('page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.port.on('loaded', function(pageInfo) {
- console.log(pageInfo[0]);
- console.log(pageInfo[1]);
- });
- }
- });
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-postmessage.md b/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-postmessage.md
deleted file mode 100644
index c15968403b99..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-postmessage.md
+++ /dev/null
@@ -1,140 +0,0 @@
-
-
-# Communicating using "postMessage()" #
-
-As an alternative to user-defined events content modules support the built-in
-`message` event. In most cases user-defined events are preferable to message
-events. However, the `context-menu` module does not support user-defined
-events, so to send messages from a content script to the add-on via a context
-menu object, you must use message events.
-
-## Handling Message Events in the Content Script ##
-
-To send a message from a content script, you use the `postMessage` function of
-the global `self` object:
-
- self.postMessage(contentScriptMessage);
-
-This takes a single parameter, the message payload, which may be any
-JSON-serializable value.
-
-To receive a message from the add-on script, use `self`'s `on` function:
-
- self.on("message", function(addonMessage) {
- // Handle the message
- });
-
-Like all event-registration functions, this takes two parameters: the name
-of the event, and the handler function. The handler function is passed the
-message payload.
-
-## Handling Message Events in the Add-on Script ##
-
-To send a message to a content script, use the worker's `postMessage`
-function. Again, `panel` and `page` integrate `worker` directly:
-
- // Post a message to the panel's content scripts
- panel.postMessage(addonMessage);
-
-However, for `page-mod` objects you need to listen to the `onAttach` event
-and use the [worker](modules/sdk/content/worker.html#Worker) supplied to that:
-
- var pageMod = require('sdk/page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.postMessage(addonMessage);
- }
- });
-
-To receive messages from a content script, use the worker's `on` function.
-To simplify this most content modules provide an `onMessage` property as an
-argument to the constructor:
-
- panel = require("sdk/panel").Panel({
- onMessage: function(contentScriptMessage) {
- // Handle message from the content script
- }
- });
-
-## Message Events Versus User-Defined Events ##
-
-You can use message events as an alternative to user-defined events:
-
- var pageModScript = "window.addEventListener('mouseover', function(event) {" +
- " self.postMessage(event.target.toString());" +
- "}, false);";
-
- var pageMod = require('sdk/page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.on('message', function(message) {
- console.log('mouseover: ' + message);
- });
- }
- });
-
-The reason to prefer user-defined events is that as soon as you need to send
-more than one type of message, then both sending and receiving messages gets
-more complex.
-
-Suppose the content script wants to send `mouseout` events as well as
-`mouseover`. Now we have to embed the event type in the message payload, and
-implement a switch function in the receiver to dispatch the message:
-
- var pageModScript = "window.addEventListener('mouseover', function(event) {" +
- " self.postMessage({" +
- " kind: 'mouseover'," +
- " element: event.target.toString()" +
- " });" +
- "}, false);" +
- "window.addEventListener('mouseout', function(event) {" +
- " self.postMessage({" +
- " kind: 'mouseout'," +
- " element: event.target.toString()" +
- " });" +
- " }, false);"
-
-
- var pageMod = require('sdk/page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.on('message', function(message) {
- switch(message.kind) {
- case 'mouseover':
- console.log('mouseover: ' + message.element);
- break;
- case 'mouseout':
- console.log('mouseout: ' + message.element);
- break;
- }
- });
- }
- });
-
-Implementing the same add-on with user-defined events is shorter and more
-readable:
-
- var pageModScript = "window.addEventListener('mouseover', function(event) {" +
- " self.port.emit('mouseover', event.target.toString());" +
- "}, false);" +
- "window.addEventListener('mouseout', function(event) {" +
- " self.port.emit('mouseout', event.target.toString());" +
- "}, false);";
-
- var pageMod = require('sdk/page-mod').PageMod({
- include: ['*'],
- contentScript: pageModScript,
- onAttach: function(worker) {
- worker.port.on('mouseover', function(message) {
- console.log('mouseover :' + message);
- });
- worker.port.on('mouseout', function(message) {
- console.log('mouseout :' + message);
- });
- }
- });
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/classes-and-inheritance.md b/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/classes-and-inheritance.md
deleted file mode 100644
index f4a8f4776e6a..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/classes-and-inheritance.md
+++ /dev/null
@@ -1,272 +0,0 @@
-
-
-#Classes and Inheritance
-A class is a blueprint from which individual objects are created. These
-individual objects are the instances of the class. Each class defines one or
-more members, which are initialized to a given value when the class is
-instantiated. Data members are properties that allow each instance to have
-their own state, whereas member functions are properties that allow instances to
-have behavior. Inheritance allows classes to inherit state and behavior from an
-existing classes, known as the base class. Unlike languages like C++ and Java,
-JavaScript does not have native support for classical inheritance. Instead, it
-uses something called prototypal inheritance. As it turns out, it is possible to
-emulate classical inheritance using prototypal inheritance, but not without
-writing a significant amount of boilerplate code.
-
-Classes in JavaScript are defined using constructor functions. Each constructor
-function has an associated object, known as its prototype, which is shared
-between all instances of that class. We will show how to define classes using
-constructors, and how to use prototypes to efficiently define member functions
-on each instance. Classical inheritance can be implemented in JavaScript using
-constructors and prototypes. We will show how to make inheritance work correctly
-with respect to constructors, prototypes, and the instanceof operator, and how
-to override methods in subclasses. The SDK uses a special constructor internally,
-known as `Class`, to create constructors that behave properly with respect to
-inheritance. The last section shows how to work with the `Class` constructor. It
-is possible to read this section on its own. However, to fully appreciate how
-`Class` works, and the problem it is supposed to solve, it is recommended that
-you read the entire article.
-
-##Constructors
-In JavaScript, a class is defined by defining a constructor function for that
-class. To illustrate this, let's define a simple constructor for a class
-`Shape`:
-
- function Shape(x, y) {
- this.x = x;
- this.y = y;
- }
-
-We can now use this constructor to create instances of `Shape`:
-
- let shape = new Shape(2, 3);
- shape instanceof Shape; // => true
- shape.x; // => 2
- shape.y; // => 3
-
-The keyword new tells JavaScript that we are performing a constructor call.
-Constructor calls differ from ordinary function calls in that JavaScript
-automatically creates a new object and binds it to the keyword this for the
-duration of the call. Moreover, if the constructor does not return a value, the
-result of the call defaults to the value of this. Constructors are just ordinary
-functions, however, so it is perfectly legal to perform ordinary function calls
-on them. In fact, some people (including the Add-on SDK team) prefer to use
-constructors this way. However, since the value of this is undefined for
-ordinary function calls, we need to add some boilerplate code to convert them to
-constructor calls:
-
- function Shape(x, y) {
- if (!this)
- return new Shape(x, y);
- this.x = x;
- this.y = y;
- }
-
-##Prototypes
-Every object has an implicit property, known as its prototype. When JavaScript
-looks for a property, it first looks for it in the object itself. If it cannot
-find the property there, it looks for it in the object's prototype. If the
-property is found on the prototype, the lookup succeeds, and JavaScript pretends
-that it found the property on the original object. Every function has an
-explicit property, known as `prototype`. When a function is used in a
-constructor call, JavaScript makes the value of this property the prototype of
-the newly created object:
-
- let shape = Shape(2, 3);
- Object.getPrototypeOf(shape) == Shape.prototype; // => true
-
-All instances of a class have the same prototype. This makes the prototype the
-perfect place to define properties that are shared between instances of the
-class. To illustrate this, let's add a member function to the class `Shape`:
-
- Shape.prototype.draw = function () {
- throw Error("not yet implemented");
- }
- let shape = Shape(2, 3);
- Shape.draw(); // => Error: not yet implemented
-
-##Inheritance and Constructors
-Suppose we want to create a new class, `Circle`, and inherit it from `Shape`.
-Since every `Circle` is also a `Shape`, the constructor for `Circle` must be
-called every time we call the constructor for `Shape`. Since JavaScript does
-not have native support for inheritance, it doesn't do this automatically.
-Instead, we need to call the constructor for `Shape` explicitly. The resulting
-constructor looks as follows:
-
- function Circle(x, y, radius) {
- if (!this)
- return new Circle(x, y, radius);
- Shape.call(this, x, y);
- this.radius = radius;
- }
-
-Note that the constructor for `Shape` is called as an ordinary function, and
-reuses the object created for the constructor call to `Circle`. Had we used a
-constructor call instead, the constructor for `Shape` would have been applied to
-a different object than the constructor for `Circle`. We can now use the above
-constructor to create instances of the class `Circle`:
-
- let circle = Circle(2, 3, 5);
- circle instanceof Circle; // => true
- circle.x; // => 2
- circle.y; // => 3
- circle.radius; // => 5
-
-##Inheritance and Prototypes
-There is a problem with the definition of `Circle` in the previous section that
-we have glossed over thus far. Consider the following:
-
- let circle = Circle(2, 3, 5);
- circle.draw(); // => TypeError: circle.draw is not a function
-
-This is not quite right. The method `draw` is defined on instances of `Shape`,
-so we definitely want it to be defined on instances of `Circle`. The problem is
-that `draw` is defined on the prototype of `Shape`, but not on the prototype of
-`Circle`. We could of course copy every property from the prototype of `Shape`
-over to the prototype of `Circle`, but this is needlessly inefficient. Instead,
-we use a clever trick, based on the observation that prototypes are ordinary
-objects. Since prototypes are objects, they have a prototype as well. We can
-thus override the prototype of `Circle` with an object which prototype is the
-prototype of `Shape`.
-
- Circle.prototype = Object.create(Shape.prototype);
-
-Now when JavaScript looks for the method draw on an instance of Circle, it first
-looks for it on the object itself. When it cannot find the property there, it
-looks for it on the prototype of `Circle`. When it cannot find the property
-there either, it looks for it on `Shape`, at which point the lookup succeeds.
-The resulting behavior is what we were aiming for.
-
-##Inheritance and Instanceof
-The single line of code we added in the previous section solved the problem with
-prototypes, but introduced a new problem with the **instanceof** operator.
-Consider the following:
-
- let circle = Circle(2, 3, 5);
- circle instanceof Shape; // => false
-
-Since instances of `Circle` inherit from `Shape`, we definitely want the result
-of this expression to be true. To understand why it is not, we need to
-understand how **instanceof** works. Every prototype has a `constructor`
-property, which is a reference to the constructor for objects with this
-prototype. In other words:
-
- Circle.prototype.constructor == Circle // => true
-
-The **instanceof** operator compares the `constructor` property of the prototype
-of the left hand side with that of the right hand side, and returns true if they
-are equal. Otherwise, it repeats the comparison for the prototype of the right
-hand side, and so on, until either it returns **true**, or the prototype becomes
-**null**, in which case it returns **false**. The problem is that when we
-overrode the prototype of `Circle` with an object whose prototype is the
-prototype of `Shape`, we didn't correctly set its `constructor` property. This
-property is set automatically for the `prototype` property of a constructor, but
-not for objects created with `Object.create`. The `constructor` property is
-supposed to be non-configurable, non-enumberable, and non-writable, so the
-correct way to define it is as follows:
-
- Circle.prototype = Object.create(Shape.prototype, {
- constructor: {
- value: Circle
- }
- });
-
-##Overriding Methods
-As a final example, we show how to override the stub implementation of the
-method `draw` in `Shape` with a more specialized one in `Circle`. Recall that
-JavaScript returns the first property it finds when walking the prototype chain
-of an object from the bottom up. Consequently, overriding a method is as simple
-as providing a new definition on the prototype of the subclass:
-
- Circle.prototype.draw = function (ctx) {
- ctx.beginPath();
- ctx.arc(this.x, this.y, this.radius,
- 0, 2 * Math.PI, false);
- ctx.fill();
- };
-
-With this definition in place, we get:
-
- let shape = Shape(2, 3);
- shape.draw(); // Error: not yet implemented
- let circle = Circle(2, 3, 5);
- circle.draw(); // TypeError: ctx is not defined
-
-which is the behavior we were aiming for.
-
-##Classes in the Add-on SDK
-We have shown how to emulate classical inheritance in JavaScript using
-constructors and prototypes. However, as we have seen, this takes a significant
-amount of boilerplate code. The Add-on SDK team consists of highly trained
-professionals, but they are also lazy: that is why the SDK contains a helper
-function that handles this boilerplate code for us. It is defined in the module
-“core/heritage”:
-
- const { Class } = require('sdk/core/heritage');
-
-The function `Class` is a meta-constructor: it creates constructors that behave
-properly with respect to inheritance. It takes a single argument, which is an
-object which properties will be defined on the prototype of the resulting
-constructor. The semantics of `Class` are based on what we've learned earlier.
-For instance, to define a constructor for a class `Shape` in terms of `Class`,
-we can write:
-
- let Shape = Class({
- initialize: function (x, y) {
- this.x = x;
- this.y = y;
- },
- draw: function () {
- throw new Error("not yet implemented");
- }
- });
-
-The property `initialize` is special. When it is present, the call to the
-constructor is forwarded to it, as are any arguments passed to it (including the
-this object). In effect, initialize specifies the body of the constructor. Note
-that the constructors created with `Class` automatically check whether they are
-called as constructors, so an explicit check is no longer necessary.
-
-Another special property is `extends`. It specifies the base class from which
-this class inherits, if any. `Class` uses this information to automatically set
-up the prototype chain of the constructor. If the extends property is omitted,
-`Class` itself is used as the base class:
-
- var shape = new Shape(2, 3);
- shape instanceof Shape; // => true
- shape instanceof Class; // => true
-
-To illustrate the use of the `extends` property, let's redefine the constructor
-for the class `Circle` in terms of `Class`:
-
- var Circle = Class({
- extends: Shape,
- initialize: function(x, y, radius) {
- Shape.prototype.initialize.call(this, x, y);
- this.radius = radius;
- },
- draw: function () {
- context.beginPath();
- context.arc(this.x, this.y, this.radius,
- 0, 2 * Math.PI, false);
- context.fill();
- }
- });
-
-Unlike the definition of `Circle` in the previous section, we no longer have to
-override its prototype, or set its `constructor` property. This is all handled
-automatically. On the other hand, the call to the constructor for `Shape` still
-has to be made explicitly. This is done by forwarding to the initialize method
-of the prototype of the base class. Note that this is always safe, even if there
-is no `initialize` method defined on the base class: in that case the call is
-forwarded to a stub implementation defined on `Class` itself.
-
-The last special property we will look into is `implements`. It specifies a list
-of objects, which properties are to be copied to the prototype of the
-constructor. Note that only properties defined on the object itself are copied:
-properties defined on one of its prototypes are not. This allows objects to
-inherit from more than one class. It is not true multiple inheritance, however:
-no constructors are called for objects inherited via `implements`, and
-**instanceof** only works correctly for classes inherited via `extends`.
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/content-processes.md b/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/content-processes.md
deleted file mode 100644
index f77d921a85fe..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/content-processes.md
+++ /dev/null
@@ -1,149 +0,0 @@
-
-
-#Content Processes
-A content process was supposed to run all the code associated with a single tab.
-Conversely, an add-on process was supposed to run all the code associated with a
-single add-on. Neither content or add-on proceses were ever actually
-implemented, but by the time they were cancelled, the SDK was already designed
-with them in mind. To understand this article, it's probably best to read it as
-if content and add-on processes actually exist.
-
-To communicate between add-on and content processes, the SDK uses something
-called content scripts. These are explained in the first section. Content
-scripts communicate with add-on code using something called event emitters.
-These are explained in the next section. Content workers combine these ideas,
-allowing you to inject a content script into a content process, and
-automatically set up a communication channel between them. These are explained
-in the third section.
-
-In the next section, we will look at how content scripts interact with the DOM
-in a content process. There are several caveats here, all of them related to
-security, that might cause things to not behave in the way you might expect.
-
-The final section explains why the SDK still uses the notion of content scripts
-and message passing, even though the multiprocess model for which they were
-designed never materialized. This, too, is primarily related to security.
-
-##Content Scripts
-When the SDK was first designed, Firefox was being refactored towards a
-multiprocess model. In this model, the UI would be rendered in one process
-(called the chrome process), whereas each tab and each add-on would run in their
-own dedicated process (called content and add-on processes, respectively). The
-project behind this refactor was known as Electrolysis, or E10s. Although E10s
-has now been suspended, the SDK was designed with this multiprocess model in
-mind. Afterwards, it was decided to keep the design the way it is: even though
-its no longer necessary, it turns out that from a security point of view there
-are several important advantages to thinking about content and add-on code as
-living in different processes.
-
-Many add-ons have to interact with content. The problem with the multiprocess
-model is that add-ons and content are now in different processes, and scripts in
-one process cannot interact directly with scripts in another. We can, however,
-pass JSON messages between scripts in different processes. The solution we've
-come up with is to introduce the notion of content scripts. A content script is
-a script that is injected into a content process by the main script running in
-the add-on process. Content scripts differ from scripts that are loaded by the
-page itself in that they are provided with a messaging API that can be used to
-send messages back to the add-on script.
-
-##Event Emitters
-The messaging API we use to send JSON messages between scripts in different
-processes is based on the use of event emitters. An event emitter maintains a
-list of callbacks (or listeners) for one or more named events. Each event
-emitter has several methods: the method on is used to add a listener for an
-event. Conversely, the method removeListener is used to remove a listener for an
-event. The method once is a helper function which adds a listener for an event,
-and automatically removes it the first time it is called.
-
-Each event emitter has two associated emit functions. One emit function is
-associated with the event emitter itself. When this function is called with a
-given event name, it calls all the listeners currently associated with that
-event. The other emit function is associated with another event emitter: it was
-passed as an argument to the constructor of this event emitter, and made into a
-method. Calling this method causes an event to be emitted on the other event
-emitter.
-
-Suppose we have two event emitters in different processes, and we want them to
-be able to emit events to each other. In this case, we would replace the emit
-function passed to the constructor of each emitter with a function that sends a
-message to the other process. We can then hook up a listener to be called when
-this message arrives at the other process, which in turn calls the emit function
-on the other event emitter. The combination of this function and the
-corresponding listener is referred to as a pipe.
-
-##Content Workers
-A content worker is an object that is used to inject content scripts into a
-content process, and to provide a pipe between each content script and the main
-add-on script. The idea is to use a single content worker for each content
-process. The constructor for the content worker takes an object containing one
-or more named options. Among other things, this allows us to specify one or more
-content scripts to be loaded.
-
-When a content script is first loaded, the content worker automatically imports
-a messaging API that allows the it to emit messages over a pipe. On the add-on
-side, this pipe is exposed via the the port property on the worker. In addition
-to the port property, workers also support the web worker API, which allows
-scripts to send messages to each other using the postMessage function. This
-function uses the same pipe internally, and causes a 'message' event to be
-emitted on the other side.
-
-As explained earlier, Firefox doesn't yet use separate processes for tabs or
-add-ons, so instead, each content script is loaded in a sandbox. Sandboxes were
-explained [this article]("dev-guide/guides/contributors-guide/modules.html").
-
-##Accessing the DOM
-The global for the content sandbox has the window object as its prototype. This
-allows the content script to access any property on the window object, even
-though that object lives outside the sandbox. Recall that the window object
-inside the sandbox is actually a wrapper to the real object. A potential
-problem with the content script having access to the window object is that a
-malicious page could override methods on the window object that it knows are
-being used by the add-on, in order to trick the add-on into doing something it
-does not expect. Similarly, if the content script defines any values on the
-window object, a malicious page could potentially steal that information.
-
-To avoid problems like this, content scripts should always see the built-in
-properties of the window object, even when they are overridden by another
-script. Conversely, other scripts should not see any properties added to the
-window object by the content script. This is where xray wrappers come in. Xray
-wrappers automatically wrap native objects like the window object, and only
-exposes their native properties, even if they have been overridden on the
-wrapped object. Conversely, any properties defined on the wrapper are not
-visible from the wrapped object. This avoids both problems we mentioned earlier.
-
-The fact that you can't override the properties of the window object via a
-content script is sometimes inconvenient, so it is possible to circumvent this:
-by defining the property on window.wrappedObject, the property is defined on the
-underlying object, rather than the wrapper itself. This feature should only be
-used when you really need it, however.
-
-##A few Notes on Security
-As we stated earlier, the SDK was designed with multiprocess support in mind,
-despite the fact that work on implementing this in Firefox has currently been
-suspended. Since both add-on modules and content scripts are currently loaded in
-sandboxes rather than separate processes, and sandboxes can communicate with
-each other directly (using imports/exports), you might be wondering why we have
-to go through all the trouble of passing messages between add-on and content
-scripts. The reason for this extra complexity is that the code for add-on
-modules and content scripts has different privileges. Every add-on module can
-get chrome privileges simply by asking for them, whereas content scripts have
-the same privileges as the page it is running on.
-
-When two sandboxes have the same privileges, a wrapper in one sandbox provides
-transparent access to an object in the other sandbox. When the two sandboxes
-have different privileges, things become more complicated, however. Code with
-content privileges should not be able to acces code with chrome privileges, so
-we use specialized wrappers, called security wrappers, to limit access to the
-object in the other sandbox. The xray wrappers we saw earlier are an example of
-such a security wrapper. Security wrappers are created automatically, by the
-underlying host application.
-
-A full discussion of the different kinds of security wrappers and how they work
-is out of scope for this document, but the main point is this: security wrappers
-are very complex, and very error-prone. They are subject to change, in order to
-fix some security leak that recently popped up. As a result, code that worked
-just fine last week suddenly does not work the way you expect. By only passing
-messages between add-on modules and content scripts, these problems can be
-avoided, making your add-on both easier to debug and to maintain.
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/getting-started.md b/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/getting-started.md
deleted file mode 100644
index bdaa61a57cae..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/contributors-guide/getting-started.md
+++ /dev/null
@@ -1,318 +0,0 @@
-
-
-#Getting Started
-The contribution process consists of a number of steps. First, you need to get
-a copy of the code. Next, you need to open a bug for the bug or feature you want
-to work on, and assign it to yourself. Alternatively, you can take an existing
-bug to work on. Once you've taken a bug, you can start writing a patch. Once
-your patch is complete, you've made sure it doesn't break any tests, and you've
-gotten a positive review for it, the last step is to request for your patch to
-be merged with the main codebase.
-
-Although these individual steps are all obvious, there are quite some details
-involved. The rest of this article will cover each individual step of the
-contribution process in more detail.
-
-##Getting the Code
-The Add-on SDK code is hosted on GitHub. GitHub is a web-based hosting service
-for software projects that is based on Git, a distributed version control
-system. Both GitHub and Git are an integral part of our workflow. If you haven't
-familiarized yourself with Git before, I strongly suggest you do so now. You're
-free to ignore that suggestion if you want, but it's going to hurt you later on
-(don't come crying to me if you end up accidentally detaching your head, for
-instance). A full explanation of how to use Git is out of scope for this
-document, but a very good one
-[can be found online here](http://git-scm.com/book). Reading at least sections
-1-3 from that book should be enough to get you started.
-
-If you're already familiar with Git, or if you decided to ignore my advice and
-jump right in, the following steps will get you a local copy of the Add-on SDK
-code on your machine:
-
-1. Fork the SDK repository to your GitHub account
-2. Clone the forked repository to your machine
-
-A fork is similar to a clone in that it creates a complete copy of a repository,
-including the history of every file. The difference is that a fork copies the
-repository to your GitHub account, whereas a clone copies it to your machine. To
-create a fork of the SDK repository, you need a GitHub account. If you don't
-already have one, you can [create one here](https://github.com/) (don't worry:
-it's free!). Once you got yourself an account, go to
-[the Add-on SDK repository](https://github.com/mozilla/addon-sdk), and click the
-fork button in the upper-right corner. This will start the forking process.
-This could take anywhere between a couple of seconds and a couple of minutes.
-
-Once the forking process is complete, the forked repository will be available at
-https://github.com/\You can review this patch at
-info: tabevents: Listener 1 -info: tabevents: Listener 2 -info: tabevents: Listener 2 -- -Listeners will be removed automatically when the add-on is unloaded. - diff --git a/addon-sdk/source/doc/dev-guide-source/guides/firefox-compatibility.md b/addon-sdk/source/doc/dev-guide-source/guides/firefox-compatibility.md deleted file mode 100644 index f91e832d2f2e..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/guides/firefox-compatibility.md +++ /dev/null @@ -1,103 +0,0 @@ - - -# Firefox Compatibility # - -One of the promises the SDK makes is to maintain compatibility for its -["supported" or "high-level" APIs](modules/high-level-modules.html): -meaning that code written against them will not need to change as new -versions of Firefox are released. - -This ties the SDK release cycle into the Firefox release cycle because -the SDK must absorb any changes made to Firefox APIs. The SDK -and Firefox both release every 6 weeks, and the releases are precisely -staggered: so the SDK releases three weeks before Firefox. Each SDK -release is tested against, and marked as compatible with, two -versions of Firefox: - -* the currently shipping Firefox version at the time the SDK is released -* the Beta Firefox version at the time the SDK is released - which, -because SDK and Firefox releases are staggered, will become the -currently shipping Firefox three week later - -Add-ons built using a particular version of the SDK are marked -as being compatible with those two versions of Firefox, meaning -that in the -[`targetApplication` field of the add-on's install.rdf](https://developer.mozilla.org/en/Install.rdf#targetApplication): - -* the `minVersion` is set to the currently shipping Firefox -* the `maxVersion` is set to the current Firefox Beta - -See the -[SDK Release Schedule](https://wiki.mozilla.org/Jetpack/SDK_2012_Release_Schedule) -for the list of all SDK releases scheduled for 2012, along with the Firefox -versions they are compatible with. - -## "Compatible By Default" ## - -There are exceptions to the "compatible by default" rule: -add-ons with binary XPCOM components, add-ons that have their compatibility -set to less than Firefox 4, and add-ons that are repeatedly reported as -incompatible, which are added to a compatibility override list. - - -From Firefox 10 onwards, Firefox treats add-ons as -"compatible by default": that is, even if the Firefox installing the -add-on is not inside the range defined in `targetApplication`, -Firefox will happily install it. - -For example, although an add-on developed using version 1.6 of the SDK will be -marked as compatible with only versions 11 and 12 of Firefox, users of -Firefox 10 will still be able to install it. - -But before version 10, Firefox assumed that add-ons were incompatible unless -they were marked as compatible in the `targetApplication` field: so an add-on -developed using SDK 1.6 will not install on Firefox 9. - -## Changing minVersion and maxVersion Values ## - -The `minVersion` and `maxVersion` values that are written into add-ons -generated with the SDK are taken from the template file found at: - -
-app-extension/install.rdf -- -If you need to create add-ons which are compatible with a wider range of -Firefox releases, you can edit this file to change the -`minVersion...maxVersion` range. - -Obviously, you should be careful to test the resulting add-on on the extra -versions of Firefox you are including, because the version of the SDK you -are using will not have been tested against them. - -## Repacking Add-ons ## - -Suppose you create an add-on using version 1.6 of the SDK, and upload it to -[https://addons.mozilla.org/](https://addons.mozilla.org/). It's compatible -with versions 11 and 12 of Firefox, and indicates that in its -`minVersion...maxVersion` range. - -Now Firefox 13 is released. Suppose Firefox 13 does not change any of the -APIs used by version 1.6 of the SDK. In this case the add-on will still -work with Firefox 13. - -But if Firefox 13 makes some incompatible changes, then the add-on will -no longer work. In this case, we'll notify developers, who will need to: - -* download and install a new version of the SDK -* rebuild their add-on using this version of the SDK -* update their XPI on [https://addons.mozilla.org/](https://addons.mozilla.org/) -with the new version. - -If you created the add-on using the [Add-on Builder](https://builder.addons.mozilla.org/) -rather than locally using the SDK, then it will be repacked automatically -and you don't have to do this. - -### Future Plans ### - -The reason add-ons need to be repacked when Firefox changes is that the -SDK modules used by an add-on are packaged as part of the add-on, rather -than part of Firefox. In the future we plan to start shipping SDK modules -in Firefox, and repacking will not be needed any more. diff --git a/addon-sdk/source/doc/dev-guide-source/guides/index.md b/addon-sdk/source/doc/dev-guide-source/guides/index.md deleted file mode 100644 index e288dadfb092..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/guides/index.md +++ /dev/null @@ -1,249 +0,0 @@ - - -# Guides # - -This page lists more theoretical in-depth articles about the SDK. - -
- -
Contributor's Guide
- -
- Getting Started- Learn how to contribute to the SDK: getting the code, opening/taking a - bug, filing a patch, getting reviews, and getting help. - |
-
-
- Private Properties- Learn how private properties can be implemented in JavaScript using - prefixes, closures, and WeakMaps, and how the SDK supports private - properties by using namespaces (which are a generalization of WeakMaps). - |
-
-
- Modules- Learn about the module system used by the SDK (which is based on the - CommonJS specification), how sandboxes and compartments can be used to - improve security, and about the built-in SDK module loader, known as - Cuddlefish. - |
-
-
- Content Processes- The SDK was designed to work in an environment where the code to - manipulate web content runs in a different process from the main add-on - code. This article highlights the main features of that design. - |
-
-
- Classes and Inheritance- Learn how classes and inheritance can be implemented in JavaScript, using - constructors and prototypes, and about the helper functions provided by - the SDK to simplify this. - |
-
- - | - -
SDK Infrastructure
- -
- Module structure of the SDK- The SDK, and add-ons built using it, are of composed from reusable JavaScript modules. This - explains what these modules are, how to load modules, and how the SDK's module - tree is structured. - |
-
-
- Program ID- The Program ID is a unique identifier for your add-on. This guide - explains how it's created, what it's used for and how to define your - own. - |
-
-
| - | - -
- Firefox compatibility- Working out which Firefox releases a given SDK release is - compatible with, and dealing with compatibility problems. - |
-
-
- SDK API lifecycle- Definition of the lifecycle for the SDK's APIs, including the stability - ratings for APIs. - |
-
- - | - -
- -
SDK Idioms
- -
- Working With Events- Write event-driven code using the the SDK's event emitting framework. - |
-
-
- Two Types of Scripts- This article explains the differences between the APIs - available to your main add-on code and those available - to content scripts. - |
-
-
- -
Content Scripts
- -
- Introducing content scripts- An overview of content scripts. - |
-
-
- Loading content scripts- Load content scripts into web pages, specified either as strings - or in separate files, and how to control the point at which they are - executed. - |
-
-
- Accessing the DOM- Detail about the access content scripts get to the DOM. - |
-
-
- Communicating with other scripts- Detail about how content scripts can communicate with "main.js", with other - content scripts, and with scripts loaded by the web page itself. - |
-
-
- Using "port"- Communicating between a content script and the rest of your add-on - using theport object.
- |
-
-
-
- Using "postMessage()"- Communicating between a content script and the rest of your add-on - using thepostMessage() API, and a comparison between
- this technique and the port object.
- |
-
-
- Cross-domain content scripts- How to enable content scripts to interact with content served from different domains. - |
-
-
-
- Reddit example- A simple add-on which uses content scripts. - |
-
-
- -
XUL Migration
- -
- XUL Migration Guide- Techniques to help port a XUL add-on to the SDK. - |
-
-
- XUL versus the SDK- A comparison of the strengths and weaknesses of the SDK, - compared to traditional XUL-based add-ons. - |
-
-
- Porting Example- A walkthrough of porting a relatively simple XUL-based - add-on to the SDK. - |
-
- - | - -
-
-The add-on is Paul Bakaus's
-[Library Detector](https://addons.mozilla.org/en-US/firefox/addon/library-detector/).
-
-The Library Detector tells you which JavaScript frameworks the current
-web page is using. It does this by checking whether particular objects
-that those libraries add to the global window object are defined.
-For example, if `window.jQuery` is defined, then the page has loaded
-[jQuery](http://jquery.com/).
-
-For each library that it finds, the library detector adds an icon
-representing that library to the status bar. It adds a tooltip to each
-icon, which contains the library name and version.
-
-You can browse and run the ported version in the SDK's `examples` directory.
-
-### How the Library Detector Works ###
-
-All the work is done inside a single file,
-[`librarydetector.xul`](http://code.google.com/p/librarydetector/source/browse/trunk/chrome/content/librarydetector.xul)
-This contains:
-
--
-
- a XUL overlay -
- a script -
Version: " + library.version); - }); - widgetContent += htmlContentPostamble; - return widgetContent; - } - - function updateWidgetView(tab) { - var widgetView = widget.getView(tab.window); - if (!tab.libraries) { - tab.libraries = []; - } - widgetView.content = buildWidgetViewContent(tab.libraries); - widgetView.width = tab.libraries.length * ICON_WIDTH; - } - -`main.js` will -use the [`tabs`](modules/sdk/tabs.html) module to update the -widget's content when necessary (for example, when the user switches between -tabs): - - tabs.on('activate', function(tab) { - updateWidgetView(tab); - }); - - tabs.on('ready', function(tab) { - tab.libraries = []; - }); - -#### Showing the Library Detail #### - -The XUL library detector displayed the detailed information about each -library on mouseover in a tooltip: we can't do this using a widget, so -instead will use a panel. This means we'll need two additional content -scripts: - -* one in the widget's context, which listens for icon mouseover events -and sends a message to `main.js` containing the name of the corresponding -library: - -
-function setLibraryInfo(element) {
- self.port.emit('setLibraryInfo', element.target.title);
-}
-
-var elements = document.getElementsByTagName('img');
-
-for (var i = 0; i < elements.length; i++) {
- elements[i].addEventListener('mouseover', setLibraryInfo, false);
-}
-
-self.on("message", function(libraryInfo) {
- window.document.body.innerHTML = libraryInfo;
-});
-
-widget.port.on('setLibraryInfo', function(libraryInfo) {
- widget.panel.postMessage(libraryInfo);
-});
-
diff --git a/addon-sdk/source/doc/dev-guide-source/guides/modules.md b/addon-sdk/source/doc/dev-guide-source/guides/modules.md
deleted file mode 100644
index ece017542fe3..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/guides/modules.md
+++ /dev/null
@@ -1,191 +0,0 @@
-
-
-# Modules in the SDK #
-
-[CommonJS](http://wiki.commonjs.org/wiki/CommonJS) is the underlying
-infrastructure for both the SDK and the add-ons you build using the SDK.
-A CommonJS module is a piece of reusable JavaScript: it exports certain
-objects which are thus made available to dependent code. CommonJS defines:
-
-* an object called `exports` which contains all the objects which a CommonJS
-module wants to make available to other modules
-* a function called `require` which a module can use to import the `exports`
-object of another module.
-
-
-
-Except for [scripts that interact directly with web content](dev-guide/guides/content-scripts/index.html),
-all the JavaScript code you'll write or use when developing add-ons using
-the SDK is part of a CommonJS module, including:
-
-* [SDK modules](dev-guide/guides/modules.html#SDK Modules):
-the JavaScript modules which the SDK provides, such as
-[`panel`](modules/sdk/panel.html) and [page-mod](modules/sdk/page-mod.html).
-* [Local modules](dev-guide/guides/modules.html#Local Modules):
-each of the JavaScript files under your add-ons "lib" directory.
-* [External modules](dev-guide/guides/modules.html#External Modules):
-reusable modules developed and maintained outside the SDK, but usable by
-SDK-based add-ons.
-
-## SDK Modules ##
-
-The modules supplied by the SDK are divided into two sorts:
-
-* [High-level modules](dev-guide/high-level-apis.html) like
-[`panel`](modules/sdk/panel.html) and
- [`page-mod`](modules/sdk/page-mod.html) provide relatively simple,
-stable APIs for the most common add-on development tasks.
-* [Low-level modules](dev-guide/low-level-apis.html) like
-[`heritage`](modules/sdk/core/heritage.html) and
-[`namespace`](modules/sdk/core/heritage.html) provide more
-powerful functionality, and are typically less stable and more
-complex.
-
-To use SDK modules, you can pass `require()` a complete path, starting with
-"sdk", to the module you want to use. For high-level modules this is just
-`sdk/-
-
- my-addon
-
-
-
- lib
-
-
-
- main.js -
- password-dialog.js -
- secrets
-
-
-
- hash.js -
- - storage
-
-
-
- password-store.js -
-
-
- - lib
-
-
-
- my-addon
-
-
-
- lib
-
-
-
- main.js -
- dependencies
-
-
-
- geolocation.js -
-
-
- - lib
-
- No 'id' in package.json: creating a new ID for you. - package.json modified: please re-run 'cfx run' -- -The ID generated by `cfx` in this way is a randomly-generated string, but -you can define your own ID by editing the `package.json` file -directly. In particular, you can use the `extensionname@example.org` format -described in the -[Install Manifest documentation](https://developer.mozilla.org/en/install.rdf#id). -However, you can't use the -[GUID-style](https://developer.mozilla.org/en/Generating_GUIDs) format. diff --git a/addon-sdk/source/doc/dev-guide-source/guides/sdk-vs-xul.md b/addon-sdk/source/doc/dev-guide-source/guides/sdk-vs-xul.md deleted file mode 100644 index a4d1d344c9a3..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/guides/sdk-vs-xul.md +++ /dev/null @@ -1,107 +0,0 @@ - - - -# SDK and XUL Comparison # - -## Advantages of the SDK ## - -
| Simplicity | -The SDK provides high-level JavaScript APIs to simplify many -common tasks in add-on development, and tool support which greatly simplifies -the process of developing, testing, and packaging an add-on. - |
-
| Compatibility | - -Although we can't promise we'll never break a High-Level API, -maintaining compatibility across Firefox versions is a top priority for us. -We've designed the APIs to be forward-compatible with the new -multiple process architecture -(codenamed Electrolysis) planned for Firefox. -We also expect to support both desktop and mobile Firefox using a single -edition of the SDK: so you'll be able to write one extension and have it work -on both products. |
-
| Security | -If they're not carefully designed, Firefox add-ons can open the browser -to attack by malicious web pages. Although it's possible to write insecure -add-ons using the SDK, it's not as easy, and the damage that a compromised -add-on can do is usually more limited. |
-
| Restartlessness | -Add-ons built with the SDK are can be installed without having -to restart Firefox. -Although you can write - -traditional add-ons that are restartless, you can't use XUL overlays in -them, so most traditional add-ons would have to be substantially rewritten -anyway. |
-
| User Experience Best Practices | -The UI components available in the SDK are designed to align with the usability -guidelines for Firefox, giving your users a better, more consistent experience. |
-
| Mobile Support | -Starting in SDK 1.5, we've added experimental support for developing -add-ons on the new native version of Firefox Mobile. See the -tutorial on mobile development. |
-
| User interface flexibility | -XUL overlays offer a great deal of options for building a UI and -integrating it into the browser. Using only the SDK's supported APIs you have -much more limited options for your UI. |
-
| XPCOM | -Traditional add-ons have access to a vast amount of Firefox -functionality via XPCOM. The SDK's supported APIs expose a relatively -small set of this functionality. |
-
| Experimental | -The module is not yet stabilized. -You can try it out and provide feedback, but we may change or remove -it in future versions without having to pass through a formal -deprecation process. | -
| Unstable | -The API is in the process of settling, but has not yet had sufficient -real-world testing to be considered stable. -Backwards-compatibility will be maintained if reasonable. -If we do have to make backwards-incompatible changes, we will not guarantee -to go through the formal deprecation process. | -
| Stable | -The module is a fully-supported part of -the SDK. We will avoid breaking backwards compatibility unless absolutely -necessary. If we do have to make backwards-incompatible changes, we will -go through the formal deprecation process. | -
| Deprecated | -We plan to change this module, and backwards compatibility -should not be expected. Don’t start using it, and plan to migrate away from -this module to its replacement. | -
| API | -Add-on code | -Content script | -
|---|---|---|
The global objects defined in the core JavaScript language, such as
-Math, Array, and JSON. See the
-reference at MDN.
- |
- ✔ | -✔ | -
The require() is available, then so are the modules supplied in the
-SDK.
- |
- ✔ | -✘ | -
| The console -global supplied by the SDK. - | -✔ | -✔ | -
Globals defined by the
-HTML5 specification,
-such as window, document, and
-localStorage.
- |
- ✘ | -✔ | -
The self global, used for communicating between content
-scripts and add-on code. See the guide to
-communicating with content scripts
-for more details.
- |
- ✘ | -✔ | -
-
-
- my-addon
-
-
-
- chrome
-
- content -
- locale -
- skin
- - chrome.manifest -
- data -
- lib -
- package.json -
- - chrome
-
Welcome to the Add-on SDK!
- -Using the Add-on SDK you can create Firefox add-ons using standard Web -technologies: JavaScript, HTML, and CSS. The SDK includes JavaScript APIs which you can use to create add-ons, and tools for creating, running, testing, and packaging add-ons. - -- -## Tutorials ## - -
- Getting started- How to - install the SDK and - use the cfx - tool to develop, test, and package add-ons. - |
-
-
- Create user interface components- Create user interface components such as - toolbar buttons, - menu items, and - dialogs - |
-
- Interact with the browser- Open web pages, - listen for pages loading, and - list open pages. - |
-
-
- Modify web pages- Modify pages matching a URL pattern - or dynamically modify a particular tab. - |
-
- Development techniques-Learn about common development techniques, such as -unit testing, -logging, -creating reusable modules, -localization, and -mobile development. - |
-
-
- Putting it together- Walkthrough of the Annotator example add-on. - |
-
- -## Guides ## - -
- Contributor's Guide- Learn - how to start contributing to the SDK, - and about the most important idioms used in the SDK code, such as - modules, - classes and inheritance, - private properties, and - content processes. - |
-
-
- SDK idioms- The SDK's - event framework and the - distinction between add-on scripts and content scripts. - |
-
-
- SDK infrastructure- Aspects of the SDK's underlying technology: - Modules, the - Program ID, - and the rules defining - Firefox compatibility. - |
-
-
- XUL migration- A guide to porting XUL add-ons to the SDK. - This guide includes a - comparison of the two toolsets and a - worked example of porting a XUL add-on. - |
-
-
- Content scripts- A detailed guide to working with content scripts, - including: how to load content scripts, which objects - content scripts can access, and how to communicate - between content scripts and the rest of your add-on. - |
-
- - | - -
- -## Reference ## - -
- High-Level APIs- Reference documentation for the high-level SDK APIs. - |
-
-
- Low-Level APIs- Reference documentation for the low-level SDK APIs. - |
-
- Tools reference- Reference documentation for the - cfx tool - used to develop, test, and package add-ons, the - console - global used for logging, and the - package.json file. - |
- - | -
-{
- "name": "my-addon",
- "fullName": "my-addon",
- "description": "a basic add-on",
- "author": "",
- "license": "MPL 2.0",
- "version": "0.1"
-}
-
-
-`package.json` may contain the following keys:
-
-author |
- The original author of the package. Defaults to an empty string. - It may include a optional URL in parentheses and an email - address in angle brackets. -This value will be used as the add-on's
- |
-
contributors |
- An array of additional These values will be used as the add-on's
- |
-
dependencies |
- String or array of strings representing package - names that this add-on requires in order to function properly. |
-
description |
- The add-on's description. This defaults to the text
- This value will be used as the add-on's
- |
-
fullName |
- The full name of the package. It can contain spaces. - If this key is present its value will be used as the add-on's -em:name
- element in its "install.rdf". |
-
harnessClassID |
- String in the GUID format. -This is used as a
- |
-
homepage |
- The URL of the add-on's website. -This value will be used as the add-on's
- |
-
icon |
- The relative path from the root of the add-on to a
- PNG file containing the icon for the add-on. Defaults to
- This value will be used as the add-on's
- The icon may be up to 48x48 pixels in size. |
-
icon64 |
- The relative path from the root of the add-on to a
- PNG file containing the large icon for the add-on. Defaults to
- This value will be used as the add-on's
- The icon may be up to 64x64 pixels in size. |
-
id |
- A globally unique identifier for the add-on. -This value will be used as the add-on's
- See the Program ID documentation. |
-
lib |
- String representing the top-level module directory provided in
- this add-on. Defaults to |
-
license |
- The name of the license under which the add-on is distributed, with an optional
- URL in parentheses. Defaults to |
-
main |
- String representing the name of a program module that is
- located in one of the top-level module directories specified by
- |
-
name |
- The add-on's name. This name cannot contain spaces or periods, and - defaults to the name of the parent directory. When the add-on is
- built as an XPI, if the |
-
packages |
- String or array of strings representing paths to
- directories containing additional packages. Defaults to
- |
-
permissions |
- A set of permissions that the add-on needs. -
|
-
preferences |
- An array of JSON objects that use the following keys:
- See the documentation for the
- |
-
tests |
- String representing the top-level module directory containing
- test suites for this package. Defaults to |
-
translators |
- An array of strings listing translators of this add-on. -These values will be used as the add-on's
- |
-
version |
- String representing the version of the add-on. Defaults to
- This value will be used as the add-on's
- |
-
Loading
-
-
-
-
-
-
diff --git a/addon-sdk/source/doc/dev-guide-source/third-party-apis.md b/addon-sdk/source/doc/dev-guide-source/third-party-apis.md
deleted file mode 100644
index 6919c69bf4ea..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/third-party-apis.md
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-# Third-Party APIs #
-
-This section lists modules which you've downloaded and added to your SDK installation.
\ No newline at end of file
diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/add-a-context-menu-item.md b/addon-sdk/source/doc/dev-guide-source/tutorials/add-a-context-menu-item.md
deleted file mode 100644
index 6f35c21ad0af..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/tutorials/add-a-context-menu-item.md
+++ /dev/null
@@ -1,89 +0,0 @@
-
-
-# Add a Context Menu Item #
-
-
-To follow this tutorial you'll need to have
-[installed the SDK](dev-guide/tutorials/installation.html)
-and learned the
-[basics of `cfx`](dev-guide/tutorials/getting-started-with-cfx.html).
-
-
-To add items and submenus to the Firefox context menu, use the
-[`context-menu`](modules/sdk/context-menu.html) module.
-
-Here's an add-on that adds a new context menu item. The item is
-displayed whenever something in the page is selected. When it's
-clicked, the selection is sent to the main add-on code, which just
-logs it:
-
- var contextMenu = require("sdk/context-menu");
- var menuItem = contextMenu.Item({
- label: "Log Selection",
- context: contextMenu.SelectionContext(),
- contentScript: 'self.on("click", function () {' +
- ' var text = window.getSelection().toString();' +
- ' self.postMessage(text);' +
- '});',
- onMessage: function (selectionText) {
- console.log(selectionText);
- }
- });
-
-Try it: run the add-on, load a web page, select some text and right-click.
-You should see the new item appear:
-
-
-
-Click it, and the selection is
-[logged to the console](dev-guide/tutorials/logging.html):
-
--info: elephantine lizard -- -All this add-on does is to construct a context menu item. You don't need -to add it: once you have constructed the item, it is automatically added -in the correct context. The constructor in this case takes four options: -`label`, `context`, `contentScript`, and `onMessage`. - -### label ### - -The `label` is just the string that's displayed. - -### context ### - -The `context` describes the circumstances in which the item should be -shown. The `context-menu` module provides a number of simple built-in -contexts, including this `SelectionContext()`, which means: display -the item when something on the page is selected. - -If these simple contexts aren't enough, you can define more sophisticated -contexts using scripts. - -### contentScript ### - -This attaches a script to the item. In this case the script listens for -the user to click on the item, then sends a message to the add-on containing -the selected text. - -### onMessage ### - -The `onMessage` property provides a way for the add-on code to respond to -messages from the script attached to the context menu item. In this case -it just logs the selected text. - -So: - -1. the user clicks the item -2. the content script's `click` event fires, and the content script retrieves -the selected text and sends a message to the add-on -3. the add-on's `message` event fires, and the add-on code's handler function -is passed the selected text, which it logs - -## Learning More ## - -To learn more about the `context-menu` module, see the -[`context-menu` API reference](modules/sdk/context-menu.html). \ No newline at end of file diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/adding-menus.md b/addon-sdk/source/doc/dev-guide-source/tutorials/adding-menus.md deleted file mode 100644 index 46e7130c68b6..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/adding-menus.md +++ /dev/null @@ -1,137 +0,0 @@ - - -# Add a Menu Item to Firefox # - - -To follow this tutorial you'll need to have -[installed the SDK](dev-guide/tutorials/installation.html) -and learned the -[basics of `cfx`](dev-guide/tutorials/getting-started-with-cfx.html). - - -The SDK doesn't yet provide an API to add new menu items to Firefox. -But it's extensible by design, so anyone can build and publish -modules for add-on developers to use. Luckily, Erik Vold has written -a [`menuitems`](https://github.com/erikvold/menuitems-jplib) module -that enables us to add menu items. - -This tutorial does double-duty. It describes the general method for -using an external, third-party module in your add-on, and it -describes how to add a menu item using the `menuitems` module in particular. - -First, create a new add-on. Make a directory called "clickme" wherever you -like, navigate to it and run `cfx init`. - -
-mkdir clickme -cd clickme -cfx init -- -The usual directory structure will be created: - -
-
-
- clickme
-
-
-
- data -
- docs
-
- main.md
- - lib
-
- main.js
- - package.json -
- README.md -
- tests
-
- test-main.js
-
-
-mkdir packages -cd packages -tar -xf ../erikvold-menuitems-jplib-d80630c.zip -- -## Module Dependencies ## - -If third-party modules only depend on SDK modules, you can use them right -away, but if they depend on other third-party modules, you'll have to install -those dependencies as well. - -In the package's main directory you'll find a file called "package.json". -Open it up and look for an entry named "dependencies". The entry for the -`menuitems` package is: - -
-"dependencies": ["vold-utils"] -- -This tells us that we need to install the `vold-utils` package, -which we can do by downloading it from -[https://github.com/erikvold/vold-utils-jplib](https://github.com/voldsoftware/vold-utils-jplib/zipball/1b2ad874c2d3b2070a1b0d43301aa3731233e84f) -and adding it under the `packages` directory alongside `menuitems`. - -## Using `menuitems` ## - -The [documentation for the `menuitems` module](https://github.com/erikvold/menuitems-jplib/blob/master/docs/menuitems.md) -tells us to create a menu item using `MenuItem()`. Of the options -accepted by `MenuItem()`, we'll use this minimal set: - -* `id`: identifier for this menu item -* `label`: text the item displays -* `command`: function called when the user selects the item -* `menuid`: identifier for the item's parent element -* `insertbefore`: identifier for the item before which we want our item to -appear - - - - var menuitem = require("menuitems").Menuitem({ - id: "clickme", - menuid: "menu_ToolsPopup", - label: "Click Me!", - onCommand: function() { - console.log("clicked"); - }, - insertbefore: "menu_pageInfo" - }); - -Next, we have to declare our dependency on the `menuitems` package. -In your add-on's `package.json` add the line: - -
-"dependencies": "menuitems" -- -Note that due to -[bug 663480](https://bugzilla.mozilla.org/show_bug.cgi?id=663480), if you -add a `dependencies` line to `package.json`, and you use any modules from -the SDK, then you must also declare your dependency on that built-in package, -like this: - -
-"dependencies": ["menuitems", "addon-sdk"] -- -Now we're done. Run the add-on and you'll see the new item appear in the -`Tools` menu: select it and you'll see `info: clicked` appear in the -console. - -## Caveats ## - -Third-party modules are a great way to use features not directly supported by -the SDK, but because third party modules typically use low-level APIs, -they may be broken by new releases of Firefox. diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/adding-toolbar-button.md b/addon-sdk/source/doc/dev-guide-source/tutorials/adding-toolbar-button.md deleted file mode 100644 index 184c6f563c57..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/adding-toolbar-button.md +++ /dev/null @@ -1,174 +0,0 @@ - - -# Adding a Button to the Toolbar # - - -To follow this tutorial you'll need to have -[installed the SDK](dev-guide/tutorials/installation.html) -and learned the -[basics of `cfx`](dev-guide/tutorials/getting-started-with-cfx.html). - - -To add a button to the toolbar, use the -[`widget`](modules/sdk/widget.html) module. - -Create a new directory, navigate to it, and execute `cfx init`. -Then open the file called "main.js" in the "lib" directory and -add the following code to it: - - var widgets = require("sdk/widget"); - var tabs = require("sdk/tabs"); - - var widget = widgets.Widget({ - id: "mozilla-link", - label: "Mozilla website", - contentURL: "http://www.mozilla.org/favicon.ico", - onClick: function() { - tabs.open("http://www.mozilla.org/"); - } - }); - -The widget is added to the "Add-on Bar" at the bottom of the browser window: - -
-
-You can't change the initial location for the widget, but the user can move
-it to a different toolbar. The `id` attribute is mandatory, and is used to
-remember the position of the widget, so you should not change it in subsequent
-versions of the add-on.
-
-Clicking the button opens [http://www.mozilla.org](http://www.mozilla.org).
-
-
-
-## Specifying the Icon ##
-
-If you're using the widget to make a toolbar button, specify the icon to
-display using `contentURL`: this may refer to a remote file as in the
-example above, or may refer to a local file. The example below will load
-an icon file called "my-icon.png" from the add-on's `data` directory:
-
- var widgets = require("sdk/widget");
- var tabs = require("sdk/tabs");
- var self = require("sdk/self");
-
- var widget = widgets.Widget({
- id: "mozilla-link",
- label: "Mozilla website",
- contentURL: self.data.url("my-icon.png"),
- onClick: function() {
- tabs.open("http://www.mozilla.org/");
- }
- });
-
-You can change the icon at any time by setting the widget's `contentURL`
-property. However, setting the `contentURL` property will break the
-channel of communication between this widget and any content scripts it
-contains. Messages sent from the content script will no longer be received
-by the main add-on code, and vice versa. This issue is currently tracked as
-[bug 825434](https://bugzilla.mozilla.org/show_bug.cgi?id=825434).
-
-## Responding To the User ##
-
-You can listen for `click`, `mouseover`, and `mouseout` events by passing
-handler functions as the corresponding constructor options. The widget
-example above assigns a listener to the `click` event using the `onClick`
-option, and there are similar `onMouseover` and `onMouseout` options.
-
-To handle user interaction in more detail, you can attach a content
-script to the widget. Your add-on script and the content script can't
-directly access each other's variables or call each other's functions, but
-they can send each other messages.
-
-Here's an example. The widget's built-in `onClick` property does not
-distinguish between left and right mouse clicks, so to do this we need
-to use a content script. The script looks like this:
-
- window.addEventListener('click', function(event) {
- if(event.button == 0 && event.shiftKey == false)
- self.port.emit('left-click');
-
- if(event.button == 2 || (event.button == 0 && event.shiftKey == true))
- self.port.emit('right-click');
- event.preventDefault();
- }, true);
-
-It uses the standard DOM `addEventListener()` function to listen for click
-events, and handles them by sending the corresponding message to the main
-add-on code. Note that the messages "left-click" and "right-click" are not
-defined in the widget API itself, they're custom events defined by the add-on
-author.
-
-Save this script in your `data` directory as "click-listener.js".
-
-Next, modify `main.js` to:
-
--
-
- pass in the script by setting the
contentScriptFile-property
- - listen for the new events: -
-
-If you supply a `panel` object to the widget's constructor, then the panel
-will be shown when the user clicks the widget:
-
- data = require("sdk/self").data
-
- var clockPanel = require("sdk/panel").Panel({
- width:215,
- height:160,
- contentURL: data.url("clock.html")
- });
-
- require("sdk/widget").Widget({
- id: "open-clock-btn",
- label: "Clock",
- contentURL: data.url("History.png"),
- panel: clockPanel
- });
-
-To learn more about working with panels, see the tutorial on
-[displaying a popup](dev-guide/tutorials/display-a-popup.html).
-
-## Learning More ##
-
-To learn more about the widget module, see its
-[API reference documentation](modules/sdk/widget.html).
-
-To learn more about content scripts, see the
-[content scripts guide](dev-guide/guides/content-scripts/index.html).
diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/creating.md b/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/creating.md
deleted file mode 100644
index d0e5448e124e..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/creating.md
+++ /dev/null
@@ -1,344 +0,0 @@
-
-
-# Creating Annotations #
-
-We'll use two objects to create annotations: a page-mod to find page elements
-that the user can annotate, and a panel for the user to enter the annotation
-text itself.
-
-## Selector page-mod ##
-
-### Selector Content Scripts ###
-
-The content script for the selector page-mod uses [jQuery](http://jquery.com/)
-to examine and manipulate the DOM.
-
-Its main job is to maintain a "matched element": this is the page element that
-is the current candidate for an annotation. The matched element is highlighted
-and has a click handler bound to it which sends a message to the main add-on
-code.
-
-The selector page mod can be switched on and off using a message from the
-main add-on code. It is initially off:
-
- var matchedElement = null;
- var originalBgColor = null;
- var active = false;
-
- function resetMatchedElement() {
- if (matchedElement) {
- $(matchedElement).css('background-color', originalBgColor);
- $(matchedElement).unbind('click.annotator');
- }
- }
-
- self.on('message', function onMessage(activation) {
- active = activation;
- if (!active) {
- resetMatchedElement();
- }
- });
-
-This selector listens for occurrences of the
-[jQuery mouseenter](http://api.jquery.com/mouseenter/) event.
-
-When a mouseenter event is triggered the selector checks whether the element
-is eligible for annotation. An element is eligible if it, or one of its
-ancestors in the DOM tree, has an attribute named `"id"`. The idea here is to
-make it more likely that the annotator will be able to identify annotated
-elements correctly later on.
-
-If the page element is eligible for annotation, then the selector highlights
-that element and binds a click handler to it. The click handler sends a message
-called `show` back to the main add-on code. The `show` message contains: the URL
-for the page, the ID attribute value, and the text content of the page element.
-
- $('*').mouseenter(function() {
- if (!active || $(this).hasClass('annotated')) {
- return;
- }
- resetMatchedElement();
- ancestor = $(this).closest("[id]");
- matchedElement = $(this).first();
- originalBgColor = $(matchedElement).css('background-color');
- $(matchedElement).css('background-color', 'yellow');
- $(matchedElement).bind('click.annotator', function(event) {
- event.stopPropagation();
- event.preventDefault();
- self.port.emit('show',
- [
- document.location.toString(),
- $(ancestor).attr("id"),
- $(matchedElement).text()
- ]
- );
- });
- });
-
-Conversely, the add-on resets the matched element on
-[mouseout](http://api.jquery.com/mouseout/):
-
- $('*').mouseout(function() {
- resetMatchedElement();
- });
-
-Save this code in a new file called `selector.js` in your add-on's `data`
-directory.
-
-Because this code uses jQuery, you'll need to
-[download](http://docs.jquery.com/Downloading_jQuery) that as well, and save it in
-`data`.
-
-### Updating main.js ###
-
-Go back to `main.js` and add the code to create the selector into the `main`
-function:
-
- var selector = pageMod.PageMod({
- include: ['*'],
- contentScriptWhen: 'ready',
- contentScriptFile: [data.url('jquery-1.4.2.min.js'),
- data.url('selector.js')],
- onAttach: function(worker) {
- worker.postMessage(annotatorIsOn);
- selectors.push(worker);
- worker.port.on('show', function(data) {
- console.log(data);
- });
- worker.on('detach', function () {
- detachWorker(this, selectors);
- });
- }
- });
-
-Make sure the name you use to load jQuery matches the name of the jQuery
-version you downloaded.
-
-The page-mod matches all pages, so each time the user loads a page the page-mod
-emits the `attach` event, which will call the listener function we've assigned
-to `onAttach`. The handler is passed a
-[worker](modules/sdk/content/worker.html) object. Each worker
-represents a channel of communication between the add-on code and any content
-scripts running in that particular page context. For a more detailed discussion
-of the way `page-mod` uses workers, see the
-[page-mod documentation](modules/sdk/page-mod.html).
-
-In the attach handler we do three things:
-
-* send the content script a message with the current activation status
-* add the worker to an array called `selectors` so we can send it messages
-later on
-* assign a message handler for messages from this worker. If the message is
-`show` we will just log the content for the time being. If the message is
-`detach` we remove the worker from the `selectors` array.
-
-At the top of the file import the `page-mod` module and declare an array for
-the workers:
-
- var pageMod = require('sdk/page-mod');
- var selectors = [];
-
-Add `detachWorker`:
-
- function detachWorker(worker, workerArray) {
- var index = workerArray.indexOf(worker);
- if(index != -1) {
- workerArray.splice(index, 1);
- }
- }
-
-Edit `toggleActivation` to notify the workers of a change in activation state:
-
- function activateSelectors() {
- selectors.forEach(
- function (selector) {
- selector.postMessage(annotatorIsOn);
- });
- }
-
- function toggleActivation() {
- annotatorIsOn = !annotatorIsOn;
- activateSelectors();
- return annotatorIsOn;
- }
-
-We'll be using this URL in all our screenshots. Because
-`cfx run` doesn't preserve browsing history, if you want to play along it's
-worth taking a note of the URL.
-Save the file and execute `cfx run` again. Activate the annotator by clicking
-the widget and load a page: the screenshot below uses
-[http://blog.mozilla.com/addons/2011/02/04/
-overview-amo-review-process/](http://blog.mozilla.com/addons/2011/02/04/overview-amo-review-process/).
-You should see the highlight appearing when you move the mouse over certain elements:
-
-- info: show - info: http://blog.mozilla.com/addons/2011/02/04/overview-amo-review-process/, - post-2249,When you submit a new add-on, you will have to choose between 2 - review tracks: Full Review and Preliminary Review. -- -## Annotation Editor Panel ## - -So far we have a page-mod that can highlight elements and send information -about them to the main add-on code. Next we will create the editor panel, -which enables the user to enter an annotation associated with the selected -element. - -We will supply the panel's content as an HTML file, and will also supply a -content script to execute in the panel's context. - -So create a subdirectory under `data` called `editor`. This will contain -two files: the HTML content, and the content script. - -### Annotation Editor HTML ### - -The HTML is very simple: - - - -Save this inside `data/editor` as `annotation-editor.html`. - -### Annotation Editor Content Script ### - -In the corresponding content script we do two things: - -* handle a message from the add-on code by giving the text area focus -* listen for the return key and when it is pressed, send the contents of the -text area to the add-on. - -Here's the code: - - var textArea = document.getElementById('annotation-box'); - - textArea.onkeyup = function(event) { - if (event.keyCode == 13) { - self.postMessage(textArea.value); - textArea.value = ''; - } - }; - - self.on('message', function() { - var textArea = document.getElementById('annotation-box'); - textArea.value = ''; - textArea.focus(); - }); - - -Save this inside `data/editor` as `annotation-editor.js`. - -### Updating main.js Again ### - -Now we'll update `main.js` again to create the editor and use it. - -First, import the `panel` module: - - var panels = require('sdk/panel'); - -Then add the following code to the `main` function: - - var annotationEditor = panels.Panel({ - width: 220, - height: 220, - contentURL: data.url('editor/annotation-editor.html'), - contentScriptFile: data.url('editor/annotation-editor.js'), - onMessage: function(annotationText) { - if (annotationText) { - console.log(this.annotationAnchor); - console.log(annotationText); - } - annotationEditor.hide(); - }, - onShow: function() { - this.postMessage('focus'); - } - }); - -We create the editor panel but don't show it. -We will send the editor panel the `focus` message when it is shown, so it will -give the text area focus. When the editor panel sends us its message we log the -message and hide the panel. - -The only thing left is to link the editor to the selector. So edit the message -handler assigned to the selector so that on receiving the `show` message we -assign the content of the message to the panel using a new property -"annotationAnchor", and show the panel: - - var selector = pageMod.PageMod({ - include: ['*'], - contentScriptWhen: 'ready', - contentScriptFile: [data.url('jquery-1.4.2.min.js'), - data.url('selector.js')], - onAttach: function(worker) { - worker.postMessage(annotatorIsOn); - selectors.push(worker); - worker.port.on('show', function(data) { - annotationEditor.annotationAnchor = data; - annotationEditor.show(); - }); - worker.on('detach', function () { - detachWorker(this, selectors); - }); - } - }); - -Execute `cfx run` again, activate the annotator, move your mouse over an -element and click the element when it is highlighted. You should see a panel -with a text area for a note: - -
- -Enter the note and press the return key: you should see console output like -this: - -
- info: http://blog.mozilla.com/addons/2011/02/04/overview-amo-review-process/, - post-2249,When you submit a new add-on, you will have to choose between 2 - review tracks: Full Review and Preliminary Review. - info: We should ask for Full Review if possible. -- -That's a complete annotation, and in the next section we'll deal with -[storing it](dev-guide/tutorials/annotator/storing.html). diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/displaying.md b/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/displaying.md deleted file mode 100644 index aa6d5a6dda0d..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/displaying.md +++ /dev/null @@ -1,213 +0,0 @@ - - -# Displaying Annotations # - -In this chapter we'll use a page-mod to locate elements of web pages that have -annotations associated with them, and a panel to display the annotations. - -## Matcher page-mod ## - -### Matcher Content Script ### - -The content script for the matcher page-mod is initialized with a list -of all the annotations that the user has created. - -When a page is loaded the matcher searches the DOM for elements that match -annotations. If it finds any it binds functions to that element's -[mouseenter](http://api.jquery.com/mouseenter/) and -[mouseleave](http://api.jquery.com/mouseleave/) events to send messages to the -`main` module, asking it to show or hide the annotation. - -Like the selector, the matcher also listens for the window's `unload` event -and on unload sends a `detach` message to the `main` module, so the add-on -can clean it up. - -The complete content script is here: - - self.on('message', function onMessage(annotations) { - annotations.forEach( - function(annotation) { - if(annotation.url == document.location.toString()) { - createAnchor(annotation); - } - }); - - $('.annotated').css('border', 'solid 3px yellow'); - - $('.annotated').bind('mouseenter', function(event) { - self.port.emit('show', $(this).attr('annotation')); - event.stopPropagation(); - event.preventDefault(); - }); - - $('.annotated').bind('mouseleave', function() { - self.port.emit('hide'); - }); - }); - - function createAnchor(annotation) { - annotationAnchorAncestor = $('#' + annotation.ancestorId); - annotationAnchor = $(annotationAnchorAncestor).parent().find( - ':contains(' + annotation.anchorText + ')').last(); - $(annotationAnchor).addClass('annotated'); - $(annotationAnchor).attr('annotation', annotation.annotationText); - } - -Save this in `data` as `matcher.js`. - -### Updating main.js ### - -First, initialize an array to hold workers associated with the matcher's -content scripts: - - var matchers = []; - -In the `main` function, add the code to create the matcher: - - var matcher = pageMod.PageMod({ - include: ['*'], - contentScriptWhen: 'ready', - contentScriptFile: [data.url('jquery-1.4.2.min.js'), - data.url('matcher.js')], - onAttach: function(worker) { - if(simpleStorage.storage.annotations) { - worker.postMessage(simpleStorage.storage.annotations); - } - worker.port.on('show', function(data) { - annotation.content = data; - annotation.show(); - }); - worker.port.on('hide', function() { - annotation.content = null; - annotation.hide(); - }); - worker.on('detach', function () { - detachWorker(this, matchers); - }); - matchers.push(worker); - } - }); - -When a new page is loaded the function assigned to `onAttach` is called. This -function: - -* initializes the content script instance with the current set of -annotations -* provides a handler for messages from that content script, handling the three -messages - `show`, `hide` and `detach` - that the content script might send -* adds the worker to an array, so we it can send messages back later. - -Then in the module's scope implement a function to update the matcher's -workers, and edit `handleNewAnnotation` to call this new function when the -user enters a new annotation: - - function updateMatchers() { - matchers.forEach(function (matcher) { - matcher.postMessage(simpleStorage.storage.annotations); - }); - } - -
- - function handleNewAnnotation(annotationText, anchor) { - var newAnnotation = new Annotation(annotationText, anchor); - simpleStorage.storage.annotations.push(newAnnotation); - updateMatchers(); - } -
- -## Annotation panel ## - -The annotation panel just shows the content of an annotation. - -There are two files associated with the annotation panel: - -* a simple HTML file to use as a template -* a simple content script to build the panel's content - -These files will live in a new subdirectory of `data` which we'll call -`annotation`. - -### Annotation panel HTML ### - - - -Save this in `data/annotation` as `annotation.html`. - -### Annotation panel Content Script ### - -The annotation panel has a minimal content script that sets the text: - - self.on('message', function(message) { - $('#annotation').text(message); - }); - -Save this in `data/annotation` as `annotation.js`. - -### Updating main.js ### - -Finally, update `main.js` with the code to construct the annotation panel: - - var annotation = panels.Panel({ - width: 200, - height: 180, - contentURL: data.url('annotation/annotation.html'), - contentScriptFile: [data.url('jquery-1.4.2.min.js'), - data.url('annotation/annotation.js')], - onShow: function() { - this.postMessage(this.content); - } - }); - -Execute `cfx run` one last time. Activate the annotator and enter an -annotation. You should see a yellow border around the item you annotated: - -
- -When you move your mouse over the item, the annotation should appear: - -
- -Obviously this add-on isn't complete yet. It could do with more beautiful -styling, it certainly needs a way to delete annotations, it should deal with -`OverQuota` more reliably, and the matcher could be made to match more -reliably. - -But we hope this gives you an idea of the things that are possible with the -modules in the SDK. diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/index.md b/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/index.md deleted file mode 100644 index ec71f55c7348..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/index.md +++ /dev/null @@ -1,31 +0,0 @@ - - -# Annotator: a More Complex Add-on # - -In this tutorial we'll build an add-on that uses many of the SDK's -[high-level APIs](modules/high-level-modules.html). - -The add-on is an annotator: it enables the user to select elements of web pages -and enter notes (annotations) associated with them. The annotator stores the -notes. Whenever the user loads a page containing annotated elements these -elements are highlighted, and if the user moves the mouse over an annotated -element its annotation is displayed. - -Next we'll give a quick overview of the annotator's design, then go through -the implementation, step by step. - -If you want to refer to the complete add-on you can find it under the -`examples` directory. - -* [Design Overview](dev-guide/tutorials/annotator/overview.html) - -* [Implementing the Widget](dev-guide/tutorials/annotator/widget.html) - -* [Creating Annotations](dev-guide/tutorials/annotator/creating.html) - -* [Storing Annotations](dev-guide/tutorials/annotator/storing.html) - -* [Displaying Annotations](dev-guide/tutorials/annotator/displaying.html) - diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/overview.md b/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/overview.md deleted file mode 100644 index bbdba2c802d4..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/overview.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Annotator Design Overview # - -The annotator uses content scripts to build user interfaces, get user input, -and examine the DOM of pages loaded by the user. - -Meanwhile the `main` module contains the application logic and mediates -interactions between the different SDK objects. - -We could represent the basic interactions between the `main` module and the -various content scripts like this: - -
-<html> -<head> - <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - <title>Saved annotations</title> - <link rel="stylesheet" type="text/css" href="annotation-list.css" /> -</head> - -<body> - -<div id="annotation-list"> -</div> - -<div id="template"> - <div class="annotation-details"> - <a class="url"></a> - <div class="selection-text"></div> - <div class="annotation-text"></div> - </div> -</div> - -</body> - -</html> - -- -Here's the corresponding CSS: - - - -Save these in `data/list` as `annotation-list.html` and `annotation-list.css` -respectively. - -### Updating main.js ### - -Here's the code to create the panel, which can go in the `main` function. - - var annotationList = panels.Panel({ - width: 420, - height: 200, - contentURL: data.url('list/annotation-list.html'), - contentScriptFile: [data.url('jquery-1.4.2.min.js'), - data.url('list/annotation-list.js')], - contentScriptWhen: 'ready', - onShow: function() { - this.postMessage(simpleStorage.storage.annotations); - }, - onMessage: function(message) { - require('sdk/tabs').open(message); - } - }); - -Since this panel's content script uses jQuery we will pass that in too: again, -make sure the name of it matches the version of jQuery you downloaded. - -When the panel is shown we send it the array of stored annotations. When the -panel sends us a URL we use the `tabs` module to open it in a new tab. - -Finally we need to connect this to the widget's `right-click` message: - - var widget = widgets.Widget({ - id: 'toggle-switch', - label: 'Annotator', - contentURL: data.url('widget/pencil-off.png'), - contentScriptWhen: 'ready', - contentScriptFile: data.url('widget/widget.js') - }); - - widget.port.on('left-click', function() { - console.log('activate/deactivate'); - widget.contentURL = toggleActivation() ? - data.url('widget/pencil-on.png') : - data.url('widget/pencil-off.png'); - }); - - widget.port.on('right-click', function() { - console.log('show annotation list'); - annotationList.show(); - }); - -This time execute `cfx xpi` to build the XPI for the add-on, and install it in -Firefox. Activate the add-on, add an annotation, and then right-click the -widget. You should see something like this: - -
- - -Until now we've always run `cfx run` rather than building an XPI and installing -the add-on in Firefox. If the annotation does not reappear when you restart -Firefox, double check you installed the add-on and didn't just use `cfx run` -again. -Restart Firefox, right-click the widget again, and check that the annotation -is still there. - -## Responding To OverQuota events ## - -Add-ons have a limited quota of storage space. If the add-on exits while -it is over quota, any data stored since the last time it was in quota will not -be persisted. - -So we want to listen to the `OverQuota` event emitted by `simple-storage` and -respond to it. Add the following to your add-on's `main` function: - - simpleStorage.on("OverQuota", function () { - notifications.notify({ - title: 'Storage space exceeded', - text: 'Removing recent annotations'}); - while (simpleStorage.quotaUsage > 1) - simpleStorage.storage.annotations.pop(); - }); - -Because we use a notification to alert the user, we need to import the -`notifications` module: - - var notifications = require("sdk/notifications"); - -(It should be obvious that this is an incredibly unhelpful way to deal with the -problem. A real add-on should give the user a chance to choose which data to -keep, and prevent the user from adding any more data until the add-on is back -under quota.) - -## Respecting Private Browsing ## - -Since annotations record the user's browsing history we should avoid recording -annotations in private windows. - -There's a very simple way to do this: do nothing. By omitting the -[`"private-browsing"` key](dev-guide/package-spec.html#permissions) from the -annotator's "package.json" file, the annotator opts out of private browsing -altogether. - -This means that its widget will not appear on any private windows and its -selector and matcher content scripts won't run, so the user won't be able to -enter any annotations in private windows. - -Try it: execute cfx run and open a new private window: you should no longer -see the annotator's widget. - -Now we can create and store annotations, the last piece is to -[display them when the user loads the page](dev-guide/tutorials/annotator/displaying.html). \ No newline at end of file diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/widget.md b/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/widget.md deleted file mode 100644 index 605e062f027e..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/annotator/widget.md +++ /dev/null @@ -1,115 +0,0 @@ - - -# Implementing the Widget # - -We want the widget to do two things: - - -[Bug 634712](https://bugzilla.mozilla.org/show_bug.cgi?id=634712) asks that -the widget API should emit separate, or at least distinguishable, events for -left and right mouse clicks, and when it is fixed this widget won't need a -content script any more. - -* On a left-click, the widget should activate or deactivate the annotator. -* On a right-click, the widget should display a list of all the annotations -the user has created. - -Because the widget's `click` event does not distinguish left and right mouse -clicks, we'll use a content script to capture the click events and send the -corresponding message back to our add-on. - -The widget will have two icons: one to display when it's active, one to display -when it's inactive. - -So there are three files we'll need to create: the widget's content script and -its two icons. - -Inside the `data` subdirectory create another subdirectory `widget`. We'll -keep the widget's files here. (Note that this isn't mandatory: you could just -keep them all under `data`. But it seems tidier this way.) - -## The Widget's Content Script ## - -The widget's content script just listens for left- and right- mouse clicks and -posts the corresponding message to the add-on code: - - this.addEventListener('click', function(event) { - if(event.button == 0 && event.shiftKey == false) - self.port.emit('left-click'); - - if(event.button == 2 || (event.button == 0 && event.shiftKey == true)) - self.port.emit('right-click'); - event.preventDefault(); - }, true); - -Save this in your `data/widget` directory as `widget.js`. - -## The Widget's Icons ## - -You can copy the widget's icons from here: - -
-
-
-(Or make your own if you're feeling creative.) Save them in your `data/widget` directory.
-
-## main.js ##
-
-Now in the `lib` directory open `main.js` and add the following code:
-
- var widgets = require('sdk/widget');
- var data = require('sdk/self').data;
-
- var annotatorIsOn = false;
-
- function toggleActivation() {
- annotatorIsOn = !annotatorIsOn;
- return annotatorIsOn;
- }
-
- exports.main = function() {
-
- var widget = widgets.Widget({
- id: 'toggle-switch',
- label: 'Annotator',
- contentURL: data.url('widget/pencil-off.png'),
- contentScriptWhen: 'ready',
- contentScriptFile: data.url('widget/widget.js')
- });
-
- widget.port.on('left-click', function() {
- console.log('activate/deactivate');
- widget.contentURL = toggleActivation() ?
- data.url('widget/pencil-on.png') :
- data.url('widget/pencil-off.png');
- });
-
- widget.port.on('right-click', function() {
- console.log('show annotation list');
- });
- }
-
-The annotator is inactive by default. It creates the widget and responds to
-messages from the widget's content script by toggling its activation state.
-Note that due to
-[bug 626326](https://bugzilla.mozilla.org/show_bug.cgi?id=626326) the add-on
-bar's context menu is displayed, despite the `event.preventDefault()` call
-in the widget's content script.
-Since we don't have any code to display annotations yet, we just log the
-right-click events to the console.
-
-Now from the `annotator` directory type `cfx run`. You should see the widget
-in the add-on bar:
-
-
-
-
-
-- -Left- and right-clicks should produce the appropriate debug output, and a -left-click should also change the widget icon to signal that it is active. - -Next we'll add the code to -[create annotations](dev-guide/tutorials/annotator/creating.html). diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/chrome.md b/addon-sdk/source/doc/dev-guide-source/tutorials/chrome.md deleted file mode 100644 index bb1d4d28d6e4..000000000000 --- a/addon-sdk/source/doc/dev-guide-source/tutorials/chrome.md +++ /dev/null @@ -1,105 +0,0 @@ - - -
The API used to gain Chrome access is currently an
-experimental feature of the SDK, and may change in future releases.
-
-# Chrome Authority #
-
-## Using Chrome Authority ##
-
-The most powerful low-level modules are run with "chrome privileges",
-which gives them access to the infamous Components object, which
-grants unfettered access to the host system. From this, the module can do
-pretty much anything the browser is capable of. To obtain these privileges,
-the module must declare its intent with a statement like the following:
-
- var {Cc, Ci} = require("chrome");
-
-The object returned by require("chrome"), when unpacked with the
-"destructuring assignment" feature available in the Mozilla JS environment,
-will provide the usual Components.* aliases:
-
-**Cc**
-
-An alias for `Components.classes`.
-
-**Ci**
-
-An alias for `Components.interfaces`.
-
-**Cu**
-
-An alias for `Components.utils`.
-
-**Cr**
-
-An alias for `Components.results`.
-
-**Cm**
-
-An alias for `Components.manager`.
-
-**components**
-
-An alias for `Components` itself (note the lower-case). From this you can
-access less-frequently-used properties like `Components.stack` and
-`Components.isSuccessCode`.
-
-Note: the `require("chrome")` statement is the **only** way to access chrome
-functionality and the `Components` API. The `Components` object should
-**not** be accessed from modules. The SDK tools will emit a warning
-if it sees module code which references `Components` directly.
-
-Your modules should refrain from using chrome privileges unless they are
-absolutely necessary. Chrome-authority-using modules must receive extra
-security review, and most bugs in these modules are security-critical.
-
-## Manifest Generation ##
-
-The **manifest** is a list, included in the generated XPI, which
-specifies which modules have requested `require()` access to which other
-modules. It also records which modules have requested chrome access. This
-list is generated by scanning all included modules for `require(XYZ)`
-statements and recording the particular "XYZ" strings that they reference.
-
-When the manifest implementation is complete the runtime loader will actually
-prevent modules from `require()`ing modules that are not listed in the
-manifest. Likewise, it will prevent modules from getting chrome authority
-unless the manifest indicates that they have asked for it. This will ensure
-that reviewers see the same authority restrictions that are enforced upon the
-running code, increasing the effectiveness of the time spent reviewing the
-add-on. (until this work is complete, modules may be able to sneak around these
-restrictions).
-
-The manifest is built with a simple regexp-based scanner, not a full
-Javascript parser. Developers should stick to simple `require` statements,
-with a single static string, one per line of code. If the scanner fails to
-see a `require` entry, the manifest will not include that entry, and (once
-the implementation is complete) the runtime code will get an exception.
-
-For example, none of the following code will be matched by the manifest
-scanner, leading to exceptions at runtime, when the `require()` call is
-prohibited from importing the named modules:
-
- // all of these will fail!
- var xhr = require("x"+"hr");
- var modname = "xpcom";
- var xpcom = require(modname);
- var one = require("one"); var two = require("two");
-
-The intention is that developers use `require()` statements for two purposes:
-to declare (to security reviewers) what sorts of powers the module wants to
-use, and to control how those powers are mapped into the module's local
-namespace. Their statements must therefore be clear and easy to parse. A
-future manifest format may move the declaration portion out to a separate
-file, to allow for more fine-grained expression of authority.
-
-Commands that build a manifest, like "`cfx xpi`" or "`cfx run`", will scan
-all included modules for use of `Cc`/`Ci` aliases (or the expanded
-`Components.classes` forms). It will emit a warning if it sees the expanded
-forms, or if it sees a use of e.g. "`Cc`" without a corresponding entry in
-the `require("chrome")` statement. These warnings will serve to guide
-developers to use the correct pattern. All module developers should heed the
-warnings and correct their code until the warnings go away.
diff --git a/addon-sdk/source/doc/dev-guide-source/tutorials/display-a-popup.md b/addon-sdk/source/doc/dev-guide-source/tutorials/display-a-popup.md
deleted file mode 100644
index 70d8c7d37cc7..000000000000
--- a/addon-sdk/source/doc/dev-guide-source/tutorials/display-a-popup.md
+++ /dev/null
@@ -1,151 +0,0 @@
-
-
-# Display a Popup #
-
-
-To follow this tutorial you'll need to have
-[installed the SDK](dev-guide/tutorials/installation.html)
-and learned the
-[basics of `cfx`](dev-guide/tutorials/getting-started-with-cfx.html).
-
-
-To display a popup dialog, use the
-[`panel`](modules/sdk/panel.html) module. A panel's content is
-defined using HTML. You can run content scripts in the panel: although the
-script running in the panel can't directly access your main add-on code,
-you can exchange messages between the panel script and the add-on code.
-
-
-
-In this tutorial we'll create an add-on that
-[adds a widget to the toolbar](dev-guide/tutorials/adding-toolbar-button.html)
-which displays a panel when clicked.
-
-The panel just contains a
-`