Firefox Extension Hogyan

A HupWiki-ből...

A how to alapját a Mozilla Wiki angol nyelvű Building an Extension szócikka szolgálja. Elsődleges dokumentációs forrásként a Mozilla Wikije tekinthető.

Ez a tutorial egy nagyon egyszerű példán keresztül próbál meg bevezetni a Firefox extension készítés alapjaiba. Az elkészülő extension a status barhoz fog egy "Hello, World!" részt hozzáadni.

A tutorial-ban kiadott parancsokat Bash shellben adtam ki.

A tutorial segítségével Firefox 1.5 vagy későbbi verziókhoz készíthetünk extensiont.

Tartalomjegyzék

A fejlesztői környezet beállítása

Az extensionök ZIPpel vannak csomagolva, melyeknek a kiterjesztése XPI (ejtsd zippy).

Egy XPI file általában következőket tartalmazza (extensiontől függően hiányozhatnak vagy más file-okat is tartalmazhat): 

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

Az példánkban is hasonló felépítést fogunk alkalmazni. Mielőtt bármit elkezdenénk, hozzunk létre egy könyvtárat, ahol majd a fejlesztést végezzük: 

$ mkdir -p ~/extensions/exampleExt

Ebbe könyvtárat létre kell hoznunk egy chrome és azon belül egy content nevű könyvtárat. 

$ mkdir -p ~/extensions/exampleExt/chrome/content

Az extension root könyvtárában hozzunk létre további két file-t chrome.manifest és install.rdf néven: 

$ touch ~/extensions/exampleExt/{chrome.manifest,install.rdf}

A végén a következő struktúrát kell kapnunk: 

<ext path>/
    install.rdf
    chrome.manifest
    chrome/
        content/

Install.rdf elkészítése

Az install.rdf file tartalmazza az extension adatait, így pl. annak honlapját, verziószámát, a szerző nevét és azt, hogy mely alkalmazások mely verziószámával kompatibilis. Nyissuk meg az install.rdf file-t és másoljuk bele a következőket: 

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <em:id>sample@example.net</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
	<!-- Célalkalmazások a támogatott minimum és maximum verziókkal, amelyekre az extension installálható -->
	<!-- Firefox -->
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>3.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
    <!-- Meta-adatok az extensionről -->
    <em:name>sample</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>http://www.example.com/</em:homepageURL>
  </Description>
</RDF>
  • sample@example.com Az extension egyedi azonosítója. Lehet e-mail cím formátumú, viszont nem kell, hogy létező e-mail cím legyen. A feladata, hogy az extensiont azonosítsa. Használhatunk továbbá GUID formát is.
  • <em:type>2</em:type> a 2 jelenti, hogy ez egy extension. Theme esetében az értéknek 4-nek kell lennie.
  • {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - Firefox alkalmazás azonosítója
  • 1.5 A minimum Firefox verzió, amellyel az extension együtt fog működni. Állítsuk arra a verzióra, amelynek támogatását vállaljuk, amely alatt teszteljük és amelyhez javításokat készítünk.
  • 3.0.* A maximum Firefox verzió, amellyel az extension együtt fog működni. Ez az érték ne legyen nagyobb a legfrissebb elérhető verziónál. A példa szerint, az extension működni fog a Firefox 3.0-val és az utólagos 3.0.x kiadásokkal.

(Firefox 3.0.1 esetén ne állítsd min- és maxverziókat 3.0.*-ra, mert az installálás nem fog sikerülni. Állítsd az em:minVersion-t 3-ra az em:maxVersion-t 3.0.*-ra.)

Mentsük el a filet.

A böngésző kiterjesztése XUL-lel

A Firefox UI-ja JavaScriptben és XUL-ben van megírva. Az XUL egy XML alapú leíró nyelv, aminek segítségével leírhatjuk a felület elemeit, widgeteit, mint a gombokat, menüket, tool barokat stb.

A böngésző XUL-ben van implementálva, a file neve browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar fileon belül: content/browser/browser.xul). Ebben a fileban találhatjuk a böngésző elemeit, pl. a tool bart vagy status bart. A statusbar a következőképpen néz ki: 

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

A <statusbar id="status-bar"> a "merge point" (magyarul talán beolvasztási pont FIXME) az XUL overlaybe. A merge-pointtal határozhatjuk meg, hogy az extensionünk új elemeit a böngészőben hová szeretnénk elhelyezni. Így, ha a statusbarhoz szeretnénk adni egy gombot, képet, szöveget, akkor a fenti merge point-ot kell hivatkozási alapul venni. Lássuk hogyan:

XUL Overlay dokumentum

Az XUL Overlay egy .xul file, amelyben dokumentum töredékeket, új elemeket definiálhatunk, amiket hozzáadhatunk a már meglévő "master" dokumentumhoz - gyakorlatilag a böngészőhöz. Ezekben határozhatjuk meg a widgeteket, amelyek a böngészőt ki fogják egészíteni.

XUL Overlay dokumentum példa 

<?xml version="1.0"?>
<overlay id="sample" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <statusbar id="status-bar">
	<statusbarpanel id="my-panel" label="Hello, World"/>
  </statusbar>
</overlay>

A status-bar ID-vel ellátott <statusbar> elem határozza meg azt a pontot, ahová az új elemet hozzá szeretnénk adni. Hasonló módon lehet új gombokat adni a tool barhoz vagy új menüpontot beszúrni a Tools vagy a jobb gombra előbukkanó menübe is.

A <statusbarpanel> elem az a widget, amit a csatolási ponthoz, tehát a statusbarhoz szeretnénk adni.

Vegyük ezt a példa kódot, és másoljuk be egy sample.xul nevű fileba, amit mentsünk el a chrome/content könyvtárba.

Chrome URI-k

Az XUL fileok "Chrome Csomagok" részei - a felhasználó felület részeit összefogó csomagok, melyeket chrome://URI formában lehet betölteni. Az efféle URI-k használatára azért van szükség, hogy a csomagokat platformtól és telepítési útvonaltól függetlenül is be lehessen tölteni.

A böngésző ablak elérési útja például chrome://browser/content/browser.xul - próbáld ki, hogy beírod a Firefox location barjába.

A Chrome URI-k több részből épülnek fel:

  • Az URI legelején található a chrome, ami megmondja a Firefox hálózati libraryjének, hogy ez egy Chrome URI. Ez jelzi, hogy miképpen legyen kezelve az URI tartalma. Ha chrome helyett például http-t használunk, a Firefox azt egy weboldalként fogja azt kezelni.
  • A második része a csomagnév (a fenti példában browser), ami az UI komponens csomagnevét határozza meg (gyakorlatilag az extension neve). Minden alkalmazás (extension, theme, stb.) esetében ennek a névnek egyedinek kell lennie, hogy elkerüljük a keveredéseket.
  • Harmadik részként a hivatkozott adat adat típusa. Három féle típus létezik:
    • content (tartalom) XUL, JavaScript, stb. ami leírja az alkalmazás struktúráját és viselkedését
    • locale (honosítás) DTD, .properties fileok, melyek a fordításhoz tartalmaznak stringeket
    • skin (téma) CSS és képek amelyek meghatározzák a felhasználói felület külsejét
  • Végül a betöltendő file elérési útvonalát (path)

Tehát pl. a chrome://foo/skin/bar.png betölti a foo theme skin részéből a bar.png filet.

Amikor valamilyen tartalmat Chrome URI-val töltesz be, a Firefox Chrome Registry-t használja hogy ezeket az URI-kat lefordítsa a forrásfájlok tényleges helyére a merevlemezen.

Chrome.manifest elkészítése

A chrome.manifest file szolgál arra, hogy az extension elemeit beregisztráljuk a chrome-ba. A chrome a böngészőablak azon interface elemeinek a gyűjteménye, melyek az ablak tartalmán (~weboldal) kívül helyezkednek el. Tool barok, menük, folyamatjelző sávok és az ablak címsora mind a chrome részei. Részletes leírás a chromeról

Nyissuk meg a chrome.manifest file-t, melyet az extension root könyvtárába készítettünk, majd másoljuk bele a következőt: 

content     sample    chrome/content/

Ügyeljünk a záró /-re, anélkül a csomag nem lesz regisztrálva!

Ezzel meghatározzuk

  1. A tartalom típusát a chrome csomagban
  2. A chrome csomag nevét. A csomag neve mindig legyen kisbetűs, mert a Firefox és a Thunderbird nem támogatja a kis- nagybetűs csomagneveket a 2. verzióban és előtte.
  3. A chrome csomag fájljainak helyét

Tehát ez a sor megmondja, hogy a chrome/content útvonal alatt találhatjuk "sample" nevű chrome csomaghoz a content file-ok. Az útvonal relatív a chrome.manifesthez képest.

A content, locale és skin file-ok a content, locale és skin nevű könyvtárakon belül kell legyenek, melyeket a chrome könyvtárban kell elhelyezni.

Mentsük el a file-t. Amikor a böngészőt elindítjuk az extensionnel, ez fogja regisztrálni a chrome csomagot.

Overlay regisztrálása

Szükségünk van arra, hogy a Firefox az overlayünket a böngésző ablakába betöltse. Ehhez adjuk hozzá a chrome.manifesthez a következő sort: 

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

Ez megmondja a Firefoxnak, hogy adja hozzá a sample.xul-t a browser.xul-hez, amikor a browser.xul betöltődik.

Tesztelés

Először szükségünk van arra, hogy a Firefoxot tudassuk az extensionről. Firefox 2.0 és újabb verziók esetében rávehetjük a Firefoxot, hogy a abból a könyvtárból töltse be az extensiont, ahol fejlesztjük azt.

  1. Keressük meg és lépjünk be az alapértelmezett profile könyvtárba. Pl.:~/.mozilla/firefox/<profile_id>.default/
  2. Nyissuk meg extensions könyvtárat. Ha nincs ilyen könyvtár, akkor hozzunk létre egyet.
  3. Hozzunk létre egy új textfile-t, és tegyük bele az fejlesztői könyvtár elérési útját. Pl. ~/extensions/my_extension/. Mentsük el a file-t, a neve legyen az extension ID-je, pl. sample@example.net

(Ne felejtsük el a záró /-t! Enélkül az extension nem lesz regisztrálva.)

Most indítsuk el a Firefoxot. A Firefox érzékelni fogja a text linket az extension könyvtárban és installálni fogja az extensiont. Amikor a böngésző ablak megjelenik egy "Hello, World!" szöveget kell látnod a status bar jobb oldalán.

Ha most megszerkesztjük az xul file-t, a böngésző újraindítása után látnunk kell a változásokat.

Csomagolás

Ha az extension működik, itt az ideje, hogy csomagot csináljunk belőle.

A csomagok zip file-ok, legegyszerűbb terminálban a zip parancs használatával elkészíteni a csomagot. 

zip sample.xpi chrome.manifest install.rdf chrome/content/overlay.xul

Defaults/preferences/

A defaults/preferences/ könyvtárban lévő file-lal lehet különböző, az extensionhöz tartozó beállítások alapértelmezett értékeit beállítani, melyek később módosíthatóak az about:configból vagy (ha készítünk hozzá) beállítópanelen keresztül. A böngésző induláskor automatikusan beolvassa az ebben a könyvtárban lévő file-okat. Preferences API

Néhány példa egy ilyen file tartalmára: 

pref("extensions.sample.username", "Joe"); //a string pref
pref("extensions.sample.sort", 2); //an int pref
pref("extensions.sample.showAdvanced", true); //a boolean pref

Honosítás

Ha szeretnéd, hogy az extension lefordítható legyen, a felület stringjeit ennek megfelelően kell kezelni. https://developer.mozilla.org/en/XUL_Tutorial/Localization

A honosítási információk nyelvenként külön könyvtárban vannak eltárolva. Ezért hozzunk létre egy locale nevű könyvtárat a chrome könyvtárban (a content könyvtár mellé), melybe hozzuk létre minden nyelvhez a hozzá tartozó könyvtárat, pl en-US. Ezután szerkesszük meg a chrome.manifest file-t, hogy beregisztráljuk az extension nyelvi file-jait a chrome-ba. 

locale sample en-US chrome/locale/en-US/

A létrehozott könyvtárban készítsünk egy .dtd (vagy .ent) file-t, melybe az XUL file-okhoz tartozó fordításokat helyezhetjük: 

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

Ezután készítsünk egy hivatkozást az overlay.xul-ba mely a nyelvi file-ra mutat: 

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

Ezt helyezzük a file tetejére, de az <?xml version="1.0"?> után.

XUL file-ban a következőképpen hivatkozhatunk ezekre a stringekre: 

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

Ha JavaScriptből szeretnénk stringet elérni, készítenünk kell egy .properties file-t. Ennek a file-nak minden sora egy lefordítható string: 

kulcs=érték
kulcs2=ertek %S

A kulcs egy azonosító, melyre a scriptben hivatkozunk, az érték pedig a string, amit ki szeretnénk majd íratni. A file-ra ugyancsak egy hivatkozást kell készítenünk, melyet a stringbundleset és stringbundle taggel valósíthatunk meg: 

<stringbundleset id="sample-stringset">
  <stringbundle id="sample-strings" src="chrome://grwatcher/locale/filename.properties" />
</stringbundleset>

A JavaScriptben a stringbundle ID-je alapján kell hivatkoznunk rá: 

sample_strings = document.getElementById('sample-strings');

Majd értéket a következőképpen olvashatunk ki: 

sample_strings.getString('kulcs')
sample_strings.getFormattedString('kulcs2', [valtozo])

A visszatérési érték a lefordított string lesz. További részletek

JavaScript overlaybe illesztése

Ha extensiont készítünk, minden bizonnyal szeretnénk annak a megjelenésen kívül valami funkciót is adni. A Firefoxban erre JavaScriptet használunk, melyet a chrome/content/ könyvtárba hozzunk létre, például overlay.js néven. Tartalma legyen nagyon egyszerű: 

alert('Hello, World');

Ahhoz a JavaScripthez hozzáférjünk, az overlay.xul-en keresztül be kell csatolnunk a chrome-ba: 

<script type="application/x-javascript" src="chrome://sample/content/overlay.js" />

Ha ezzel megvagyunk, akkor a következő indításkor a Firefox egy "Hello, World" feliratú alert window-val fogad majd.

Külső hivatkozások

Megjegyzések a hogyanról

A how to semmiképpen nem tekinthető referenciának, csupán megpróbál segítséget nyújtani az elinduláshoz. Megeshet, hogy félrefordításokat, helytelen és érthetetlen fogalmazásokat vagy teljes ostobaságokat tartalmaz. Ebben az esetben javítsd nyugodtan vagy írj a szócikk Vitalapjára, esetleg vedd fel velem (Ajnasz) a kapcsolatot.

Kinyerve "http://wiki.hup.hu/index.php/Firefox_Extension_Hogyan"-ből