Sviluppare un'Estensione

Introduzione

Questo tutorial accompagnerà passo-passo nella creazione di un'estensione semplice e basilare che permetta di aggiungere un pannello alla barra di stato contenente il testo "Hello, World!"

Organizzare l'ambiente di sviluppo

Le estensioni vengono impacchettate e distribuite in file ZIP, o Bundles, con l'estensione <tt>xpi</tt> ( pronunciata “zippy” ). Lo schema del contenuto di un file XPI è simile a questo:

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

Per questo motivo è consigliabile organizzare i file sorgente in una struttura simile, a meno che non si voglia scrivere un qualche tipo di Makefile or shell script per impacchettare e comprimere i propri file. Anche qualora si sia in grado di farlo, è molto più semplice eseguire i test attraverso la struttura sopra indicata a causa delle caratteristiche del sistema di installazione delle estensioni di Firefox 1.5.

Iniziamo. Crea una cartella per l'estensione da qualche parte sull'hard disk, ad es. <tt>C:\extensions\myExtension\</tt> o <tt>~/extensions/myExtension/</tt>. Dentro questa cartella crea un'altra cartella chiamata <tt>chrome</tt>, e all'interno della cartella <tt>chrome</tt> crea un'altra cartella chiamata <tt>content</tt>. (Su sistemi di tipo Unix è possibile creare tutte e tre le directory eseguendo semplicemente <tt>mkdir -p chrome/content</tt> dalla directory di root dell'estensione.)

Dentro alla root della cartella dell'estensione, insieme alla cartella <tt>chrome</tt>, crea due nuovi file di testo vuoti, uno chiamato <tt>chrome.manifest</tt>, l'altro invece <tt>install.rdf</tt>.

Altri suggerimenti sull'organizzazione dell'ambiente di sviluppo possono essere trovati su Mozillazine Knowledge Base(EN).

Creare il manifesto di installazione

Apri il file chiamato <tt>install.rdf</tt> che hai creato al vertice della gerarchia delle cartelle dell'estensione e scrivici dentro:

<?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>Esempio!</em:name>
    <em:description>Estensione di prova</em:description>
    <em:creator>Il tuo nome</em:creator>
    <em:homepageURL>https://www.iltuositoweb.com/</em:homepageURL>
  </Description>      
</RDF>

• [email protected] - è l'ID dell'estensione. E' un valore che serve ad identificare l'estensione con il formato di un indirizzo e-mail (N.B. non deve essere il tuo indirizzo e-mail). Rendilo unico. Si può anche usare un GUID.
• Specifica <tt><em:type>2</em:type></tt> -- il 2 indica che viene descritta un'estensione (vedere Manifesti di installazione#Tipi per i codici di altri tipi).
• {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - rappresenta l'ID della applicazione per Firefox.
• 1.0+ - la versione minima di Firefox con la quale si afferma che funzioni l'estensione. Imposta questo valore come la minima versione di Firefox sulla quale si ha l'intenzione di eseguire test e di correggere gli errori.
• 1.5.0.* - rappresenta la massima versione di Firefox con la quale si afferma che funzioni l'estensione. Non impostare questo valore ad una versione maggiore di quella più nuova attualmente disponibile!

Guarda Manifesti di installazione per un elenco completo delle proprietà richieste e opzionali.

Salva il file.

Estendere il browser con XUL

L'interfaccia utente di Firefox è scritta in XUL e JavaScript. XUL è una grammatica XML che fornisce all'interfaccia utente dei componenti come pulsanti, menu, barre degli strumenti, strutture ad albero, etc. Le azioni dell'utente sono invece collegate alle funzionalità attraverso dei JavaScript.

Per estendere il borwser si modificano parti dell'UI del browser aggiungendo o modificando i componenti. Si aggiungono componenti inserendo nuovi elementi XUL DOM nella finestra del browser, e si modificano usando script e associando dei gestori di eventi.

Il browser è implementato in un file XUL chiamato <tt>browser.xul</tt> (<tt>$FIREFOX_INSTALL_DIR/chrome/browser.jar</tt> che contiene <tt>content/browser/browser.xul</tt>). Dentro browser.xul si può trovare la barra di stato, che assomiglierà a qualcosa del genere:

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

<tt><statusbar id="status-bar"></tt> è un "punto di fusione" per un Overlay XUL.

Overlay XUL

Gli Overlay XUL sono un modo di associare altri oggetti UI a un documento XUL al momento dell'esecuzione. Un Overlay XUL è un file .xul che specifica dei frammenti del file XUL da inserire in specifici "punti di fusione" contenuti nel documento principale. Questi frammenti possono indicare l'inserimento, la rimozione o la modifica degli oggetti.

Esempio di un documento di Overlay XUL

<?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="Hello, World"/>
 </statusbar>
</overlay>

La <tt><statusbar></tt> chiamata <tt>status-bar</tt> indica il "punto di fusione" all'interno della finestra del browser al quale si intende associare la modifica.

Il figlio <tt><statusbarpanel></tt> rappresenta un nuovo oggetto da inserire all'interno del punto di fusione.

Usa questo semplice codice e salvalo in un file chiamato <tt>sample.xul</tt> dentro la cartella <tt>chrome/content</tt> che hai creato.

Per ulteriori informazioni circa l'inserimento di oggetti e la modifica dell'interfaccia utente attraverso gli Overlay, guarda sotto.

URI Chrome

I file XUL sono parti del "Pacchetto Chrome" - una serie di componenti dell'interfaccia utente che vengono caricati attraverso indirizzi URI <tt>chrome://</tt>. Invece di caricare il browser da disco usando un URI <tt>file://</tt> (poichè l'ubicazione di Firefox nel sistema può cambiare da piattaforma a piattaforma e da sitema a sistema), gli sviluppatori di Mozilla hanno trovato una soluzione per creare degli URI al contenuto XUL che l'applicazione installata possa conoscere.

Ad esempio, la finestra del browser è: <tt>chrome://browser/content/browser.xul</tt> Prova a digitare questa URL nella barra degli indirizzi di Firefox!

Gli URI Chrome sono composti da diversi componenti:

• Primo, lo schema URI (<tt>chrome</tt>) che comunica alla libreria del networking di Firefox che si è in presenza di un URI Chrome e che il contenuto in fase di caricamento dovrà essere trattato in modo particolare.
• Secondo, il nome del pacchetto (nel esempio sopra, <tt>browser</tt>) che identifica la serie dei componenti dell'interfaccia utente. Tale nome dovrebbe essere unico per l'applicazione, per evitare collisioni tra le estensioni.
• Terzo, il tipo di dati che viene richiesto. Ce ne sono di tre tipi: <tt>content</tt> (XUL, JavaScript, XBL bindings, etc. che plasmano la struttura ed il comportamento di un'applicazione UI), <tt>locale</tt> (file DTD, .properties, etc che contengono le stringhe per la localizzazione), e <tt>skin</tt> (CSS e immagini che disegnano il Tema della UI)
• Da ultimo, il percorso del file da caricare.

Quindi, <tt>chrome://foo/skin/bar.png</tt> carica il file <tt>bar.png</tt> dalla sezione <tt>skin</tt> del tema <tt>foo</tt>.

Quando si carica un file mediante l'URI Chrome, Firefox usa il Registro del Chrome per tradurre questi URI nella effettiva sorgente del file su disco (o nel pacchetto JAR).

Creare il manifesto di installazione

Per maggiori informazioni sul Chrome Manifest e le proprietà supportate, guarda il riferimento sul Chrome Manifest.

Apri il file chiamato <tt>chrome.manifest</tt> che hai creato insieme alla directory <tt>chrome</tt> nella root dell'estensione.

Aggiungi questo codice:

content     sample    chrome/content/

(Non dimenticare gli slash posteriori, "<tt>/</tt>"! Senza, l'estensione non verrà caricata.)

Il codice indica:

1. il tipo di materiale all'interno del pacchetto chrome
2. il nome del pacchetto chrome
3. la ubicazione dei file del pacchetto chrome

Quindi, la stringa indicata sopra dice che per il pacchetto chrome sample, si possono trovare i suoi file content all'ubicazione <tt>chrome/content</tt> che è un percorso relativo alla ubicazione di <tt>chrome.manifest</tt>.

N.B. i file content, locale e skin devono essere contenuti nelle cartelle chiamate content, locale e skin all'interno della sotto-directory <tt>chrome</tt>.

Salva il file. Quando Firefox verrà eseguito con questa estensione, (più avanti in questo tutorial), il chrome.manifest registrerà il pacchetto chrome.

Registrare un Overlay

E' necessario che Firefox fonda il tuo overlay con la finestra del browser ogni volta che ne mostra una. Quindi aggiungi questa stringa al file <tt>chrome.manifest</tt>:

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

Questo dice a Firefox di fondere <tt>sample.xul</tt> in <tt>browser.xul</tt> quando viene caricato <tt>browser.xul</tt> .

Test

Primo, devi far sapere a Firefox della tua estensione. Nei vecchi e bui giorni di Firefox 1.0 questo significava impacchettare l'estensione come un XPI e installarla attraverso l'interfaccia utente, che era davvero una faticaccia. Ora è più semplice.

1. Apri la cartella del Profilo
2. Apri la cartella dell'estensione (creala se non esiste)
3. Crea un nuovo file di testo e scrivici dentro il percorso alla cartella dell'estensione, ad es. <tt>C:\extensions\myExtension\</tt> o <tt>~/extensions/myExtension</tt>. Salva il file con l'ID dell'estensione, per esempio <tt>[email protected]</tt>

Ora sei pronto a fare un test dell'estensione!

Avvia Firefox. Firefox rileverà il link testuale alla directory dell'estensione e la installerà. Quando apparirà la finestra del browser si dovrebbe vedere la scritta "Hello, World!" sulla destra della barra di stato.

Ora puoi tornare indietro ed effettuare dei cambiamenti al file .xul, chiudere e riavviare Firefox e questi dovrebbero essere mostrati.

Impacchettamento

Ora che l'estensione funziona, può essere impacchettata per l'installazione e la circolazione.

Comprimi il contenuto della cartella dell'estensione (non la cartella stessa), e rinomina il file .zip con l'estensione .xpi. In ambiente Windows XP, si può facilmente esguire questa operazione selezionando tutti i file e le sottocartelle presenti nella cartella dell'estensione, cliccando col tasto destro del mouse e scegliendo "Invia a -> Cartella compressa". Verrà creato un file .zip. Basta rinominarlo ed il gioco è fatto!

Ora è possibile caricare il file .xpi su un server, avendo cura di controllare che offra il servizio di <tt>application/x-xpinstall</tt>. Basta quindi creare un collegamento al file sul server per permettere alle persone di scaricare e installare l'estensione su Firefox.

Utilizzare addons.mozilla.org

Mozilla Update è un sito di distribuzione dove è possibile ospitare (hosting) le proprie estensioni gratuitamente. Your extension will be hosted on Mozilla's mirror network to guarantee your download even though it might be very popular. Il sito di Mozilla garantisce inoltre agli utenti un'installazione semplificata delle estensioni, e rende automaticamente disponibili, per gli utenti che già le possiedano, gli aggiornamenti ogni volta che viene effettuato l'upload delle nuove versioni delle estensioni. In più Mozilla Update consente agli utenti di commentare e lasciare un feedback sulla estensione. E' vivamente consigliabile di utilizzare Mozilla Update per distribuire le tue estensioni!

Visita https://addons.mozilla.org/developers/ per creare un account ed iniziare a distribuire le tue estensioni!

N.B. Le tue estensioni saranno promosse più velocemente e maggiormente scaricate se fornisci una descrizione accurata e alcuni screenshot delle funzionalità dell'estensione.

Registrare le Estensioni nel registro di Windows

Su Windows, possono essere aggiunte nel registro delle informazioni sulle estensioni, cosicché l'estensione sarà automaticamente caricata all'avvio dell'applicazione. Questo permette ai programmi di installazione delle applicazioni di aggiungere facilmente dei punti di acesso perl'integrazione sottoforma di estensioni. Guarda "Aggiugere estensioni utilizzando il Registro di Windows" per ulteriori informazioni.

Altre informazioni sugli Overlay XUL

Oltre che per inserire dei componenti UI ai "punti di fusione", si possono usare i frammenti di XUL negli Overlay per:

• Modificare degli attributi al punto di fusione, es. <tt><statusbar id="status-bar" hidden="true"/></tt> (nasconde la barra di stato)
• Rimuovere il punto di fusione dal documento principale, e.g. <tt><statusbar id="status-bar" removeelement="true"/></tt>
• Controllare la posizione dei componenti inseriti:

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

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

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

Creare nuovi componenti per l'interfaccia utente

E' possibile creare proprie finestre (e finestre di dialogo) come file .xul separati, fornire nuove funzionalità implementando le azioni disponibili per l'utente nei file .js, usando il metodo DOM per manipolare i componenti UI. Si possono definire le regole di stile nei file .css per associare delle immagini, impostare i colori, etc.

Guarda la documentazione su XUL per ulteriori risorse sullo sviluppo con XUL.

File predefiniti

I file predefiniti con i quali modificare il profilo dell'utente dovrebbero essere posti nella cartella <tt>defaults/</tt> sotto la root della gerarchia di cartelle dell'estensione. I file .js che settano impostazioni predefinite dovrebbero invece essere posti nella cartella <tt>defaults/preferences/</tt> - infatti, qualora vengano ubicati in queste cartelle, saranno automaticamente caricati dal sistema di preferenze di Firefox all'avvio e sarà possibile accedervi facilmente utilizzando l'API delle Preferenze.

Componenti XPCOM

Firefox supporta anche i componenti XPCOM all'interno delle estensioni. Questi componenti possono essere facilmente creati con JavaScript o C++ (utilizzando il Gecko SDK).

Riponi tutti i file .js o .dll nella directory <tt>components/</tt> - saranno automaticamente registrati al primo avvio di Firefox successivo all'installazione dell'estensione.

Per maggiori informazioni guarda Come costruire un componente XPCOM con Javascript e il libro Creare componenti XPCOM.

Linea di comando per l'applicazione

Uno dei possibili usi dei componenti XPCOM personalizzati è quello di aggiungere una gestione a linea di comando per Firefox o Thunderbird. Questa tecnica è utile per eseguire l'estensione come se fosse un'applicazione:

 firefox.exe -myapp

Guarda Chrome: Linea di comando ed una discussione sul forum(EN) per maggiori dettagli.

Localizzazione

Per supportare più di una lingua, occorre separare le stringhe dal contenuto utilizzando le entities e le string bundles. E' più semplice effettuare questa operazione mentre si sviluppa l'estensione che dover tornare indietro e farlo alla fine!

Le informazioni sulla Localizzazione sono immagazzinate nella directory del locale dell'estensione. Per esempio, per aggiungere un locale all'estensione che abbiamo sviluppato fin ora, basta creare una directory chiamata "locale" nel chrome (dove è ubicata la directory "content") e aggiungere la seguente stringa al file chrome.manifest:

locale sample sampleLocale chrome/locale/

Per creare valori localizzabili per gli attributi XUL, è necessario inserire tali valori in un file <tt>.ent</tt> (o <tt>.dtd</tt>), che deve essere ubicato nella directory del locale ed avere questo aspetto:

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

E quindi includere all'inizio del documento XUL (ma dopo il prologo "<?xml version"1.0"?>") qualcosa del genere:

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

dove window è il valore localName dell'elemento di root del documento XUL, ed il valore della proprietà <tt>SYSTEM</tt> è l'URI chrome al file dell'entità (entity). Nell'estensione dell'esempio, l'elemento di root è overlay.

Per usare le entità occorre modificare il proprio XUL così:

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

Il Registro del Chrome farà in modo che il file dell'entità venga caricato dalla cartella del locale corrispondente al locale selezionato.

Per le stringhe usate negli script crea un file .properties: un file di testo che contiene una stinga per ogni linea in questo formato:

chiave=valore

e utilizza il tag <tt>nsIStringBundleService</tt>/<tt>nsIStringBundle</tt> o il tag <tt><stringbundle></tt> per caricare i valori negli script.

Conoscere il Browser

Usa il DOM Inspector (non è parte dell'installazione Standard di Firefox, se manca dal menu Strumenti occorre reinstallare Firefox con l'opzione "installazione personalizzata" e selezionare Strumenti di sviluppo) per esplorare la finestra del browser ed ogni altra finestra XUL che hai l'intenzione di estendere.

Utilizza il pulsante in alto a sinistra nella bara degli strumenti del DOM Inspector per attivare la modalità di ricerca dei nodi "punta-e-clicca": in tal modo basterà un clic visuale su un nodo nella finestra XUL per selezionarlo. Effettuando quest'operazione l'albero della gerarchia DOM del DOM inspector salterà automaticamente al nodo selezionato.

Usa il pannello di destra del DOM Inspector per trovare i punti di fusione e gli "id" da usare per inserire gli elementi tramite l'overlay. Se non riesci a trovare un elemento che abbia un'id sulla quale sia possibile effettuare l'inserimento, potrebbe essere necessario aggiungere uno script nell'overlay per inserire i propri elementi quando l'evento <tt>load</tt> si attiva nella finestra XUL principale.

Effettuare il debug sull'estensione

Strumenti per il debug analitico

• Il DOM Inspector - ispeziona gli attributi, la struttura DOM, le regole di stile CSS che sono attive (ad es. si può capire perché le proprie regole di stile non sembrano funzionare per un elemento - uno strumento inestimabile!)
• Venkman - imposta i punti d'arresto in JavaScript ed esamina le call stacks
• arguments.callee.caller in JavaScript - accede allo stack di chiamata di una funzione

Debug con printf

• Esegui Firefox con il parametro <tt>-console</tt> sulla linea di comando e utilizza dump("string") (guarda il link per dettagli)
• Utilizza nsIConsoleService per accedere alla console JavaScript

Debug avanzato

• Esegui una build di debug di Firefox ed imposta dei punti di arresto in Firefox stesso, o nei tuoi componenti C++. Per gli sviluppatori esperti, questa è spesso il modo più veloce per diagnosticare un problema. Guarda la Documentazione sulla build e Sviluppare Mozilla per ulteriori informazioni.
• Guarda Eseguire un debug su un'applicazione XULRunner per altri suggerimenti utili.

Iniziare velocemente

Può essere utilizzato lo strumento online Extension Wizard(EN) per generare una semplice estensione.

Un'estensione "Hello World"(EN) simile a quella prodotta dall'Extension Wizard è spiegata passo-passo in un altro tutorial di MozillaZine(EN).