Un generador de microsumaris és un conjunt d'instruccions per a crear un microsumari a partir del contingut d'una pàgina. Les pàgines web poden fer referència als generadors a través d'elements <link rel="microsummary"> en llurs elements de capçalera <head>. Els generadors també poden baixar-se i instaŀlar-se de forma independent pels usuaris si aquests inclouen una llista de les pàgines a les quals s'apliquen.
En aquest tutorial crearem un generador de microsumaris per a la pàgina d'inici d'Spread Firefox. Es mostrarà el recompte actual de baixades del Firefox juntament amb l'etiqueta baixades del Firefox; per exemple: 174475447 baixades del Firefox.
També crearem un full de transformació XSLT que converteix la pàgina en el seu microsumari, aprendrem com especificar que el generador s'apliqui en aqueixa pàgina, i esbrinarem com fer el generador disponible perquè pugui baixar-se i instaŀlar-se.
En cada pas de la revisió del full de transformació, com altre codi del tutorial, el text que s'afegeixi es mostrarà en negreta perquè el procés pugui seguir-se més fàcilment.
Inici
Els generadors són documents XML que tenen com element arrel l'etiqueta <generator> en l'espai de noms https://www.mozilla.org/microsummaries/0.1. Per a començar a crear un generador, partim d'un nou fitxer de text buit i li afegim una declaració XML i un element <generator> buit:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1"> </generator>
Donant-li un nom
Els generadors cal que tinguin atributs de nom que són descripcions arbitràries dels microsumaris que el generador crea. Cal que els noms siguin suficientment descriptius perquè els usuaris puguin fer-se una idea de quina informació es proporciona des dels microsumaris. Atès que el nostre generadpr crearà microsumaris que mostren el recompte baixades del Firefox, un nom adequat pot ser «Recompte de baixades del Firefox»:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del Firefox"> </generator>
Addició d'un full de transformació XSLT
Els generadors han d'incloure un full de transformació XSLT (també conegut com full d'estil XSLT) que transformi el contingut de la pàgina en el seu microsumari. L'XLST és un potent llenguatge per a transformar documents en diferents representacions de la mateixa informació.
Afegiu el full de transformació XSLT al generador incloent-hi l'element <template>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> </transform> </template> </generator>
Tingueu en compte que mentre els generadors de microsumaris poden incloure codi XSLT arbitrari, si incorporeu XSLT que produeixi sortida en text ric, el Firefox actualment només podrà mostrar-la en text net.
Especificació d'un tipus de sortida
Atès que el full de transformació XSLT generarà un microsumari en format text, cal que ho indiquem amb l'element <output>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> </transform> </template> </generator>
Ús d'una plantilla d'XSLT simple, <template>
El processador d'XSLT transforma els documents comparant cada element XSLT en el full de transformació amb el conjunt de nodes del document. Quan un atribut de <template> coincideix amb el d'un node, el processador realitza les transformacions que s'especifiquen en el contingut de l'element.
Aquest és un potent mecanisme, perquè us permet recòrrer l'àrbol de nodes d'un document, generant recursivament una sortida basada en els continguts del document. Per a generar un microsumari per a la pàgina d'Spread Firefox page, només ens cal un únic element <template> que coincideixi amb el node arrel del document i que es processi d'una vegada:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> </template> </transform> </template> </generator>
Incloure el recompte de baixades
Per a incloure el recompte de baixades en la sortida del full de transformació XSLT, cal que afegim l'element XSLT <value-of> a la plantilla del qual l'atribut de selecció select conté una expressió XPath que apunta al node que conté el recompte.
L'XPath és un llenguatge per a identificar nodes en documents HTML/XML. També conté funcions bàsiques per a manipular aqueixos nodes i llur contingut. La forma més fàcil d'obtenir una expressió XPath que apunti al node en qüestió és utilitzar l'[extensió XPath Checker.
Instaŀleu l'extensió (reinicie el Firefox per a completar la instaŀlació), a continuació aneu a la pàgina d'inici d'Spread Firefox, cerqueu el recompte de baixades del Firefox (un gran número a sota de la columna dreta), cliqueu amb el botó secondari al número, i seleccioneu Visualitza l'XPath des del menú contextual.
L'XPath Checker obrirà una nova finestra. Aquesta inclourà un camp d'XPath que conté l'expressió XPath que a punta al node del recompte de baixades: id('download-count').
Afegeix un element <value-of> a l'element XSLT <template>, el qual el seu atribut <select> conté l'expressió XPath:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del 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>
Addició d'un text
Per a incloure l'etiqueta de baixades del Fx en el microsumari, cal que afegim un element XSLT a l'element XSLT <template>, el contingut del qual és el text que volem afegir.
Afegeix un element <text> a la plantilla XSLT amb el contingut de baixades del Firefox:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del 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>Baixades del Firefox</text> </template> </transform> </template> </generator>
Tingueu en compte que l'espai en blanc entre les etiquetes XSLT no apareix a la sortida de l'XSLT, a diferència de l'HTML, on aquell espai en blanc esdevé un espai simple. Per això, assegureu-vos llavors d'incloure un espai a la frase per a separar-la del recompte de baixades.
Amb aquesta addició, hem acabat d'escriure el full de transformació XSLT que permet crear un microsumari a partir de la pàgina d'inici de l'Spread Firefox.
Especifar en quina pàgina s'aplica el generador
Ara que ja hem escrit un full de transformació, hem d'especificar la pàgina on s'aplica. Si fóssim els webmestres d'Spread Firefox, podríem simplement referenciar el generador dins de la mateixa pàgina afegint l'etiqueta <link rel="microsummary"> dins de l'element <head>:
<head> ... <link rel="microsummary" href="camí/al/nostre/generador.xml"> </head>
Atès que no en som els webmestres, podem especificar la pàgina on s'aplica dins del mateix generador i fer-lo disponible perquè pugui baixar-se i instaŀlar-se. Per a especificar les pàgines on s'aplica el generador, utilitzem l'element <pages> dins de l'element <generator>:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del 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>Baixades del Firefox</text> </template> </transform> </template> <pages> </pages> </generator>
L'element <pages> pot contenir una seqüència d'elements <include> i <exclude> que especifica les pàgines on el generador s'aplica i no s'aplica, respectivament.
Per a fer que un generador s'apliqui a una pàgina, afegiu un element <include> el contingut del qual sigui una expressió regular que coincideixi amb la pàgina. Per a fer que el generador no s'apliqui a una pàgina, afegiu un element <exclude> el contingut del qual sigui una expressió regular que també coincideixi amb la pàgina.
Per defecte, els generadors no s'apliquen a cap pàgina, per això heu de llistar-les explícitament a les pàgines on s'apliquen, i no heu d'excloure cap pàgina excepte si les haguéssiu inclós anteriorment.
Afegiu un element <include> que coincideixi amb la pàgina d'Spread Firefox:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Recompte de baixades del 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> Fx downloads</text> </template> </transform> </template> <pages> <include>https://(www\.)?spreadfirefox\.com/(index\.php)?</include> </pages> </generator>
Fer el generador disponible per a baixar-se
Ara que el generador s'aplica a la pàgina d'inici de l'Spread Firefox, només queda fer-lo disponible per a ser descarregat. Per a fer-ho, cal que el posem al web i creem un enllaç Javascript en alguna pàgina web que faci una crida al mètode del Firefox window.sidebar.addMicrosummaryGenerator() per a baixar i instaŀlar el generador.
Per exemple, si posem el fitxer del generador a https://people.mozilla.com/~myk/micro...-generator.xml, i volguéssim que els usuaris poguessin instaŀlar-lo de from https://people.mozilla.com/~myk/micro...ial/index.html, podríem afegir el següent codi a la pàgina index.html:
<a href="javascript:window.sidebar.addMicrosummaryGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Instaŀla el microsumari de la pàgina d'inici de l'Spread Firefox!</a>
En clicar aquest enllaç, es generarà un error de JavaScript en els navegadors que no permeten utilitzar microsumaris, no obstant això, per a millorar la navegació d'aqueixos usuaris, hauríem de comprovar si utilitzen un navegador que accepti microsumaris, i per altra banda, mostrar un missatge explicatiu si no. Podem fer-ho amb aquest codi:
<script>
const warning = "Us cal un navegador que permeti utilitzar microsumaris, com ara el Firefox 2.0, per a instaŀlar i utilitzar generadors de microsumaris.";
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')">Instaŀla el microsumari de la pàgina d'inici de l'Spread Firefox!</a>
Conclusió
Ara ja hauríeu de tenir un generador de microsumaris que mostri el recompte de baixades del Firefox quan l'instaŀleu. Afegiu la pàgina d'inici de l'Spread Firefox a les adreces d'interès, i seleccioneu-ne el microsumari del menú desplegable en el diàleg Afegeix a les adreces d'interès.
Per a més informació, consulteu la pàgina d'inici dels microsumaris (en anglès).