Content Scripts

Sie können ein einzelnes Skript laden, indem Sie einen String an die contentScript oder die contentScriptFile Option übergeben. Die contentScript Option behandelt den übergebenen String wie ein eigenes Skript:

// main.js

var pageMod = require("sdk/page-mod");
var contentScriptValue = 'document.body.innerHTML = ' +
                         ' "<h1>Page matches ruleset</h1>";';

pageMod.PageMod({
  include: "*.mozilla.org",
  contentScript: contentScriptValue
});

Die contentScriptFile Option behandelt den String wie eine resource:// URL, die auf ein Skript zeigt, dass in ihrem Add-on Verzeichnis "data" gespeichert ist. jpm erstellt standardmäßig keinen "data" Ordner, also muss dieser erst erstellt werden, wenn Sie ihre Content Scripts verwenden wollen.

Das Add-on liefert eine URL, die auf die Datei "content-script.js" zeigt, welche im data Unterordner des Add-on Stammverzeichnisses enthalten ist:

// main.js

var data = require("sdk/self").data;
var pageMod = require("sdk/page-mod");

pageMod.PageMod({
  include: "*.mozilla.org",
  contentScriptFile: data.url("content-script.js")
});

// content-script.js

document.body.innerHTML = "<h1>Seite erfüllt die Regeln.</h1>";

var pageMod = require("sdk/page-mod");

pageMod.PageMod({
  include: "*.mozilla.org",
  contentScriptFile: "./content-script.js"
});

Sie können auch mehrere Skripte in contentScript oder contentScriptFile laden, indem Sie ein Array von Strings übergeben:

// main.js

var tabs = require("sdk/tabs");

tabs.on('ready', function(tab) {
  tab.attach({
      contentScript: ['document.body.style.border = "5px solid red";', 'window.alert("hi");']
  });
});

// main.js

var data = require("sdk/self").data;
var pageMod = require("sdk/page-mod");

pageMod.PageMod({
  include: "*.mozilla.org",
  contentScriptFile: [data.url("jquery.min.js"), data.url("my-content-script.js")]
});

Wenn Sie das tuen, können die Skripte direkt miteinander kommunizieren, als wären es Skripte der gleichen Webseite.

Sie können auch contentScript und contentScriptFile zusammen benutzen. Wenn Sie das tun, werden die Skripte, die sie in contentScriptFile spezifizieren vor denen in contentScript geladen. Das ermöglicht es Ihnen javaScript Bibliotheken, wie JQuery über eine URL zu laden und dann ein simples Skript inline zu verwenden, dass diese Bibliothek benutzt:

// main.js

var data = require("sdk/self").data;
var pageMod = require("sdk/page-mod");

var contentScriptString = '$("body").html("<h1>Page matches ruleset</h1>");';

pageMod.PageMod({
  include: "*.mozilla.org",
  contentScript: contentScriptString,
  contentScriptFile: data.url("jquery.js")
});

Kontrollieren, wann das Skript angehängt werden soll.

Die contentScriptWhen Option spezifiziert, wann das/die Content Skript/e geladen werden sollen. Diese brauch eine dieser Parameter:

• "start": Läd das Skript sofort, nach dem das Dokumentelement der Seite in den DOM eingefügt wird. ZU diesem Zeitpunkt wurde der DOM Inhalt noch nicht geladen,, deshalb kann das Skript nicht damit interagieren.
• "ready": Läd das Skript nachdem der DOM der Seite geladen wurde: Dies ist der Fall, wenn das DOMContentLoaded Event  abgefeuert wird. Ab diesem Zeitpunkt können Content Skripts mit dem DOM interagieren, aber extern referenzierte Stylesheets und Bilder könnten noch nicht geladen sein.
• "end": Läd das Skript nachdem der komplette Inhalt (DOM, JS, CSS, images) der Seute geladen wurde. Zu diesem Zeitpunkt wird das window.onload event abgefeuert.

Der Standardwert ist "end".

Die Funktion tab.attach() akzepiert contentScriptWhen nicht, da es generell aufgerufen wird wenn die Seite geladen wurde.

Übergabe von Konfigurationsoptionen

Das contentScriptOptions Objekt ist ein JSON Objekt, das den Content Skripts als "read-only" Wert als self.options Eigenschaft übergeben wird:

// main.js

var tabs = require("sdk/tabs");

tabs.on('ready', function(tab) {
  tab.attach({
      contentScript: 'window.alert(self.options.message);',
      contentScriptOptions: {"message" : "hello world"}
  });
});

Jeder Wert (Objekt, Feld, String, etc), dass in JSON dargestellt werden kann, kann hier benutzt werden.

Zugriff auf den DOM

Content Skripts können natürlich wie jedes andere Skript, dass die Seite geladen hat ( Page Skripts) auf den DOM zugreifen. Content Skripts und Page Skripts sind wie folgt von einander isoliert:

• Content Skripts sehen keine JavaScript Objekte, die der Seite über Page Skripts hinzugefügt wurden.
• Auch wenn ein Page Skript das Verhalten eines DOM Objekts verändert hat, sieht das Content Skript nur das Originalverhalten.

Das gleiche gilt auch umgekehrt: Page Skripts sehen keine JavaScript Objekte, die von Content Skripts hinzugefügt wurden.

Stellen Sie sich eine Seite vor, die zum Beispiel eine Variable foo über ein Page Skript zum window Objekt hinzufügt:

<!DOCTYPE html">
<html>
  <head>
    <script>
    window.foo = "hello from page script"
    </script>
  </head>
</html>

Ein anderes Skript, dass nach diesem Skript in die Seite geladen wird, kann auf foo zugreifen. Ein Content Skript kann dies nicht:

// main.js

var tabs = require("sdk/tabs");
var mod = require("sdk/page-mod");
var self = require("sdk/self");

var pageUrl = self.data.url("page.html")

var pageMod = mod.PageMod({
  include: pageUrl,
  contentScript: "console.log(window.foo);"
})

tabs.open(pageUrl);

console.log: my-addon: null

Es gibt gute Gründe für diese Isolation. Erstens können Content Skripts so keine Objekte an Webseiten übermitteln und somit Sicherheitslücken schaffen. Zweitens können Content Skripts so Objekte erzeugen, ohne sich Sorgen machen zu müssen, dass diese mit Objekten kollidieren, die in Page Skripts erzeugt wurden.

Die Isulation bedeutet, dass wenn zum Beispiel eine Webseite die JQuery Bibliothek läd, das Content Skript nicht in der Lage ist dieses zu sehen, aber eine eigene JQuery Bibliothek laden kann ohne das es ein Problem mit der Version gibt, die über das Page Skript hinzugefügt wurde.

Interaktion mit Page Skripts

Normalerweise möchte man Content Skripts und Page Skripts voneinander isolieren. Wenn dies nicht der Fall ist, da Sie zum Beispiel Objekte zwischen beiden Skripten austauschen wollen, oder Nachrichten zwischen ihnen schicken wollen können Sie mehr zum Thema unter  Interaktion mit Page Skripts finden.

Event Listeners

Man kann in Content Skripts genau wie in einem Page Skript auf DOM Events warten. Es gibt nur zwei wichtige Unterschieden:

Erstens: Falls Sie einen Event Listener als String an setAttribute() übergeben, wird der Listener im Seitenkontext ausgeführt und hat somit keinen Zugriff auf Variablen, die im Content Skript definiert wurden.

Zum Beispiel, wird dieses Content Skript mit der Fehlermeldung "theMessage is not defined" ausgeben:

var theMessage = "Hello from content script!";
anElement.setAttribute("onclick", "alert(theMessage);");

Zweitens: Falls Sie einen Event Listener per direkter Zuweisung einem globalen Event Handler  wie onclick zuweisen, könnten Zuweisungen, die die Seite vornimmt überschrieben werden. Zur Veranschaulichung ist hier ein Add-on, das versucht einen click Handler per Zuweisung an window.onclick anzufügen:

var myScript = "window.onclick = function() {" +
               "  console.log('unsafewindow.onclick: ' + window.document.title);" +
               "}";

require("sdk/page-mod").PageMod({
  include: "*",
  contentScript: myScript,
  contentScriptWhen: "start"
});

Das wird auf den meisten Seiten funktionieren, bis auf denen, die ebenfalls ein onclick zuweisen:

<html>
  <head>
  </head>
  <body>
    <script>
    window.onclick = function() {
      window.alert("it's my click now!");
    }
    </script>
  </body>
</html>

Aus diesen Gründen ist es besser Event Listeners per addEventListener() hinzuzufügen. So definieren Sie einen Listener als Funktion:

var theMessage = "Hello from content script!";

anElement.onclick = function() {
  alert(theMessage);
};

anotherElement.addEventListener("click", function() {
  alert(theMessage);
});

Kommunikation mit dem Add-on

Damit Add-On Sktipts und Content Skripts miteinander kommunizieren können, haben beide Seiten der Konversation Zugriff auf ein port Objekt.

• Um eine Nachricht von einer Seite zur anderen zu schicken nutzen Sie port.emit()
• Um eine Nachricht von der anderen Seite zu empfangen nutzen port.on()

Nachrichten sind asyncron, was bedeutet, dass der Sender nicht wartet, bis er eine Antwort des Empfängers erhält, sondern die Nachricht schickt und das weiter arbeitet.

Hier ist ein simples Beispieladd-on, das eine Nachricht an ein Content Skript per port schickt:

// main.js

var tabs = require("sdk/tabs");
var self = require("sdk/self");

tabs.on("ready", function(tab) {
  worker = tab.attach({
    contentScriptFile: self.data.url("content-script.js")
  });
  worker.port.emit("alert", "Message from the add-on");
});

tabs.open("https://www.mozilla.org");

// content-script.js

self.port.on("alert", function(message) {
  window.alert(message);
});

Zugriff auf port im Content Skript

Im Content Skript ist das port Objekt als Eigenschaft im globalen Objekt self verfügbar. So versenden Sie eine Nachricht vom Content Skript:

self.port.emit("myContentScriptMessage", myContentScriptMessagePayload);

Um eine Nachricht vom Add-on Code zu bekommen:

self.port.on("myAddonMessage", function(myAddonMessagePayload) {
  // Handle the message
});

Zugriff auf port im Add-on Skript

Im Add-on Code ist das Bindeglied zur Kommunikation zwischen Add-on und einem spezifischen Content Skript das  worker Objekt. Das port Objekt ist also eine Eigenschaft des  worker Objekts.

Der worker wird aber im Add-on Code nicht von allen Modulen gleich verwendet.

Vom page-worker

Das page-worker Objekt integriert die worker API direkt. Um also eine Nachricht von einem Content Skript zu erhalten, das mit dem page-worker assoziiert wird benutzt man pageWorker.port.on():

// main.js

var pageWorkers = require("sdk/page-worker");
var self = require("sdk/self");

var pageWorker = require("sdk/page-worker").Page({
  contentScriptFile: self.data.url("content-script.js"),
  contentURL: "https://en.wikipedia.org/wiki/Internet"
});

pageWorker.port.on("first-para", function(firstPara) {
  console.log(firstPara);
});

Um eine benutzerdefinierte Nachricht vom Add-on zu schicken, nutz man pageWorker.port.emit():

// main.js

var pageWorkers = require("sdk/page-worker");
var self = require("sdk/self");

pageWorker = require("sdk/page-worker").Page({
  contentScriptFile: self.data.url("content-script.js"),
  contentURL: "https://en.wikipedia.org/wiki/Internet"
});

pageWorker.port.on("first-para", function(firstPara) {
  console.log(firstPara);
});

pageWorker.port.emit("get-first-para");

// content-script.js

self.port.on("get-first-para", getFirstPara);

function getFirstPara() {
  var paras = document.getElementsByTagName("p");
  if (paras.length > 0) {
    var firstPara = paras[0].textContent;
    self.port.emit("first-para", firstPara);
  }
}

Vom page-mod

Ein einziges  page-mod Objekt kann ein Skript an mehrere Seiten anhängen. Jede dieser Seiten hat ihren eigenen Context, in dem sie dieses Skript aufrufen. Daher benötigt es seperate Kanäle(worker) für jede Seite.

page-mod integriert also die worker API nicht direkt, sondern es wird jedes Mal wenn ein Content Skript an eine Seite angehängt wird das attach Event aufgerufen,  dessen listener einen worker für den Kontext übergeben bekommt. Durch das bereit stellen eines listeners bei attach kann man das port Objekt für das Content Skript, dass dieser Seite angefügt wurde über diesen page-mod verwenden:

// main.js

var pageMods = require("sdk/page-mod");
var self = require("sdk/self");

var pageMod = pageMods.PageMod({
  include: ['*'],
  contentScriptFile: self.data.url("content-script.js"),
  onAttach: startListening
});

function startListening(worker) {
  worker.port.on('click', function(html) {
    worker.port.emit('warning', 'Do not click this again');
  });
}

// content-script.js

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);
});

Im oben gezeigten Add-on gibt es zwei Nachrichten:

• click wird vom page-mod an das Add-on geschickt, wenn der Nutzer auf ein Element auf der Seite klickt
• warning schickt einen String zurück an den page-mod

Von Tab.attach()

Die Tab.attach() methode liefert einen worker zurück, den man zur Kommunikation mit dem/den Content Skript/Content Skripts, die angehängt wurden, verwenden kann.

Das Add-on fügt einen Button zu Firefox hinzu: Wenn der Benutzer den Button drückt, fügt das Add-on ein Content Skript an den aktuellen Tab an. Das Skript sendet eine Nachricht namens "my-addon-message" und wartet auf eine Antwort namens "my-script-response":

//main.js

var tabs = require("sdk/tabs");
var buttons = require("sdk/ui/button/action");
var self = require("sdk/self");

buttons.ActionButton({
  id: "attach-script",
  label: "Attach the script",
  icon: "./icon-16.png",
  onClick: attachScript
});

function attachScript() {
  var worker = tabs.activeTab.attach({
    contentScriptFile: self.data.url("content-script.js")
  });
  worker.port.on("my-script-response", function(response) {
    console.log(response);
  });
  worker.port.emit("my-addon-message", "Message from the add-on");
}

// content-script.js

self.port.on("my-addon-message", handleMessage);

function handleMessage(message) {
  alert(message);
  self.port.emit("my-script-response", "Response from content script");
}

Die port API

Schaue unter der Referenzseite für das port Objekt.