Références relatives

GlossPatch

Dans l'exercice précédent, nous avons pris soin que le mécanisme du glossPatch soit bien opérationnel, ce que nous avons fait avec la directive #useGlossPatcher.

Le mécanisme du glossPatch est un outil ingénieux pour établir des liens relatifs entre les pages de votre site. C'est commode parce que les références relatives sont efficaces, et le restent lorsque vous décidez de changer l'URL de votre site. Et c'est très utile, parce que cela vous permet de laisser Frontier maintenir vos références relatives à votre place.

Il y a plusieurs parties dans le mécanisme du glossPatch.

Premièrement, allez dans la sous-table glossary. Notez que certaines entrées sont des tables ne contenant que deux éléments. Elles sont générées automatiquement à chaque fois que vous rendez une page.

En fait, votre glossary doit être dans un tel désordre qu'il ne doit plus du tout refléter l'état actuel de votre site. Il vous revient de le purger de temps à autre, alors commençons à nous exercer.

S'occuper de son glossaire

En faisant attention, sélectionnez et supprimez toutes les entrées du glossary qui sont des tables. Je dis de faire attention parce que vous ne voudriez pas supprimer des entrées du glossaire que vous avez mis là vous-même, comme ourLogo.

À présent publiez le site complet (en étant vigilant de ne pas le faire à partir de la table glossary !). Maintenant, regardez de nouveau dans glossary. Vous devriez voir que seules deux entrées sont des tables, une pour la secondePage, et une pour la quatrièmePage.

Bien que publier l'ensemble d'un site reconstruise son glossaire, il y a un autre moyen, plus simple. Sélectionnez votre table #glossary et choisissez Build Glossary dans le menu Web. Frontier va alors mettre à jour vos entrées de glossaire relatives -- c'est le type de celles dont nous sommes en train de parler.

Ces entrées sont générées automatiquement, pour chaque page, par le pageFilter. Si vous alliez dans le pageFilter, sélectionniez la ligne :

   html.addPageToGlossary (adrPageData)

et choisissiez dans le menu script Toggle Comment pour commenter cette ligne, la génération de entrées #glossPatch cesserait.

La raison d'être de cette génération automatique des entrées #glossPatch est de vous permettre de créer les liens relatifs. Une fois que l'entrée #glossPatch existe, si vous désirez insérer dans secondePage un lien pointant sur quatrièmePage, vous pouvez aisément écrire la chose suivante:

   Si vous voulez voir un tableau, regardez ma "quatrièmePage".

Que se passe t-il quand vous écrivez cela ? Frontier va convertir "quatrièmePage" en une entrée de #glossPatch au look élaboré -- que vous ne verrez sans doute jamais. Il ne s'agit que d'une version en language machine de l'entrée de glossaire relative, traduite au bénéfice de Frontier.

Puis, à la toute fin du processus de rendu, l'expression du #glossPatch de votre page est remplacée par un chouette lien relatif en HTML -- si #useGlossPatcher est true. Si vous faites référence à l'une de ces entrées dans une page Web et que #useGlossPatcher est réglé à false, l'expression du #glosspatch ne sera pas modifiée et sera visible dans votre page Web comme le nez au milieu de la figure !

Anatomie d'une référence du glossPatch

Voyons comment l'interpréteur du glossPatch fait son travail. Cela nécessite que nous comprenions l'anatomie d'une expression #glossPatch qui n'est pas, somme toute, si compliquée. Considérez, par exemple l'expression générée automatiquement pour quatrièmePage.

Dans le glossaire, quatrièmePage est une table contenant deux éléments : linetext et path. Linetext est le titre, et le path (chemin d'accès) est relatif à la racine du site (et inclut l'extension du fichier).

Lorsque cette entrée de glossaire est traitée, Frontier la traduit en :

    [[#glossPatch Ma quatrième page|quatrièmePage.html|]]

Souvenez-vous que vous ne verrez probablement jamais l'expression ci-dessus lorsque vous travaillez sur vos sites Web ; mais ça ne peut pas faire de mal de savoir ce qui se passe en coulisses.

Les "[[" et "]]" sont juste des balises et le "#glossPatch" dit simplement que ceci est une expression #glossPatch.

Le reste, c'est deux expressions séparées par ces petites lignes verticales, j'ai nommé "Ma quatrième page" et "quatrièmePage.html".

La première, "Ma quatrième page" est le texte qui apparaîtra en tant que lien dans le fureteur.

La seconde, "quatrièmePage.html" indique sur quoi pointer. Puisque le mot "quatrièmePage.html" est seul dans sa section de l'expression, cela signifie que quatrièmePage est au niveau supérieur de votre site, dans le dossier principal.

D'un autre côté, si quatrièmePage.html était destinée à apparaître dans un sous-dossier appelé "sub", la génération automatique de l'expression glossPatch aurait l'air de ceci :

    [[#glossPatch Ma quatrième page|sub/quatrièmePage|]]

Pourquoi ces éléments du glossary sont t'ils générés automatiquement ? Pour vous permettre de réarranger votre site et de conserver des références qui continueront de pointer sur les bonnes pages ! Supposons que vous déplaciez votre quatrièmePage à l'intérieur d'une sous-table. Si l'expression du glossary était codée avec une référence absolue comme dans cet exemple :

    <a href="quatrièmePage.html">Ma quatrième page</a>

lors du prochain rendu de votre site, le lien généré par "Ma quatrième page" serait rompu.

Avec le mécanisme du glossPatch, cela ne risque pas d'arriver. Le pageFilter construit un nouvel ensemble d'expressions du glossary de telle sorte que ma "Ma quatrième page" sera correctement reliée sans que vous n'ayez à changer quoi que se soit dans vos pages (vous aurez par contre peut être besoin de publier deux fois le site pour que tout soit correctement remis en place).

Personnaliser vos références du glossPatch

Quand vous insérez dans secondePage la ligne suivante :

    Si vous voulez voir un tableau, allez à "Ma quatrième page".

lorsque vous publierez le site, secondePage.html contiendra la phrase :

   Si vous voulez voir un tableau, allez à Ma quatrième page.

où ces trois derniers mots, "Ma quatrième page" constitueront le lien vers quatrièmePage.html. C'est très bien, mais vous préfèreriez peut être dire, par exemple :

    Si vous voulez voir un tableau, 
    J'ai une page super qui en contient un.

où les mots "page super" devraient être un lien vers quatrièmePage. De toute évidence, ce que vous désirez à la fin du processus de rendu, quand les appels au glossPatch seront interprétés, c'est ceci :

    [[#glossPatch une page super|quatrièmePage.html|]]

Mais comment l'obtenir ? Une solution serait d'écrire simplement cette expression vous-même dans la page, sachant qu'à la fin du processus de rendu, elle se sera changée en un joli lien intitulé "super page", pointant sur quatrièmePage.html. En effet, rien ne vous empêche d'écrire vos propres appels au glossPatch.

Mais ce n'est pas la solution qu'idéalement vous aimeriez avoir. L'expression implique que quatrièmePage.html est au niveau supérieur de votre site. Cela contredit toute l'idée du mécanisme du glossPatch, qui est de vous permettre de réorganiser vos pages sans rompre les références relatives.

Si vous créez maintenant une sous-table "sub" et mettez quatrièmePage dedans, cette référence devra se briser. Et pourtant, le mécanisme qui génère les entrées du glossaire du glossPatch aurait pu modifier cette entrée pour qu'elle continue de pointier correctement Ma quatrième page :

    [[#glossPatch Ma quatrième page|sub/quatrièmePage.html|]]

Quel gâchis ! La génération automatique des entrées du glossaire s'échine à suivre l'organisation de votre site, et vous ne tirez pas profit de cette automatisation, en codant avec des références absolues.

La solution bien sûr est est la macro glossSub dont nous avons déjà parlé (voir la page Glossaires), et qui fonctionne aussi pour les expressions du glossary !

Alors, tout ce que vous avez besoin de dire maintenant est ceci :

    Si vous voulez voir un tableau 
    J'ai une {glossSub("Ma quatrième page", "page super")} qui en contient un.

Derniers points

Nous avons déjà observé que pour n'importe quelle page, la génération automatique d'entrées glossPatch dans le glossaire utlise la valeur de #title de la page, tant pour le nom de l'entrée que pour le texte qui sera visible en tant que lien hypertexte.

D'un côté, cela vous permet de relocaliser où bon vous semble votre site. Vous pouvez aussi renommer les entrées qui contiennent les pages.

Mais si vous changez le #title d'une page, toutes les références à cette page via le mécanisme automatique du glossary ne seront plus valides. Vous devez donc choisir avec attention le titre de vos pages, parce que vous allez restez coincé avec ces derniers. C'est le prix à payer pour ne pas être enfermé dans la logique de localisation spécifique pour chaque page.

Note  : certains utilisateurs plus anciens de Frontier ont eu l'expérience d'URL mal construits par le mécanisme du glossPatch. Ces URL commençaient par "/../../../" ou quelque chose de similaire. Si cela vous arrive, c'est parce que vous utilisez une entrée "éloignée" #ftpSite, c'est-à-dire que l'entrée #ftpSite de votre site n'est pas une table telle qu'expliquée dans cette introduction mais le nom d'une entrée à user.html.sites.

Le mécanisme du glossPatch n'est pas compatible avec les #ftpSite éloignés, et puisqu'à présent les directives ne sont plus hiérarchiques, il n'y pas vraiment de raisons d'utiliser des entrées #ftpSite éloignées. Faites de votre entrée #ftpSite une table comparable à celle qui est générée par la commande New Site et tout ira bien.