Creare estensioni per Firefox - livello 1
Autore: Lodolo Francesco
email: flod[at]extenzilla[dot]it
Versione documento: 1.0
Ultima modifica: 19 agosto 2004
In questa guida verrà spiegato come creare una semplice estensione, perfettamente funzionante, da installare in Firefox.
L'estensione utilizzata nell'esempio è scaricabile da qui.
Prima di partire facciamo un piccolo elenco delle cose indispensabili per partire con la creazione dell'estensione:
- un'idea da realizzare
- una discreta conoscenza dei linguaggi utilizzati nella creazione di un'estensione (Javascript, CSS, XUL)
- un editor di testi, meglio se in grado di colorare il codice (ad es. Kate o Kwrite per Linux oppure EditPad Lite per Windows)
- un software per gestire i file zip (es. zip-genius per Windows o Ark per Linux)
Il consiglio è di fare tutte le prove usando un profilo nuovo in Firefox, in modo da non danneggiare il profilo che si utilizza abitualmente.
Javascript viene utilizzato per scrivere il motore dell'estensione; su Internet esistono centinaia di script e di guide che possono risultare molto utili per apprendere questo linguaggio.
Un libro che mi sento di consigliare è Javascript Bible di Danny Goodman, arrivato alla quinta edizione (ISBN 0-7645-5743-2 ,1200 pagine), e il relativo Javascript Examples Bible (ISBN 0-7645-4855-7 ,500 pagine).
Il linguaggio XUL viene utilizzato per costruire le finestre e quindi l'interfaccia delle estensioni. In questo caso il migliore punto di partenza è XUL Planet, dove è disponibile un'ottima guida (in inglese) a questo indirizzo.
Idea da realizzare
In questo caso l'idea iniziale è decisamente semplice: creare una voce "Saluta", nel menu Strumenti, che visualizzi il messaggio "Ciao a tutti!" usando la funzione javascript alert.
La nostra estensione si chiamerà ciao.xpi
Creare la struttura delle cartelle
Per prima cosa creare una cartella in cui inserire i file, chiamandola per comodità ciao_jar (il motivo di questi nomi sarà più chiaro successivamente).
All'interno di questa, creare la seguente struttura di directory:
- ciao_jar\
- ciao_jar\content
- ciao_jar\content\ciao
- ciao_jar\skin
- ciao_jar\skin\classic\ciao
Creare una nuova cartella, chiamandola ciao_xpi, e all'interno di questa creare una directory Chrome realizzando questa struttura:
- ciao_xpi\
- ciao_xpi\chrome
Il file contents.rdf in /content/ciao/
Consideriamo la cartella content, che conterrà l'estensione vera e propria.
Per prima cosa bisogna creare un file contents.rdf, che specifica le caratteristiche della nostra estensione.
Il file in questione conterrà queste stringhe:
<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
<RDF:Seq RDF:about="urn:mozilla:package:root">
<RDF:li RDF:resource="urn:mozilla:package:ciao"/>
</RDF:Seq>
<RDF:Seq RDF:about="urn:mozilla:overlays">
<RDF:li RDF:resource="chrome://browser/content/browser.xul"/>
<RDF:li RDF:resource="chrome://navigator/content/navigator.xul"/>
</RDF:Seq>
<RDF:Seq RDF:about="chrome://browser/content/browser.xul">
<RDF:li>chrome://ciao/content/ciaoOverlay.xul</RDF:li>
</RDF:Seq>
<RDF:Seq about="chrome://navigator/content/navigator.xul">
<RDF:li>chrome://ciao/content/ciaoOverlay.xul</RDF:li>
</RDF:Seq>
<RDF:Description RDF:about="urn:mozilla:package:ciao"
chrome:displayName="Ciao a tutti!"
chrome:author="flod"
chrome:authorURL="mailto:flod@extenzilla.it"
chrome:name="ciao"
chrome:extension="true"
chrome:description="Visualizza un saluto attraverso il menu Strumenti.">
</RDF:Description>
</RDF:RDF>
All'inizio, nella parte in blu, viene specificato il nome dell'estensione urn:mozilla:package:ciao.
Nella parte centrale viene dichiarato che verrà utilizzata il file ciaoOverlay.xul.
Alla fine, nella parte in nero, si trovano le informazioni sull'estensione (autore, sito web, ecc.).
Il file ciaoOverlay.xul in content/ciao/
Questo è il contenuto del file xul
<?xml version="1.0"?>
<overlay id="ciaoOverlay" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<script type="application/x-javascript" src="chrome://ciao/content/ciaoOverlay.js" />
<menupopup id="menu_ToolsPopup">
<menuitem insertafter="devToolsSeparator" label="Saluta" accesskey="u" oncommand="ciao();" />
</menupopup>
</overlay>
All'interno dei tag script (indicato in blu) viene specificato di utilizzare un file javascript esterno, ciaoOverlay.js, contenente il codice della funzione ciao().
Trattandosi di javascript, bisogna porre attenzione alla differenza tra maiuscole e minuscole.
All'interno dei tag <menupopup> (indicato in rosso) si trova la parte fondamentale di questa estensione; viene richiesto di creare una nuove voce di menu:
- all'interno del menu con id menu_ToolsPopup, che altro non è che il menu strumenti
- chiamata "Saluta" (label)
- con scorciatoia da tastiera u (accesskey)
- che esegue la funzione ciao() quando selezionata
Il file ciaoOverlay.js in content/ciao/
Questo è il contenuto del file js
function ciao() {
alert("Ciao a tutti!");
}
Come è evidente, il codice è talmente semplice che avremmo potuto inserire il codice direttamente nel file xul.
Il file contents.rdf in /skin/classic/ciao/
Questo è il contenuto del file contents.rdf in /skin/classic/ciao
<?xml version="1.0"?>
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
<RDF:Seq about="urn:mozilla:skin:root">
<RDF:li resource="urn:mozilla:skin:classic/1.0" />
</RDF:Seq>
<RDF:Description about="urn:mozilla:skin:classic/1.0">
<chrome:packages>
<RDF:Seq about="urn:mozilla:skin:classic/1.0:packages">
<RDF:li resource="urn:mozilla:skin:classic/1.0:ciao" />
</RDF:Seq>
</chrome:packages>
</RDF:Description>
</RDF:RDF>
L'unica parte eventualmente da modificare è quella indicata in rosso.
A questo punto le operazioni sulla cartella ciao_jar sono concluse.
Creare il file ciao.jar
La prossima operazione è creare un file zip con il contenuto della cartella ciao_jar; a questo punto bisogna porre particolare attenzione al percorso con cui vengono archiviati i file all'interno dello zip, che deve essere relativo e non assoluto, come nell'immagine seguente.
Per concludere rinominare il file zip appena creato in ciao.jar (è fondamentale cambiare l'estensione del file da zip a jar) e copiarlo nella cartella ciao_xpi\chrome
Creare i file di installazione install.js e install.rdf
Adesso bisogna creare, all'interno della cartella ciao_xpi i due file necessari per rendere possibile l'installazione della nostra estensione all'interno di Firefox; i due file si chiamano install.js ed install.rdf
Cominciamo con il file install.js, che viene utilizzato per le vecchie versioni di Firefox e Mozilla Suite.
/****************
Desc: Installation script For Mozilla Suite, Firefox prior to 0.9
****************** */
const author = "flod";
const displayName = "ciao a tutti!";
const name = "ciao";
const version = "0.1";
var contentFlag = CONTENT | PROFILE_CHROME;
var error = null;
var folder = getFolder("Profile", "chrome");
var localeFlag = LOCALE | PROFILE_CHROME;
var skinFlag = SKIN | PROFILE_CHROME;
var jarName = name + ".jar";
var existsInApplication = File.exists(getFolder(getFolder("chrome"), jarName));
var existsInProfile = File.exists(getFolder(folder, jarName));
const SUCCESS_MESSAGE = " e' stato installato correttamente";
initInstall(displayName, name, version);
// If the extension exists in the application folder or
//it doesn't exist in the profile folder and the user
//doesn't want it installed to the profile folder
if(existsInApplication || (!existsInProfile && !confirm("Vuoi installare "
+"questa estensione nella cartella del tuo profilo?\n(Premendo Cancel questa estensione "
+"verra' installata nella cartella principale del tuo Browser)")))
{
contentFlag = CONTENT | DELAYED_CHROME;
folder = getFolder("chrome");
localeFlag = LOCALE | DELAYED_CHROME;
skinFlag = SKIN | DELAYED_CHROME;
}
setPackageFolder(folder);
error = addFile(author, version, 'chrome/' + jarName, folder, null);
// If adding the JAR file succeeded
if(error == SUCCESS)
{
folder = getFolder(folder, jarName);
registerChrome(contentFlag, folder, "content/ciao/");
error = performInstall();
// If the install failed
if(error == SUCCESS || error == 999)
{
alert(displayName+" "+version+" e' stata installata con successo.\n");
}else{
alert("Installazione non riuscita. Codice errore:" + error);
cancelInstall(error);
}
}
else
{
alert("L'installazione della estensione non e' riuscita.\n" + error + "\n"
+"Non sono riuscito a creare " +jarName+ " \n"
+"Controlla di avere tutti i permessi per effettuare tale operazione");
cancelInstall(error);
}
Si tratta di un file standard, in cui le parti da modificare sono poche ed abbastanza semplici da individuare; per comodità sono indicate in rosso.
È fondamentale non utilizzare caratteri non consentiti, come ad esempio le lettere accentate.
Questo invece è il contenuto del file install.rdf; anche in questo caso le parti da modificare rispetto al file standard sono segnate in rosso.
<?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>{a2f5c06d-41fe-4444-b9f4-4a3fa25adc77}</em:id>
<em:name>Ciao a tutti!</em:name>
<em:version>0.1</em:version>
<em:description>Visualizza un saluto attraverso il menu Strumenti.</em:description>
<em:creator>flod</em:creator>
<em:homepageURL>http://www.extenzilla.it</em:homepageURL>
<em:file>
<Description about="urn:mozilla:extension:file:ciao.jar">
<em:package>content/ciao/</em:package>
<em:skin>skin/classic/ciao/</em:skin>
</Description>
</em:file>
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>0.7</em:minVersion>
<em:maxVersion>0.9+</em:maxVersion>
</Description>
</em:targetApplication>
</Description>
</RDF>
Le parti segnate in rosso sono semplicemente da modificare in base alla propria estensione; maggiore attenzione deve essere posta alle altre stringhe colorate.
La stringa in blu {a2f5c06d-41fe-4444-b9f4-4a3fa25adc77}, è l'id della nostra estensione ed è univoco per ogni estensione; in altri termini, non possono esistere due estensioni con lo stesso id.
Una volta installata l'estensione, il file jar, nel nostro caso ciao.jar, è rintracciabile nella cartella del profilo, all'interno della cartella \extensions\id-estensione.
Per generare questo id, è possibile ricorrere a script perl disponibili online come questo, oppure usare software esterni:
- Windows: GUIDGEN
- Linux: usare il comando shell uuidgen
Questo id, è diverso da quello indicato in arancio, {ec8030f7-c20a-464f-9b0e-13a3a9e97384}: questo infatti è l'id di Firefox, la "target application", e non va modificato per nessun motivo.
L'ultimo valore da considerare è la "target version": questo indica le versioni con cui l'estensione è compatibile.
Per le estensioni compatibili con gli attuali browser (Firefox 0.9.3), il valore è 0.9+; ovviamente questo dovrà essere aggiornato con l'uscita di Firefox 1.0
Creare il file ciao.xpi
A questo punto bisogna creare il file ciao.xpi.
È sufficiente creare un file zip con il contenuto della cartella ciao_xpi, ponendo attenzione anche in questo caso al percorso dei file; al termine dell'operazione rinominare il file in ciao.xpi togliendo l'estensione zip.
A questo punto l'estensione ciao.xpi è pronta per essere installata in Firefox.
Questa è l'estensione installata nel gestore estensioni
Questo è il menu aggiunto dall'estensione
Questo è il risultato del comando
