Twoje pierwsze rozszerzenie

W tym artykule przejdziemy przez tworzenie rozszerzenia dla przeglądarki Firefox od początku do końca. Rozszerzenie to tylko dodaje czerwoną ramkę do stron załadowanych z "mozilla.org" lub dowolnej z jej poddomen.

Kod źródłowy dla tego przykładu znajduje się na GitHub'ie: https://github.com/mdn/webextensions-examples/tree/master/borderify.

Najpierw, będziesz potrzebować przeglądarki Firefox w wersji 45 lub nowszej.

Pisanie rozszerzenia

Stwórz nowy folder i przejdź do niego:

mkdir borderify
cd borderify

manifest.json

Teraz stwórz nowy plik o nazwie "manifest.json" bezpośrednio w katalogu "borderify". Wprowadź do niego poniższy kod:

{

  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Dodaje czerwoną ramkę we wszystkich stronach powiązanych z domeną mozilla.org.",

  "icons": {
    "48": "icons/border-48.png"
  },

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]

}
  • Pierwsze trzy klucze: manifest_version, name, oraz version, są obowiązkowe i zawierają podstawowe metadane dla rozszerzenia.
  • description jest opcjonalny, ale zalecany: jest on wyświetlany w menadżerze rozszerzeń.
  • icons jest opcjonalna, ale zalecana: pozwala ona nadać ikonę rozszerzeniu, która będzie wyświetlana w menadżerze rozszerzeń.

Najbardziej interesującym kluczem jest tutaj content_scripts, który mówi przeglądarce, który skrypt wczytać do stron internetowych, których adres spełnia określony wzór. W tym przypadku prosimy przeglądarkę o wczytanie skryptu o nazwie "borderify.js" na wszystkich stronach HTTP i HTTPS obsługiwanych przez domenę "mozilla.org" bądź jakąkolwiek jej poddomenę.

W niektórych sytuacjach musisz nadać ID swojemu rozszerzeniu. Jeśli potrzebujesz nadać rozszerzeniu ID, dołącz klucz applications do manifest.json i przypisz mu pole id:

"applications": {
  "gecko": {
    "id": "borderify@przyklad.pl"
  }
}

icons/border-48.png

Rozszerzenie powinno mieć ikonę. Będzie ona wyświetlona na liście dodatków w menadżerze rozszerzeń. Nasz manifest.json zapowiada, że będziemy mieć ikonę w "icons/border-48.png".

Stwórz folder "icons" bezpośrednio w katalogu "borderify". Zapisz tam ikonę o nazwie "border-48.png". Możesz użyć tej naszej przykładowej, która pochodzi ze zbioru ikon Google Material Design i jest używana zgodnie z warunkami licencji Creative Commons Attribution-ShareAlike.

Jeśli zdecydujesz się dodać własną ikonę, to powinna być w formacie 48x48 pikseli. Możesz także dodać ikonę o rozmiarze 96x96 pikseli dla ekranów o wysokiej rozdzielczości i jeśli dodasz ją, to powinna ona zostać przypisana jako wartość pola 96 obiektu icons 
w pliku manifest.json:

"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}

Ewentualnie możesz dodać plik SVG tutaj, więc zostanie on poprawnie przeskalowany. (Jeśli jednak używasz SVG, a twoja ikona zawiera napisy, możesz chcieć użyć narzędzia "przekonwertuj do ścieżki" w edytorze SVG, by spłaszczyć tekst, więc będzie skalowo dopasowany do położenia/rozmiaru).

borderify.js

Ostatecznie stwórz plik o nazwie "borderify.js" bezpośrednio w katalogu "borderify". Wpisz do niego poniższy kod:

document.body.style.border = "5px solid red";

Ten skrypt będzie załadowany na stronach spełniających wzór określony w kluczu content_scripts w pliku manifest.json. Skrypt ma bezpośredni dostęp do dokumentu, podobnie jak skrypty wczytane przez stronę.

Wypróbujmy

Najpierw dokładnie sprawdź, czy odpowiedne pliki są w właściwych miejsacach:

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json

Instalacja

Otwórz "about:debugging" w przeglądarce Firefox, kliknij "Załaduj tymczasową wtyczkę" i wybierz jakikolwiek plik z katalogu z Twoim rozszerzeniem:

Rozszerzenie zostanie teraz zainstalowane i pozostanie tam do momentu ponownego uruchomienia Firefoksa.

Alternatywnie, możesz także uruchomić swoje rozszerzenie za pomocą wiersza poleceń używając narzędzie web-ext.

Testowanie

Teraz spróbuj odwiedzić jakąś stronę należącą do "mozilla.org" i powinienieś zobaczyć czerwoną ramkę wokół strony:

Jednakże nie próbuj tego na addons.mozilla.org! Obecnie skrypty są blokowane na tej domenie.

Spróbuj trochę poeksperymentować. Edytuj zawartość skryptu by zmienić kolor ramki lub zrób coś innego z zawartością strony. Zapisz skrypt i przeładuj pliki rozszerzenia kilkając przycisk "Przeładuj" w about:debugging. Możesz zobaczyć zmiany odrazu:

Pakowanie i publikowanie

Aby inni użytkownicy mogli korzystać z Twojego rozszerzenia, musisz je zapakować i wysłać do Mozilli w celu podpisania go. 
Aby dowiedzieć się więcej, zajrzyj do artykułu "Publikowanie własnego rozszerzenia".

Co dalej?

Teraz gdy ty masz pomysł na temat procesu tworzenia rozszerzeń (WebExtension) dla Firefoxa, to spróbuj: