Tworzymy rozszerzenie

Wprowadzenie

Ten przewodnik przeprowadzi Cię przez kilka kroków potrzebnych do stworzenia bardzo prostego rozszerzenia, które doda do Firefoksa panel na pasku statusu z tekstem "Witaj Świecie!"

Uwaga! Ten artykuł dotyczy tworzenia rozszerzenia dla Firefoksa 1.5 i późniejszych. Istnieją także przewodniki na temat budowy rozszerzeń dla starszych wersji Firefoksa.

Przygotowanie środowiska programowania

Rozszerzenia są spakowane i rozpowszechniane w plikach ZIP lub paczkach z rozszerzeniem pliku xpi (wymawiane jak “zippy”). Układ zawartości wewnątrz pliku XPI może wyglądać następująco:

extension.xpi:
              /install.rdf
              /components/*
              /components/cmdline.js
              /defaults/
              /defaults/preferences/*.js
              /plugins/*
              /chrome.manifest
              /chrome/icons/default/*
              /chrome/
              /chrome/content/

Z tego powodu najłatwiej będzie układać pliki źródłowe w podobny sposób, chyba że chcesz napisać coś w stylu pliku Makefile lub skryptu powłoki, aby spakować wszystkie swoje pliki. Nawet, jeśli jesteś gotów to zrobić, testowanie rozszerzenia będzie znacznie łatwiejsze, jeśli ułożysz swoje pliki w powyższy sposób, ze względu na sposób pracy systemu Dodatków Firefoksa 1.5.

Zaczynajmy. Utwórz gdzieś na swoim dysku folder dla Twojego rozszerzenia, np. C:\extensions\my_extension\ lub ~/extensions/my_extension/. (Uwaga: Używaj tylko małych liter) Wewnątrz tego folderu tworzymy kolejny o nazwie chrome, następnie wewnątrz chrome tworzymy folder content. (W systemach Uniksowych można zazwyczaj stworzyć wszystkie trzy foldery za pomocą polecenia mkdir -p chrome/content wydanego w głównym katalogu rozszerzenia.)

Wewnątrz głównego folderu rozszerzenia, obok folderu chrome, tworzymy dwa puste pliki tekstowe: chrome.manifest oraz install.rdf.

Przykładowo:

#!/bin/sh
h=$HOME/moExt
mkdir -p $h/my_extension/chrome/content
touch $h/my_extension/chrome.manifest $h/my_extension/install.rdf

Więcej wskazówek na temat tego jak przygotowywać środowisko programistyczne można znaleźć w artykule Przygotowanie środowiska programowania rozszerzenia.

Tworzenie manifestu instalacji

Otwieramy plik install.rdf, który utworzyliśmy w głównym katalogu rozszerzenia i wpisujemy tam:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.0+</em:minVersion>
        <em:maxVersion>1.5.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>Sample!</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>https://www.foo.com/</em:homepageURL>
  </Description>      
</RDF>

[email protected] - Identyfikator rozszerzenia. Jest to wartość, która pozwala zidentyfikować rozszerzenia, w formacie adresu email (zauważ, ze nie powinien to być Twój adres e-mail). Powinna być to wartość unikatowa. Możesz użyć także GUID. UWAGA: parametr ten MUSI posiadać format adresu e-mail, ale NIE musi to być poprawny adres (cośtam@coś.coś).
Określ <em:type>2</em:type> -- cyfra 2 wskazuje, że plik opisuje rozszerzenie (zobacz inne typy kodów).
{ec8030f7-c20a-464f-9b0e-13a3a9e97384} - Identyfikator aplikacji Firefox.
1.0+ - Minimalna wersja Firefoksa, na której rozszerzenie będzie działać. Ustaw tu minimalną wersję Firefoksa, dla której będziemy testować rozszerzenie i przygotowywać poprawki błędów.
1.5.0.* - Maksymalna wersja Firefoksa, na której rozszerzenie będzie działać. Ustaw tak, aby wersja ta nie była nowsza niż najnowsza dostępna obecnie wersja Firefoksa!

Zobacz Manifesty Instalacji, gdzie znajdziesz kompletną listę wymaganych i opcjonalnych właściwości.

Zapisz plik.

Rozszerzanie przeglądarki przy użyciu języka XUL

Interfejs użytkownika w Firefoksie napisany jest w XUL i JavaScript. XUL jest językiem zgodnym z językiem XML, pozwala on na tworzenie elementów interfejsu użytkownika takich jak: przyciski, menu, paski narzędzi itp. Akcje użytkownika są powiązane z funkcjami przy użyciu języka JavaScript.

Aby rozszerzyć możliwości przeglądarki, zmieniamy interfejs użytkownika poprzez dodanie lub modyfikację kontrolek. Możemy dodać elementy interfejsu poprzez wstawienie nowych elementów DOM XUL do okna przeglądarki i zmodyfikowanie ich poprzez dodanie skryptów i uchwytów zdarzeń.

Przeglądarka jest zaimplementowana w pliku XUL o nazwie browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar zawiera content/browser/browser.xul). W browser.xul znajdziemy pasek stanu, który wygląda mniej więcej tak:

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar"> jest punktem wiązania dla nakładki XUL.

Nakładki XUL

Nakładki XUL są metodą na dołączanie w locie elementów interfejsu XUL do gotowych dokumentów XUL. Nakładka XUL to plik o rozszerzeniu .xul określający fragmenty w języku XUL, które mają zostać dołączone do określonego punktu wiązania w dokumencie głównym. Fragmenty te mogą określać elementy interfejsu, które mają zostać dodane, usunięte lub zmodyfikowane.

Przykładowy dokument nakładki XUL ^[1]

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Witaj świecie!"/>
 </statusbar>
</overlay>

Element <statusbar> nazwany status-bar określa "punkt wiązania" w oknie przeglądarki, do którego chcemy się podpiąć.

Element podrzędny ("dziecko") <statusbarpanel> jest nowym elementem interfejsu, który chcemy wstawić wewnątrz elementu będącego punktem wiązania.

Skopiuj przykładowy kod podany powyżej i zapisz go w pliku o nazwie sample.xul wewnątrz katalogu chrome/content, który wcześniej utworzyłeś.

Aby dowiedzieć się więcej na temat wiązania elementów interfejsu i modyfikowania interfejsu użytkownika przy zastosowaniu Nakładek, czytaj dalej.

Chrome URI

Pliki XUL są częścią "Pakietów Chrome" - paczek komponentów interfejsu użytkownika, które są ładowane przy użyciu URI chrome://. Zamiast ładować przeglądarkę z dysku używając URI file:// (ponieważ położenie Firefoksa w systemie może się zmieniać w zależności od platformy i systemu), twórcy Firefoksa wymyślili w jaki sposób tworzyć URI dla zawartości plików XUL, o których wie zainstalowana aplikacja.

URI dla okna przeglądarki to: chrome://browser/content/browser.xul Spróbuj wpisać to URI do paska adresu w Firefoksie!

Chrome URI składa się z kilku części:

Po pierwsze, rodzaju zasobu/usługi URI (chrome), który mówi bibliotece sieciowej Firefoksa, że jest to Chrome URI i że ładowana przez niego zawartość będzie wymagała obsłużenia w specjalny sposób.
Po drugie, nazwy pakietu (w przykładzie powyżej, browser), która identyfikuje paczkę komponentów interfejsu użytkownika. Ta nazwa powinna być tak unikalna dla twojej aplikacji jak to możliwe, aby uniknąć kolizji między rozszerzeniami.
Po trzecie, typ żądanych danych. Są trzy typy: content (XUL, JavaScript, wiązania XBL i inne, które tworzą strukturę i funkcjonalność interfejsu użytkownika aplikacji), locale (DTD, pliki .properties (właściwości) i inne, które zawierają łańcuchy znaków dla lokalizacji) interfejsu oraz skin (CSS i obrazki, które tworzą motyw (wygląd) interfejsu)
Na koniec, ścieżka do pliku, który ma zostać załadowany przez URI.

Tak więc, chrome://foo/skin/bar.png ładuje plik bar.png z sekcji skin rozszerzenia foo.

Kiedy ładujesz zawartość używając Chrome URI, Firefox używa rejestru Chrome do przetłumaczenia tych identyfikatorów URI na właściwe pliki źródłowe na dysku (lub w archiwach JAR).

Tworzenie Manifestu Chrome

Więcej informacji o manifeście Chrome i obsługiwanych przez niego właściwościach znajdziesz w dokumentacji Manifestu Chrome.

Otwórz plik o nazwie chrome.manifest, który stworzyłeś obok katalogu chrome w głównym katalogu rozszerzenia.

Dodaj poniższy kod:

content     sample    chrome/content/

(Nie zapomnij o ukośnikach "/"! Bez nich pakiet nie zostanie zarejestrowany.)

Dane w pliku określają:

typ zawartości przechowywanej w pakiecie chrome,
nazwę pakietu chrome (używaj wyłącznie małych liter w nazwie rozszerzenia ("sample"), ponieważ Firefoks/Thunderbird nie obsługuje mieszanych wielkości liter w wersji 2 oraz wcześniejszych - błąd 132183),
położenie plików pakietu chrome.

Zatem powyższa linia informuje, że dla pakietu sample możemy znaleźć pliki zawierające dane typu content (zawartość) w lokalizacji chrome/content, podanej względem położenia pliku chrome.manifest.

Zauważ, że pliki zawartości, lokalizacji i motywu muszą być zawarte wewnątrz folderów content, locale oraz skin wewnątrz twojego podkatalogu chrome.

Zapisz plik. Kiedy załadujesz Firefoksa z twoim rozszerzeniem (dalej w tym przewodniku), ten plik umożliwi zarejestrowanie Twojego pakietu chrome.

Rejestrowanie nakładki

Chcemy, aby Firefox łączył Twoją nakładkę z oknem przeglądarki, zawsze gdy jest ono wyświetlane. Dodaj tą linię do twojego pliku chrome.manifest :

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

Mówi ona Firefoksowi, żeby połączył sample.xul i browser.xul, gdy browser.xul jest ładowany.

Test

Po pierwsze, musimy powiedzieć przeglądarce Firefox o Twoim rozszerzeniu. W starych, złych czasach Firefoksa 1.0 oznaczało to spakowanie rozszerzenia jako XPI i zainstalowanie go przez interfejs użytkownika, co było naprawdę nieprzyjemne. Teraz jest to znacznie prostsze.

Otwórz swój folder profilu,
Otwórz folder extensions (stwórz go, jeśli nie istnieje),
Stwórz nowy plik tekstowy i umieść w nim ścieżkę do folderu twojego rozszerzenia, np. C:\extensions\myExtension\ lub ~/extensions/myExtension. Zapisz plik z identyfikatorem twojego rozszerzenia jako jego nazwą, np. [email protected].

(Nie zapomnij o ukośniku "/"! Bez niego rozszerzenie nie zostanie zarejestrowane.)

Teraz jesteś gotowy do testowania swojego rozszerzenia!

Uruchom Firefoksa. Firefox wykryje plik z odnośnikiem do katalogu Twojego rozszerzenia i zainstaluje rozszerzenie. Kiedy pojawi się okno przeglądarki, powinieneś zobaczyć tekst "Witaj świecie!" z prawej strony paska statusu.

Możesz teraz wrócić i zmienić plik .xul, uruchomić ponownie Firefoksa - zmiany powinny się pojawić.

grafika:Helloworld_status_bar.PNG

grafika:Helloworld_extensions_wnd.PNG

</center>

Pakowanie

Teraz, gdy twoje rozszerzenie działa, możesz je spakować w celu umożliwienia dystrybucji i instalacji.

Spakuj jako archiwum zip zawartość katalogu rozszerzenia (nie sam folder rozszerzenia) i zmień rozszerzenie pliku zip na rozszerzenie .xpi. W Windows XP możesz to łatwo zrobić przez zaznaczenie wszystkich plików i podfolderów w katalogu rozszerzenia, kliknięcie prawym przyciskiem myszy i wybranie "Wyślij do -> Folder skompresowany (zip)". Plik .zip zostanie utworzony. Teraz tylko zmień nazwę i gotowe!

Teraz wgraj plik .xpi na serwer i upewnij się, że jest obsługiwany jako application/x-xpinstall. Możesz podlinkować plik i umożliwić ludziom ściąganie i instalowanie Twojego rozszerzenia w Firefoksie.

Zastosowanie addons.mozilla.org

Mozilla Update jest witryną służącą do rozpowszechniania rozszerzeń, gdzie możesz umieścić swoje rozszerzenie za darmo. Rozszerzenie będzie przechowywane w sieci mirrorów Mozilli gwarantując możliwość ściągnięcia go, nawet jeżeli będzie ono bardzo popularne. Witryna Mozilli umożliwia także użytkownikom łatwiejszą instalację i automatyczne uaktualnienia do nowych wersji po ich udostępnieniu przez Ciebie. W dodatku Mozilla Update pozwala użytkownikom komentować i dostarczać opinie na temat twojego rozszerzenia. Rozpowszechnianie swoich rozszerzeń za pomocą Mozilla Update jest bardzo zalecane!

Odwiedź https://addons.mozilla.org/developers/, załóż konto i zacznij rozpowszechnianie swoich rozszerzeń!

Uwaga: Twoje rozszerzenie może być szybciej udostępnione i częściej ściągane, jeśli masz jego dobry opis i ekranowe zrzuty rozszerzenia w akcji.

Rejestrowanie rozszerzeń w rejestrze Windows

W systemie Windows informacja o rozszerzeniach może być dodana do rejestru, wtedy rozszerzenia będą automatycznie instalowane następnym razem, gdy aplikacja (Firefox/Thunderbird) uruchamia się. To umożliwia instalatorom innych aplikacji łatwe integrowanie się z Firefoksem i innymi aplikacjami Mozilli poprzez rozszerzenia. Zobacz Dodawanie rozszerzeń poprzez rejestr systemu Windows w celu uzyskania dalszych informacji.

Więcej o nakładkach XUL

Poza dołączaniem kontrolek interfejsu użytkownika do punktów łączenia możesz użyć fragmentów XUL w Nakładkach do:

Modyfikowania atrybutów punktu łączenia, np. <statusbar id="status-bar" hidden="true"/> (ukrywa pasek statusu)
Usunięcia punktu łączenia z głównego dokumentu, np. <statusbar id="status-bar" removeelement="true"/>
Kontrolowania pozycji wstawianych kontrolek:

<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="other-id" .../>

<statusbarpanel insertafter="other-id" .../>

Tworzenie nowego komponentu interfejsu użytkownika

Możesz tworzyć swoje własne okna i okienka dialogowe jako oddzielne pliki .xul, dostarczać nową funkcjonalność poprzez implementację akcji w plikach .js, używać metod DOM do manipulowania kontrolkami interfejsu użytkownika. Możesz używać stylów w plikach .css do dołączania obrazków, ustawiania kolorów itp.

Zobacz dokumentację XUL, znajdziesz w niej więcej zasobów dla programistów XUL.

Pliki domyślne

Domyślne pliki, których używasz do stworzenia profilu użytkownika powinny być umieszczone w katalogu defaults/ w głównym folderze hierarchii katalogów Twojego rozszerzenia. Pliki domyślnych preferencji .js powinny być przechowywane w defaults/preferences/ - kiedy umieścisz je tutaj, będą one automatycznie ładowane przez system preferencji Firefoksa podczas startu tak, że będziesz miał do nich dostęp używając Preferencji API.

Przykładowy plik domyślny preferencji:

pref("extensions.sample.username", "Joe"); //tekst
pref("extensions.sample.sort", 2); //liczba
pref("extensions.sample.showAdvanced", true); //wartość logiczna

Komponenty XPCOM

Firefox obsługuje komponenty XPCOM w rozszerzeniach. Możesz łatwo stworzyć swoje własne komponenty w JavaScript lub C++ (używając SDK Gecko).

Wszystkie pliki .js lub .dll umieszczamy w katalogu components/ - zostaną one automatycznie zarejestrowane przy pierwszym uruchomieniu Firefoksa po instalacji rozszerzenia.

Aby uzyskać więcej informacji, zobacz Jak stworzyć komponent XPCOM w Javascripcie, Jak stworzyć binarny komponent XPCOM używając Visual Studio oraz Tworzenie komponentów XPCOM.

Linia poleceń aplikacji

Jednym z możliwych zastosowań komponentów XPCOM wykonanych specjalnie do tego celu jest dodanie agenta linii poleceń do Firefoksa lub Thunderbirda. Możesz użyć tej techniki do uruchamiania swojego rozszerzenia jako aplikacji:

 firefox.exe -myapp

Zobacz Chrome:Linia poleceń i dyskusję na forum, aby poznać szczegóły.

Lokalizacja

Dla obsługi więcej niż jednego języka, powinieneś rozdzielić teksty napisów od reszty zawartości Twojego rozszerzenia używając do tego encji i plików własności. Dużo łatwiej zrobić to podczas tworzenia rozszerzenia niż wracać do tego później.

Informacje o lokalizacji dla Twojego rozszerzenia są przechowywane w katalogu locale. Na przykład, dla dodania lokalizacji do naszego przykładowego rozszerzenia, stwórz katalog "locale" w chrome (gdzie ulokowany jest katalog "content") i dodaj następującą linię do pliku chrome.manifest:

locale sample sampleLocale chrome/locale/

Dla stworzenia lokalizowalnej wartości atrybutu w XUL wstaw te wartości do pliku .dtd, który powinien być umieszczony w katalogu locale i wyglądać tak:

<!ENTITY  button.label     "Click Me!">
<!ENTITY  button.accesskey "C">

I następnie dołącz go na początku Twojego dokumentu XUL (ale pod "<?xml version"1.0"?>"), tak jak poniżej:

<!DOCTYPE window SYSTEM "chrome://sample/locale/filename.dtd">

gdzie: window jest wartością atrybutu localName, głównego elementu dokumentu XUL, a wartość własności SYSTEM jest identyfikatorem chrome URI pliku encji. Dla naszego prostego rozszerzenia, głównym elementem jest overlay.

Aby użyć encji, zmodyfikuj swój kod XUL, tak żeby wyglądał jak ten (poniższa linia musi być zawarta wewnątrz elementu <statusbar id="status-bar"> z poprzedniego przykładu):

<button label="&button.label;" accesskey="&button.accesskey;"/>

Rejestr Chrome załaduje plik encji z pakietu lokalizacyjnego odpowiadającego wybranej lokalizacji.

Dla łańcuchów znaków, których używasz w skrypcie, utwórz plik tekstowy .properties, który w każdej linii ma łańcuchy znaków w formacie:

key=value

i następnie użyj: nsIStringBundleService/nsIStringBundle lub znacznika <stringbundle> w celu załadowania wartości do skryptu.

Zrozumienie przeglądarki

Użyj Inspektora DOM (nie jest on częścią Standardowej instalacji Firefoksa; musisz go zainstalować z użyciem instalacji Użytkownika i wybrać Narzędzia programistyczne jeśli nie ma składnika "Inspektor DOM" w menu Narzędzia w twojej przeglądarce) do zbadania okna przeglądarki lub każdego innego okna XUL, które chcesz zmodyfikować.

Użyj przycisku "Wybierz węzeł do zbadania poprzez kliknięcie na nim" z paska narzędzi położonego u góry na lewo Inspektora DOM do kliknięcia na element (węzeł) w oknie przeglądarki. Kiedy to zrobisz widok drzewa hierarchii DOM w oknie Inspektora DOM przeniesie się na węzeł, na który kliknąłeś.

Użyj prawego panelu Inspektora DOM w celu znalezienia punktów łączenia z identyfikatorami, których możesz użyć przy wstawianiu swoich elementów z nakładek. Jeśli nie możesz znaleźć elementu z identyfikatorem, do któregoś mógłbyś się podłączyć, być może będziesz musiał dołączyć skrypt do swojej nakładki i wstawiać swoje elementy, kiedy zdarzenie load zostanie odpalone w głównym oknie XUL.

Debugowanie rozszerzeń

Analityczne narzędzia do debugowania

Inspektor DOM - bada atrybuty, strukturę DOM, style CSS, których używasz (np. odkrywa, dlaczego Twój styl wydaje się nie działać dla elementu - nieocenione narzędzie!)
Venkman - ustawia pułapki (breakpointy) w skryptach JavaScript i bada stos wywołań
arguments.callee.caller w JavaScript - dostęp do stosu wywołań funkcji.

Debugowanie printf

Uruchom Firefoksa z opcją -console z linii poleceń i używaj dump("string") (zobacz odnośnik, aby dowiedzieć się szczegółów),
Używaj nsIConsoleService do wyświetlania logów w konsoli JavaScript.

Zaawansowane debugowanie

Uruchom wersję Firefoksa skompilowaną ze wsparciem dla debugowania i ustaw pułapki w samym Firefoksie lub Twoim komponencie C++. Dla doświadczonych twórców rozszerzeń, jest to często najszybszy sposób zdiagnozowania problemu. Przejrzyj Dokumentacja kompilacji i Programowanie_Mozilli w celu uzyskania dalszych informacji.
Zobacz Debugowanie aplikacji XULRunner, aby uzyskać więcej pomocnych wskazówek.

Szybki start

Możesz zastosować narzędzie Kreator rozszerzeń do generowania prostych rozszerzeń, które potem możesz modyfikować.

Rozszerzenie Hello World podobne do tych, które można wygenerować Kreatorem Rozszerzeń jest opisane linijka po linijce w innym przewodniku MozillaZine Knowledge Base.

Dalsze informacje

* Rozszerzenia - FAQ
* Rozszerzenia

Uwaga: 1

Dwie uwagi do tego punktu:

Jeżeli chcesz użyć polskich liter, powinieneś zapisać plik w formacie UTF-8 (w Windows XP wystarczy do tego Notatnik)
Zgodnie z sugestią w tym komentarzu - jeżeli napis na pasku statusu nie pokaże się podczas testowania rozszerzenia, to być może inne zainstalowane rozszerzenie również wykorzystuje panel na pasku statusu o id "my-panel". Warto wtedy spróbować zmienić w powyższym kodzie id="my-panel" np. na id="my-panel123" i ponownie uruchomić przeglądarkę.