691536 - Clarify tab.attach() to explain how to use its return value

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P2)

Description

[Will Bamberg [:wbamberg]]

See: https://groups.google.com/forum/#!msg/mozilla-labs-jetpack/T5AWgYnT63o/kazLFCxqljUJ

The documentation for tab.attach should explain that it returns a worker object which you can use to communicate with the content script. The example should also include this.

Comment 1

[Will Bamberg [:wbamberg]]

Attachment: Added stuff on tab.attach returning a worker; included example

Comment 2

[Alexandre Poirot [:ochameau]]

Comment on attachment 569721 [details] [diff] [review]
Added stuff on tab.attach returning a worker; included example

The example expose a really bad practice that would create an useless worker for each opened document. 
You are trying to show a really common usecase with widget, where you want to evaluate a content script only for one particular tab, the current one.

In order to do so, you will write something like this:

var fetchContent = "self.postMessage(document.body.innerHTML);";

var widget = widgets.Widget({
  id: "fetch-content",
  label: "Fetch content",
  contentURL: "http://www.mozilla.org/favicon.ico",
  onClick: function() {
    require("tabs").activeTab.attach({
      contentScript: fetchContent,
      onMessage: function (message) {
        console.log(message);
      }
    });
  }
});

I removed worker usage as it will be unecessarry in most cases. 
But this example is really usefull as it will be really common, so if you have an idea of worker/postMessage/onMessage usage on top of it, it would be perfect!

Comment 3

[Will Bamberg [:wbamberg]]

Do you think this: https://builder.addons.mozilla.org/addon/1041869/latest/ is a better example? It's slightly long, and related to one of the new tutorials, so it might be better to include it in a tutorial rather than the API doc.

Comment 4

[Erik Vold [:erikvold] (please needinfo? me)]

This is explained in https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/tabs#attach%28options%29 now