Un generatore di microsommari è un insieme di istruzioni per creare un microsommario a partire dal contenuto di un documento. Le pagine possono essere collegate ai generatori tramite <link rel="microsummary">, che va inserito nell'elemento <head>. I generatori possono anche essere scaricati in maniera indipendente e installati dagli utenti, se questi scrivono una lista di pagine alla quale i generatori devono essere associati.
In questo articolo creeremo un generatore di microsommario per la home page di SpreadFirefox che mostra il numero di download del browser con l'etichetta Fx downloads; per esempio: 174475447 Fx downloads.
Costruiremo poi il foglio stile XSLT che converte la pagina in un microsommario e impareremo a specificare che il generatore si applica proprio a quella pagina; infine impareremo a preparare il generatore per il download e l'installazione.
In ogni passo della creazione del foglio stile, ciò che viene aggiunto rispetto all'esempio precedente è in grassetto per facilitarne l'identificazione.
Iniziare
I generatori si presentano come documenti XML, la cui radice è l'elemento <generator> e il namespace è https://www.mozilla.org/microsummaries/0.1. Per iniziare a costruire il generatore, creiamo un nuovo file di testo vuoto, poi inseriamo la dichiarazione XML e l'elemento radice:
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1">
</generator>
Il nome
Ogni generatore dovrebbe essere dotato di attributi name, che forniscono descrizioni arbitrarie dei microsommari. I nomi dovrebbero essere abbastanza descrittivi da dare all'utente un'idea di quali informazioni vengono fornite dal microsommario. Siccome il nostro generatore creerà dei microsommari che mostrano il conteggio dei download di Firefox, lo chiameremo "Download di Firefox":
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1"
name="Download di Firefox">
</generator>
Creare un foglio stile XSLT
I generatori devono includere un foglio stile XSLT (o trasformazione XSLT), che trasforma il contenuto della pagina in un microsommario. XSLT è un potente linguaggio per trasformare i documenti in rappresentazioni diverse delle stesse informazioni.
Aggiungiamo quindi il foglio stile includendolo in un elemento <template>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> </transform> </template> </generator>
Si noti che, mentre i generatori di microsommari includono del codice XSLT arbitrario, compreso codice che produca un output formattato, Firefox attualmente visualizza soltanto una versione di puro testo dell'output XSLT.
Specificare il tipo di output
Siccome il foglio stile genera un sommario testuale, dovremmo indicarlo nell'elemento <output>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> </transform> </template> </generator>
Utilizzare un semplice <template>
L'elaboratore XSLT trasforma i documenti comparando ogni elemento <template> presente nel foglio stile con un insieme di nodi del documento. Quando trova un attributo match, dell'elemento <template>, l'elaboratore esegue le trasformazioni specificate nel contenuto dell'elemento stesso.
Questo è un meccanismo potente, perchè permette di attraversare l'albero di un documento, generando ricorsivamente un output basato sui contenuti. Ma, per gli scopi di un microsommario per la pagina di Spread Firefox, necessitiamo di un solo <template> che corrisponde al nodo radice del documento e che viene processato una volta sola:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> </template> </transform> </template> </generator>
Inserire il conteggio dei download
Per inserire il conteggio dei download nell'output del foglio stile, occorre aggiungere un elemento <value-of> al template il cui attributo select contiene un'espressione XPath che punta al nodo che contiene il numero da visualizzare.
XPath è un linguaggio che serve a identificare i nodi nei documenti HTML o XML. Contiene anche alcuni funzioni basilari per la manipolazione dei nodi e del loro contenuto. Il modo più semplice per ottenere una espressione XPath che punti al nodo desiderato è utilizzare l'estensione XPath Checker.
Quindi installiamo l'estensione e riavviamo Firefox quando l'installazione è completa. Andiamo quindi alla home page di Spread Firefox, troviamo il conteggio dei download (un numero grande nella colonna di destra), clicchiamo col tasto detro del mouse su tale informazione e selezioniamo View XPath nel menù a comparsa.
XPath Checker aprirà una nuova finestra. La nuova finestra contiene un campo XPath che contiene l'espressione XPath desiderata, che punta al numero di download: id('download-count').
Aggiungiamo un elemento <value-of> dentro <template>, con un attributo select che contiene detta espressione XPath:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <value-of select="id('download-count')"/> </template> </transform> </template> </generator>
Inserire del testo
Per inserire l'etichetta Fx downloads nel microsommario, occorre aggiungere un elemento <text> in <template>, il cui contenuto sarà il testo che si desidera inserire.
Aggiungiamo quindi un elemento <text>, il cui contenuto è Fx downloads:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <value-of select="id('download-count')"/> <text> download</text> </template> </transform> </template> </generator>
Si noti che lo spazio bianco tra i tag XSLT non viene incluso nell'output, diversamente da quanto accade in HTML, dove invece tutti gli spazi vengono riuniti in un singolo spazio, quindi facciamo attenzione a inserire uno spazio prima della frase "download" per separarla dal numero.
Con questo, abbiamo terminato di scrivere il foglio stile XSLT che converte la pagina principale di Spread Firefox in un microsommario.
Specificare a quale pagina di riferisce il generatore
Ora che abbiamo terminato il foglio stile, dobbiamo specificare a quale pagina si applica. Se fossimo i webmaster di Spread Firefox, sarebbe sufficiente inserire un riferimento al generatore nella pagina stessa aggiungendo un tag <link rel="microsummary"> nella sezione <head> del documento:
<head> ... <link rel="microsummary" href="path/to/our/generator.xml"> </head>
Siccome però non siamo i webmaster di quel sito, possiamo specificare la pagina al quale si applica il generatore dentro al generatore stesso e poi renderlo disponibile per il download e l'installazione. Per specificare la pagina, utilizziamo un elemento <pages>, figlio di <generator>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <value-of select="id('download-count')"/> <text> download</text> </template> </transform> </template> <pages> </pages> </generator>
Tale elemento può contenere una sequenza di tag <include> e <exclude> che specificano, rispettivamente, a quali pagine il generatore si applica e non si applica.
Per far sì che il generatore si applichi a una pagina, si può aggiungere un elemento <include>, il cui contenuto è un'espressione regolare che corrisponde alla pagina (o alle pagine). Per far sì che il generatore invece ignori una pagina, è necessario inserire un elemento <exclude>, il cui contenuto è anch'esso un'espressione regolare.
Per default i generatori non si applicano ad alcuna pagina, quindi è possibile elencare esplicitamente a quali pagine si applica e non è necessario escludere altre pagine, a meno che non siano state precedentemente incluse.
Aggiungiamo un elemento <include> che corrisponda alla home page di Spread Firefox:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Download di Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <value-of select="id('download-count')"/> <text> download</text> </template> </transform> </template> <pages> <include>https://(www\.)?spreadfirefox\.com/(index\.php)?</include> </pages> </generator>
Rendere il generatore disponibile per il download
Ora che il nostro generatore si applica alla home page di Spread Firefox, l'unica cosa rimasta da fare è renderlo scaricabile. Per fare questo, dobbiamo caricarlo in rete e creare un link JavaScript in una qualche pagina che chiami il metodo di Firefox window.sidebar.addMicrosummaryGenerator() per scaricarlo e installarlo.
Per esempio, se carichiamo il generatore all'indirizzo https://people.mozilla.com/~myk/micro...-generator.xml e vogliamo che gli utenti possano installarlo da https://people.mozilla.com/~myk/micro...ial/index.html, possiamo aggiungere il seguente codice alla pagina index.html:
<a href="javascript:window.sidebar.addMicrosummaryGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Installa il microsommario della pagina principale di Spread Firefox!</a>
Cliccando sul link, si genera un errore JavaScript sui browser che non supportano i microsommari, pertanto si può migliorarlo controllando se i microsommari sono supportati. Potremmo farlo con il codice seguente:
<script>
const warning = "Spiacente, ma è necessario un browser che supporti i microsommari, come Firefox 2.0";
function addGenerator(url) {
if (typeof window.sidebar == "object" &&
typeof window.sidebar.addMicrosummaryGenerator == "function")
window.sidebar.addMicrosummaryGenerator(url);
else
alert(warning);
}
</script>
<a href="javascript:addGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Installa il microsommario della pagina principale di Spread Firefox!</a>
Conclusione
Abbiamo creato un generatore di microsommari che, una volta installato, mostra il numero attuale di download di Firefox e seleziona il microsommario dal menu a discesa Summary nella finestra Add Bookmark.
Per ulteriori informazioni sui microsommari, si veda Microsummaries home page (EN).