-Error: Couldn't find the worker to receive this message. The script may not be initialized yet, or may already have been unloaded. -- -So code like this, where we create a panel and then -synchronously send it a message using `postMessage()`, will not work: - - var data = require("sdk/self").data; - - var panel = require("sdk/panel").Panel({ - contentURL: "http://www.bbc.co.uk/mobile/index.html", - contentScriptFile: data.url("panel.js") - }); - - panel.postMessage("hi from main.js"); - -[`port.emit()`](dev-guide/guides/content-scripts/using-port.html) -queues messages until the content script is ready to receive them, -so the equivalent code using `port.emit()` will work: - - var data = require("sdk/self").data; - - var panel = require("sdk/panel").Panel({ - contentURL: "http://www.bbc.co.uk/mobile/index.html", - contentScriptFile: data.url("panel.js") - }); - - panel.port.emit("hi from main.js"); - - ## Message Events Versus User-Defined Events ## You can use message events as an alternative to user-defined events: diff --git a/addon-sdk/source/doc/dev-guide-source/guides/events.md b/addon-sdk/source/doc/dev-guide-source/guides/events.md index 9e5f051b8446..735ceaefd6a5 100644 --- a/addon-sdk/source/doc/dev-guide-source/guides/events.md +++ b/addon-sdk/source/doc/dev-guide-source/guides/events.md @@ -51,19 +51,15 @@ is specific to an event emitter and is included with its documentation. whenever the event occurs. The arguments that will be passed to the listener are specific to an event type and are documented with the event emitter. -For example, the following add-on registers two listeners with the -[`private-browsing`](modules/sdk/private-browsing.html) module to -listen for the `start` and `stop` events, and logs a string to the console -reporting the change: +For example, the following add-on registers a listener with the +[`tabs`](modules/sdk/tabs.html) module to +listen for the `ready` event, and logs a string to the console +reporting the event: - var pb = require("sdk/private-browsing"); + var tabs = require("sdk/tabs"); - pb.on("start", function() { - console.log("Private browsing is on"); - }); - - pb.on("stop", function() { - console.log("Private browsing is off"); + tabs.on("ready", function () { + console.log("tab loaded"); }); It is not possible to enumerate the set of listeners for a given event. @@ -73,9 +69,8 @@ the event. ### Adding Listeners in Constructors ### -Event emitters may be modules, as is the case for the -`private-browsing` events, or they may be objects returned by -constructors. +Event emitters may be modules, as is the case for the `ready` event +above, or they may be objects returned by constructors. In the latter case the `options` object passed to the constructor typically defines properties whose names are the names of supported event types prefixed @@ -126,28 +121,36 @@ supplying the type of event and the listener to remove. The listener must have been previously been added using one of the methods described above. -In the following add-on, we add two listeners to private-browsing's `start` -event, enter and exit private browsing, then remove the first listener and -enter private browsing again. +In the following add-on, we add two listeners to the +[`tabs` module's `ready` event](modules/sdk/tabs.html#ready). +One of the handler functions removes the listener again. - var pb = require("sdk/private-browsing"); +Then we open two tabs. + + var tabs = require("sdk/tabs"); function listener1() { console.log("Listener 1"); - pb.removeListener("start", listener1); + tabs.removeListener("ready", listener1); } function listener2() { console.log("Listener 2"); } - pb.on("start", listener1); - pb.on("start", listener2); + tabs.on("ready", listener1); + tabs.on("ready", listener2); - pb.activate(); - pb.deactivate(); - pb.activate(); + tabs.open("https://www.mozilla.org"); + tabs.open("https://www.mozilla.org"); -Removing listeners is optional since they will be removed in any case -when the application or add-on is unloaded. +We should see output like this: + +
+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/package-spec.md b/addon-sdk/source/doc/dev-guide-source/package-spec.md index 039578ef5e0d..d99cef998b66 100644 --- a/addon-sdk/source/doc/dev-guide-source/package-spec.md +++ b/addon-sdk/source/doc/dev-guide-source/package-spec.md @@ -2,124 +2,221 @@ - 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/. --> -# Package Specification # +# package.json # -A *package* is a directory that, at minimum, contains a JSON file -called `package.json`. This file is also referred to as the -*package manifest*. +The "package.json" file contains metadata for your add-on. -## The Package Manifest ## +Some of its entries, such as [`icon`](dev-guide/package-spec.html#icon), +[`name`](dev-guide/package-spec.html#name), and +[`description`](dev-guide/package-spec.html#description), have +direct analogues in the +[install manifest](https://developer.mozilla.org/en-US/docs/Install_Manifests) +format, and entries from package.json are written into the install +manifest when the add-on is built using [`cfx xpi`](dev-guide/cfx-tool.html#cfx xpi). + +Others, such as +[`lib`](dev-guide/package-spec.html#lib), +[`permissions`](dev-guide/package-spec.html#permissions), +and [`preferences`](dev-guide/package-spec.html#preferences), +represent instructions to the cfx tool itself to generate and include +particular code and data structures in your add-on. + +The `package.json` file is initially generated in your add-on's root +directory the first time you run +[`cfx init`](dev-guide/cfx-tool.html#cfx init). It looks like this +(assuming the add-on's directory is "my-addon"): + +
+{
+ "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:
-* `name` - the name of the package. The package system will only load
- one package with a given name. This name cannot contain spaces or periods.
- The name defaults to the name of the parent directory. If the package is
- ever built as an XPI and the `fullName` key is not present, this is
- used as the add-on's `em:name` element in its `install.rdf`.
+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
- `lib`. Defaults to `"main"`.
+ |
+
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
+ |
+
activate
-and deactivate
-functions, isActive
-property, start,
-and stop
-events are all
-now deprecated due to per-window private browsing. They will continue to work
-until version 1.13 of the SDK. From version 1.13 onwards they will still exist
-but will have no effect when called.
-"permissions": {"private-browsing": true}
+
+If an add-on has not opted in, then the high-level SDK modules will not
+expose private windows, or objects (such as tabs) that are associated
+with private windows:
+
+* the [`windows`](modules/sdk/windows.html) module will not list any
+private browser windows, generate any events for private browser windows,
+or let the add-on open any private browser windows
+
+* the [`tabs`](modules/sdk/tabs.html) module will not list any tabs that
+belong to private browser windows, and the add-on won't receive any events
+for such tabs
+
+* any [`widgets`](modules/sdk/widget.html) will not be displayed in
+private browser windows
+
+* any menus or menu items created using the
+[`context-menu`](modules/sdk/context-menu.html) will not be shown in
+context menus that belong to private browser windows
+
+* the [`page-mod`](modules/sdk/page-mod.html) module will not attach
+content scripts to documents belonging to private browser windows
+
+* any [`panel`](modules/sdk/panel.html) objects will not be shown if the
+active window is a private browser window
+
+* the [`selection`](modules/sdk/selection.html) module will not include
+any selections made in private browser windows
+
+Add-ons that have opted in:
+
+* will see private windows, so they will need to
+use the `private-browsing` module to check whether objects are private,
+so as to avoid storing data derived from such objects.
+
+* will not be able to use panels in their code. This is due to a platform
+restriction which will be fixed in Firefox 21.
+
+Additionally, add-ons that use low-level modules such as
+[`window/utils`](modules/sdk/window/utils.html) may see private browser
+windows with certain functions, even if they have not explicitly opted
+into private browsing.
+
+## Respecting private browsing ##
+
+The `private-browsing` module exports a single function
+[`isPrivate()`](modules/sdk/private-browsing.html#isPrivate(object))
+that takes an object, which may be a
+[`BrowserWindow`](modules/sdk/windows.html#BrowserWindow),
+[`tab`](modules/sdk/tabs.html#Tab), or
+[`worker`](modules/sdk/content/worker.html#Worker),
+as an argument. It returns `true` only if the object is:
+
+* a private window, or
+* a tab belonging to a private window, or
+* a worker that's associated with a document hosted in a private window
+
+Add-ons can use this API to decide whether or not to store user data.
+For example, here's an add-on that stores the titles of tabs the user loads,
+and uses `isPrivate()` to exclude the titles of tabs that were loaded into
+private windows:
+
+ var simpleStorage = require("simple-storage");
+
+ if (!simpleStorage.storage.titles)
+ simpleStorage.storage.titles = [];
+
+ require("tabs").on("ready", function(tab) {
+ if (!require("private-browsing").isPrivate(tab)) {
+ console.log("storing...");
+ simpleStorage.storage.titles.push(tab.title);
+ }
+ else {
+ console.log("not storing, private data");
+ }
+ });
+
+Here's an add-on that uses a [page-mod](modules/sdk/page-mod.html) to log
+the content of pages loaded by the user, unless the page is private. In
+the handler for the page-mod's [`attach`](modules/sdk/page-mod.html#attach)
+event, it passes the worker into `isPrivate()`:
+
+ var pageMod = require("sdk/page-mod");
+ var privateBrowsing = require("sdk/private-browsing");
+
+ var loggingScript = "self.port.on('log-content', function() {" +
+ " console.log(document.body.innerHTML);" +
+ "});";
+
+ function logPublicPageContent(worker) {
+ if (privateBrowsing.isPrivate(worker)) {
+ console.log("private window, doing nothing");
+ }
+ else {
+ worker.port.emit("log-content");
+ }
+ }
+
+ pageMod.PageMod({
+ include: "*",
+ contentScript: loggingScript,
+ onAttach: logPublicPageContent
+ });
+
+## Tracking private-browsing exit ##
+
+Sometimes it can be useful to cache some data from private windows while they
+are open, as long as you don't store it after the private browsing windows
+have been closed. For example, the "Downloads" window might want to display
+all downloads while there are still some private windows open, then clean out
+all the private data when all private windows have closed.
+
+To do this with the SDK, you can listen to the system event named
+"last-pb-context-exited":
+
+ var events = require("sdk/system/events");
+
+ function listener(event) {
+ console.log("last private window closed");
+ }
+
+ events.on("last-pb-context-exited", listener);
+
+## Working with Firefox 19 ##
+
+In Firefox 19, private browsing is a global property for the entire browser.
+When the user enters private browsing, the existing browsing session is
+suspended and a new blank window opens. This window is private, as are any
+other windows opened until the user chooses to exit private browsing, at which
+point all private windows are closed and the user is returned to the original
+non-private session.
+
+When running on Firefox 19, `isPrivate()` will return true if and only if
+the user has global private browsing enabled.
require("private-browsing").isPrivate(browserWindow)
+ From version 1.14, use the private-browsing module's isPrivate() function instead.