Un générateur de microrésumé est un ensemble d'instructions permettant de créer un microrésumé à partir du contenu d'une page. Les pages Web peuvent faire référence à de tels générateurs à l'aide d'éléments <link rel="microsummary"> au sein de leur section <head>. Il est également possible pour les utilisateurs de télécharger et d'installer des générateurs indépendamment si ceux-ci comprennent une liste de pages auxquelles ils s'appliquent.
Dans ce tutoriel, nous créerons un générateur de microrésumé pour la page d'accueil de Spread Firefox qui affichera le compteur de téléchargements de Firefox entouré d'un peu de texte ; par exemple Fx : 195728643 téléchargements.
Nous construirons la feuille de transformation XSLT convertissant la page en son microrésumé, apprendrons comment indiquer que le générateur s'applique à cette page et découvrirons comment rendre ce générateur téléchargeable et installable.
À chaque étape de construction de la feuille de transformation et des autres codes dans ce tutoriel, les ajouts seront affichés en caractères gras pour faciliter la lecture.
Note : si vous êtes développeur de sites et que vous voulez créer des microrésumés, vous pouvez écrire des générateurs, mais il est plus simple et plus efficace de créer les microrésumés du côté serveur en utilisant les mêmes outils et langages que ceux utilisés pour générer les pages.
Par exemple, si vous utilisez des scripts PHP pour générer les pages de votre site, vous pourriez écrire du code PHP pour créer un microrésumé lorsque le paramètre view=microsummary se trouve dans l'adresse, puis renseigner le générateur au sein de la page à l'aide d'une balise <link rel="microsummary"> :
<head> <link rel="microsummary" href="index.php?view=microsummary"> </head>
Lorsque Firefox rencontre une balise <link rel="microsummary">, il charge l'adresse renseignée dans l'attribut href. Si celle-ci pointe vers un générateur, il l'utilise pour générer un microrésumé pour la page. Par contre, si le lien renvoie un fichier texte (ou du contenu HTML pouvant être converti en texte simple), Firefox utilise son contenu comme microrésumé pour la page.
Pour commencer
Les générateurs s'expriment sous la forme de documents XML dont l'élément racine est <generator> dans l'espace de nommage https://www.mozilla.org/microsummaries/0.1. Pour commencer à construire le générateur, créez un nouveau fichier texte vide, ajoutez une déclaration XML et une balise <generator> vide :
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1">
</generator>
Baptiser un générateur
Les générateurs doivent être dotés d'attributs name qui sont des descriptions arbitraires des microrésumés créés. Ces noms doivent être suffisamment descriptifs pour donner aux utilisateurs une bonne idée de l'information fournie par les microrésumés. Comme notre générateur créera des microrésumés affichant le compteur de téléchargements de Firefox, appelons-le « Compteur de téléchargements de Firefox » :
<?xml version="1.0" encoding="UTF-8"?>
<generator xmlns="https://www.mozilla.org/microsummaries/0.1"
name="Compteur de téléchargements de Firefox">
</generator>
Ajout d'une feuille de transformation XSLT
Les générateurs doivent fournir une feuille de transformation XSLT (également appelée feuille de style XSLT) qui transformera le contenu de la page en son microrésumé. XSLT est un puissant langage de transformation de documents en d'autres représentations de la même information.
Ajoutez la feuille de transformation XSLT au générateur en la déclarant au sein d'un élément <template> :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> </transform> </template> </generator>
Notez que si les générateurs de microrésumés peuvent contenir n'importe quel code XSLT, même un code contenant des instructions de formatage, Firefox n'affiche pour l'instant que la version texte de la sortie XSLT.
Spécification du type de sortie
Puisque la feuille de transformation XSLT va générer un microrésumé texte, il faut l'indiquer dans l'élément XSLT <output> :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> </transform> </template> </generator>
Utilisation d'un <template> XSLT simple
Le processeur XSLT transforme les documents en comparant chaque élément XSLT <template> de la feuille de transformation en un ensemble de nœuds dans le document. Lorsque l'attribut match d'un élément <template> correspond à un nœud, le processeur effectue la transformation spécifiée au sein de l'élément.
Ce mécanisme est très puissant, car il permet de traverser l'arbre des nœuds d'un document, en générant récursivement une sortie basée sur le contenu du document. Mais dans le cas d'un microrésumé pour la page de Spread Firefox, nous aurons juste besoin d'un seul élément <template> correspondant au nœud racine du document et qui sera traité une seule fois :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> </template> </transform> </template> </generator>
Inclusion du compteur de téléchargements
Pour inclure le compteur de téléchargements dans la sortie de la feuille de transformation XSLT, il est nécessaire d'ajouter un élément XSLT <value-of> au template dont l'attribut select contient une expression XPath pointant vers le nœud contenant le compteur.
XPath est un langage permettant d'identifier des nœuds dans des documents HTML/XML. Il fournit également quelques fonctions basiques permettant de manipuler ces nœuds et leur contenu. La manière la plus simple d'obtenir une expression XPath pointant vers le nœud désiré est d'utiliser l'extension XPath Checker.
Installez l'extension (en redémarrant Firefox pour terminer l'installation) et rendez-vous ensuite sur la page d'accueil de Spread Firefox, trouvez le compteur de téléchargements de Firefox (un grand nombre en bas de la colonne de droite), cliquez avec le bouton de droite sur ce nombre et choisissez View XPath dans le menu contextuel.
XPath Checker ouvrira une nouvelle fenêtre. Celle-ci contiendra un champ XPath contenant l'expression XPath qui pointe vers le nœud du compteur de téléchargements : id('download-count').
Ajoutez un élément <value-of> dont l'attribut select contient cette expression XPath à l'élément <template> :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de 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>
Ajout de texte
Pour ajouter du texte dans le microrésumé, nous devrons ajouter des éléments XSLT <text> contenant le texte désiré à l'élément <template>.
Ajoutez des éléments <text> au template XSLT contenant Fx : et téléchargements:
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <text>Fx : </text> <value-of select="id('download-count')"/> <text> téléchargements</text> </template> </transform> </template> </generator>
Notez que les espaces blancs entre les balises XSLT ne sont pas repris dans la sortie XSLT, contrairement au HTML où les espaces sont condensés en un seul caractère espace, assurez-vous donc d'ajouter un espace devant le mot téléchargements pour qu'il ne soit pas collé au nombre de téléchargements.
Avec cet ajout, nous avons terminé d'écrire la feuille de transformation XSLT qui convertira la page d'accueil de Spread Firefox en un microrésumé.
Spécifier à quelle page s'applique le générateur
Maintenant que nous avons la feuille de transformation, il nous faut spécifier à quelle page elle s'applique. Si nous étions les webmestres de Spread Firefox, nous pourrions simplement renseigner le générateur au sein de la page à l'aide d'une balise <link rel="microsummary"> dans son élément <head> :
<head> <link rel="microsummary" href="chemin/vers/notre/generateur.xml"> </head>
Comme ce n'est pas le cas, nous allons devoir spécifier à quelle page s'applique le générateur dans le code du générateur lui-même, et permettre ensuite de télécharger celui-ci. Pour spécifier les pages auxquelles un générateur s'applique, on utilise un élément <pages> au sein de l'élément <generator> :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <text>Fx : </text> <value-of select="id('download-count')"/> <text> téléchargements</text> </template> </transform> </template> <pages> </pages> </generator>
L'élément <pages> peut contenir une séquence d'éléments <include> et <exclude> spécifiant respectivement les pages auxquelles le générateur s'applique ou ne s'applique pas.
Pour que le générateur s'applique à une page, ajoutez un élément <include> dont le contenu est une expression rationelle s'appliquant à la page. Pour qu'il ne s'applique pas à une page, ajoutez un élément <exclude> à la place.
Par défaut, les générateurs ne s'appliquent à aucune page. Vous devrez donc explicitement lister les pages auxquelles ils s'appliquent sans avoir à exclure aucune page, à moins de les avoir inclues auparavant.
Ajoutez un élément <include> correspondant à la page d'accueil de Spread Firefox :
<?xml version="1.0" encoding="UTF-8"?> <generator xmlns="https://www.mozilla.org/microsummaries/0.1" name="Compteur de téléchargements de Firefox"> <template> <transform xmlns="https://www.w3.org/1999/XSL/Transform" version="1.0"> <output method="text"/> <template match="/"> <text>Fx : </text> <value-of select="id('download-count')"/> <text> téléchargements</text> </template> </transform> </template> <pages> <include>https://(www\.)?spreadfirefox\.com/(index\.php)?</include> </pages> </generator>
Si vous n'êtes pas expérimenté avec les expressions régulières, consultez Création d'expression régulières pour les générateurs de microrésumés, un tutoriel pour l'écriture de ceux-ci.
Rendre le générateur téléchargeable
Maintenant que le générateur s'applique à la page d'accueil de Spread Firefox, la seule chose qui reste à faire est de le rendre téléchargeable. Pour ce faire, il faut le placer quelque part en ligne et ensuite créer un lien JavaScript sur une page Web appelant la méthode window.sidebar.addMicrosummaryGenerator() de Firefox pour télécharger et installer le générateur.
Par exemple, si l'on place le fichier du générateur sur le Web à l'adresse https://people.mozilla.com/~myk/micro...-generator.xml, et que l'on veut permettre au visiteurs de l'installer depuis https://people.mozilla.com/~myk/micro...ial/index.html, on peut ajouter le code suivant à la page index.html :
<button onclick="window.sidebar.addMicrosummaryGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Installer le microrésumé pour la page d'accueil de Spread Firefox</button>
Un clic sur ce bouton génèrera cependant une erreur JavaScript sur les navigateurs ne gérant pas les microrésumés. Pour être plus sympathique avec ceux-ci, nous devrions vérifier si le visiteur utilise un navigateur gérant les microrésumés et afficher un message explicatif dans le cas contraire. Cela peut se faire avec le code suivant :
<script>
const warning = "Désolé, vous devez disposer d'un navigateur acceptant les microrésumés comme Firefox 2 pour installer et utiliser des générateurs de microrésumés.";
function addGenerator(url) {
if (typeof window.sidebar == "object" &&
typeof window.sidebar.addMicrosummaryGenerator == "function")
window.sidebar.addMicrosummaryGenerator(url);
else
alert(warning);
}
</script>
<button onclick="addGenerator('https://people.mozilla.com/~myk/microsummaries/tutorial/sfx-generator.xml')">Installer le microrésumé pour la page d'accueil de Spread Firefox</button>
Note: à cause du bug 341283, addMicrosummaryGenerator() n'accepte pas d'URL relative.
Conclusion
Vous devriez à présent disposer d'un générateur de microrésumé affichant le compteur de téléchargements de Firefox. Lorsqu'il est installé, Placez la page d'accueil de Spread Firefox dans vos marque-pages, et sélectionnez le microrésumé depuis le menu déroulant Nom de la fenêtre Ajouter un marque-page.
Pour plus d'informations sur les microrésumés, consultez Microsummaries home page sur le wiki de Mozilla.