Bug 871350 - Uplift Add-on SDK integration branch to Firefox

Author: KWierso

addon-sdk/source/doc/dev-guide-source/guides/content-scripts/index.md

@@ -10,6 +10,9 @@ 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)**<br>
+Add items to the browser's context menu.
+
 **[panel](modules/sdk/panel.html)**<br>
 Create a dialog that can host web content.
 
@@ -19,12 +22,12 @@ Retrieve a page and access its content, without displaying it to the user.
 **[page-mod](modules/sdk/page-mod.html)**<br>
 Execute scripts in the context of selected web pages.
 
+**[tabs](modules/sdk/tabs.html)**<br>
+Manipulate the browser's tabs, including the web content displayed in the tab.
+
 **[widget](modules/sdk/widget.html)**<br>
 Host an add-on's user interface, including web content.
 
-**[context-menu](modules/sdk/context-menu.html)**<br>
-Add items to the browser's context menu.
-
 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

addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-port.md

@@ -79,7 +79,8 @@ 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` object. Thus
+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.
 
@@ -117,7 +118,8 @@ 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 associated with the page is
+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

addon-sdk/source/doc/dev-guide-source/guides/content-scripts/using-postmessage.md

@@ -39,7 +39,7 @@ function. Again, `panel` and `page` integrate `worker` directly:
     panel.postMessage(addonMessage);
 
 However, for `page-mod` objects you need to listen to the `onAttach` event
-and use the worker supplied to that:
+and use the [worker](modules/sdk/content/worker.html#Worker) supplied to that:
 
     var pageMod = require('sdk/page-mod').PageMod({
       include: ['*'],

addon-sdk/source/doc/dev-guide-source/tutorials/modifying-web-pages-tab.md

@@ -99,7 +99,8 @@ message from one side to the other, the sender calls `port.emit()` and
 the receiver listens using `port.on()`.
 
 * In the content script, `port` is a property of the global `self` object.
-* In the add-on script, `tab-attach()` returns an object containing the
+* In the add-on script, `tab.attach()` returns a 
+[worker](modules/sdk/content/worker.html#Worker) object containing the
 `port` property you use to send messages to the content script.
 
 Let's rewrite the example above to pass a message from the add-on to

addon-sdk/source/doc/dev-guide-source/tutorials/modifying-web-pages-url.md

@@ -146,7 +146,8 @@ the receiver listens using `port.on()`.
 
 * In the content script, `port` is a property of the global `self` object.
 * In the add-on script, you need to listen for the `onAttach` event to get
-passed an object that contains `port`.
+passed a [worker](modules/sdk/content/worker.html#Worker) object that
+contains `port`.
 
 Let's rewrite the example above to pass a message from the add-on to
 the content script. The message will contain the new content to insert into

addon-sdk/source/doc/module-source/sdk/content/worker.md

@@ -7,8 +7,8 @@
 This module is used in the internal implementation of SDK modules
 which use
 [content scripts to interact with web content](dev-guide/guides/content-scripts/index.html),
-such as the [`panel`](modules/sdk/panel.html) or [`page-mod`](modules/sdk/page-mod.html)
-modules.
+such as the [`tabs`](modules/sdk/tabs.html), [`panel`](modules/sdk/panel.html),
+or [`page-mod`](modules/sdk/page-mod.html) modules.
 
 It exports the `Worker` trait, which enables content
 scripts and the add-on code to exchange messages using the
@@ -121,14 +121,27 @@ error that occurs in one of the content scripts.
 
 @argument {Error}
 The event listener is passed a single argument which is an
-[Error](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error)
+[Error](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error)
 object.
 </api>
 
 <api name="detach">
 @event
 This event is emitted when the document associated with this worker is unloaded
 or the worker's `destroy()` method is called.
+
+Note that you can't communicate with the content script in response to this
+event. If you try, you'll see this error:
+
+<pre>Error: Couldn't find the worker to receive this message.
+The script may not be initialized yet, or may already have been unloaded</pre>
+
+You can handle the `detach` event in the content script itself though:
+
+    // in content script
+    self.on("detach", function() {
+      window.close();
+    });
 </api>
 
 </api>

addon-sdk/source/doc/module-source/sdk/places/favicon.md

@@ -0,0 +1,48 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+The `places/favicon` module provides simple helper functions for working with favicons.
+
+<api name="getFavicon">
+@function
+Takes an `object` that represents a page's URL and returns a promise
+that resolves with the favicon URL for that page. The `object` can
+be a URL `String` or a [`Tab`](modules/sdk/tabs.html#Tab). The platform service
+([mozIAsyncFavicons](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/mozIAsyncFavicons)) retrieves favicon data stored from previously visited sites, and as
+such, will only return favicon URLs for visited sites.
+
+    let { getFavicon } = require("sdk/places/favicon");
+
+    // String example
+    getFavicon("http://mozilla.org").then(function (url) {
+      console.log(url); // http://mozorg.cdn.mozilla.net/media/img/favicon.ico
+    });
+
+    // Tab example
+    require("sdk/tabs").open({
+      url: "http://mozilla.org",
+      onReady: function (tab) {
+        getFavicon(tab).then(function (url) {
+          console.log(url); // http://mozorg.cdn.mozilla.net/media/img/favicon.ico
+        });
+      }
+    });
+
+    // An optional callback can be provided to handle
+    // the promise's resolve and reject states
+    getFavicon("http://mozilla.org", function (url) {
+      console.log(url); // http://mozorg.cdn.mozilla.net/media/img/favicon.ico
+    });
+
+@param object {string, tab}
+  A value that represents the URL of the page to get the favicon URL from.
+  Can be a URL `String` or a [`Tab`](modules/sdk/tabs.html#Tab).
+
+@param callback {function}
+  An optional callback function that will be used in both resolve and
+  reject cases.
+
+@returns {promise}
+  A promise that resolves with the favicon URL.
+</api>

addon-sdk/source/doc/module-source/sdk/tabs.md

@@ -55,7 +55,8 @@ property you can load a new page in the tab:
 
 You can attach a [content script](dev-guide/guides/content-scripts/index.html)
 to the page hosted in a tab, and use that to access and manipulate the page's
-content:
+content (see the
+[Modifying the Page Hosted by a Tab](dev-guide/tutorials/modifying-web-pages-tab.html) tutorial):
 
     var tabs = require("sdk/tabs");
 
@@ -213,6 +214,12 @@ This property can be set to load a different URL in the tab.
 @property {string}
 The URL of the favicon for the page currently loaded in the tab.
 This property is read-only.
+
+<div class="warning">
+  This property is deprecated.
+  From version 1.15, use the <a href="modules/sdk/places/favicon.html#getFavicon()">favicon module's <code>getFavicon()</code></a> function instead.
+</div>
+
 </api>
 
 <api name="contentType">
@@ -312,8 +319,10 @@ Returns thumbnail data URI of the page currently loaded in this tab.
     content script. Optional.
 
 @returns {Worker}
+  The [Worker](modules/sdk/content/worker.html#Worker) object can be used to
+  communicate with the content script.
   See [Content Scripts guide](dev-guide/guides/content-scripts/index.html)
-  to learn how to use the `Worker` object to communicate with the content script.
+  to learn the details.
 
 </api>
 

addon-sdk/source/lib/sdk/io/data.js

@@ -10,43 +10,18 @@ module.metadata = {
 
 const { Cc, Ci, Cu } = require("chrome");
 const base64 = require("../base64");
-const { defer } = require("../core/promise");
-const { newURI } = require("../url/utils");
-
 const IOService = Cc["@mozilla.org/network/io-service;1"].
   getService(Ci.nsIIOService);
 
 const { deprecateFunction } = require('../util/deprecate');
 const { NetUtil } = Cu.import("resource://gre/modules/NetUtil.jsm");
 const FaviconService = Cc["@mozilla.org/browser/favicon-service;1"].
                           getService(Ci.nsIFaviconService);
-const AsyncFavicons = FaviconService.QueryInterface(Ci.mozIAsyncFavicons);
 
 const PNG_B64 = "data:image/png;base64,";
 const DEF_FAVICON_URI = "chrome://mozapps/skin/places/defaultFavicon.png";
 let   DEF_FAVICON = null;
 
-/**
- * Takes URI of the page and returns a promise that resolves
- * to the page's favicon URI.
- * @param {String} uri
- * @param {Function} (callback)
- * @returns {Promise}
- */
-
-exports.getFavicon = function getFavicon(uri, callback) {
-  let pageURI = newURI(uri);
-  let deferred = defer();
-  AsyncFavicons.getFaviconURLForPage(pageURI, function (aURI) {
-    if (aURI && aURI.spec)
-      deferred.resolve(aURI.spec.toString());
-    else
-      deferred.reject(null);
-  });
-  if (callback) deferred.promise.then(callback, callback);
-  return deferred.promise;
-};
-
 /**
  * Takes URI of the page and returns associated favicon URI.
  * If page under passed uri has no favicon then base64 encoded data URI of

addon-sdk/source/lib/sdk/places/favicon.js

@@ -0,0 +1,45 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+module.metadata = {
+  "stability": "unstable"
+};
+
+const { Cc, Ci, Cu } = require("chrome");
+const { defer, reject } = require("../core/promise");
+const FaviconService = Cc["@mozilla.org/browser/favicon-service;1"].
+                          getService(Ci.nsIFaviconService);
+const AsyncFavicons = FaviconService.QueryInterface(Ci.mozIAsyncFavicons);
+const { isValidURI } = require("../url");
+const { newURI, getURL } = require("../url/utils");
+
+/**
+ * Takes an object of several possible types and
+ * returns a promise that resolves to the page's favicon URI.
+ * @param {String|Tab} object
+ * @param {Function} (callback)
+ * @returns {Promise}
+ */
+
+function getFavicon (object, callback) {
+  let url = getURL(object);
+  let deferred = defer();
+
+  if (url && isValidURI(url)) {
+    AsyncFavicons.getFaviconURLForPage(newURI(url), function (aURI) {
+      if (aURI && aURI.spec)
+        deferred.resolve(aURI.spec.toString());
+      else
+        deferred.reject(null);
+    });
+  } else {
+    deferred.reject(null);
+  }
+
+  if (callback) deferred.promise.then(callback, callback);
+  return deferred.promise;
+}
+exports.getFavicon = getFavicon;