Gestion des liens de navigation : les tags atm-linx

Les tags atm-linx permettent de créer des liens 'interne' au site. Ces liens permettent de générer les liens de navigation d'une page à une autre du site. Ils suivront le schéma d'arborescence des pages que vous définirez pour votre site.

Format des tags atm-linx :

Convention de notation : dans les codes source suivant, les codes entre crochets [ ] sont facultatif.

<atm-linx type="linxtype">
    <selection>...</selection>
    [<selection>...</selection>]
    <display>...</display>
    [<display>...</display>]
    [<noselection>...</noselection>]
</atm-linx>

Où la valeur linxtype de l'attribut type peut prendre une des valeurs suivantes :

• "direct" : lien direct vers une ou plusieurs pages.
   
• "sublinks" : lien vers les sous-pages d'une page.
   
• "desclinks" : liens "descendants" depuis la racine jusqu'à la page courante. Des paramètres permettront de régler la page de départ et d'arrivée.
   
• "recursivelinks" : liens "récursifs", permet d'afficher une arborescence complète de pages.

Le contenu d'un tag atm-linx est séparé en trois zones distinctes :

• Le ou les tags <selection> qui permettent de sélectionner les pages cibles des liens à créer.  
• Le ou les tags <display> qui permettent de spécifier comment afficher les pages sélectionnées.  
• Le tag facultatif <noselection> qui permet de spécifier un affichage dans le cas ou aucune page n'a été trouvé par le ou les tags <selection>

Les sous-liens et les liens descendants ne franchissent pas les frontières des sites. Par contre, les liens directs n'ont pas cette restriction.

1. Format des tags 'selection'.

Le tag selection déclare les pages cibles du lien. Il peut contenir une déclaration de condition, dans ce cas les pages cibles devront passer la condition avant d'être sélectionnées.

Voici le format des tags 'selection' :

<selection [noerror="1"] [crosswebsite="1"]>
    [<condition>...</condition>]
    <start>'nodespec declaration'[, 'nodespec declaration' ...]</start>
    [<start>'nodespec declaration'[, 'nodespec declaration' ...]</start>]
    [<stop>'nodespec declaration'</stop>]
</selection>

La sélection des pages cibles se fait en trois étapes :

• La ou les cible(s) de départ, représentée(s) par un tag start.
• La cible éventuelle de destination dans le cas de la description d'un chemin (lien de type "desclinks"), représentée par un tag stop.
• Un certain nombre de conditions (facultatif) représentées par le tag condition.

Les attributs facultatifs du tag selection sont :

• noerror : permet d'éliminer les messages d'erreur lors de la spécification d'une page inexistante. Accepte les valeurs 0, 1, true, false (défaut).
• crosswebsite : Par défaut un lien ne pourra cibler une page appartenant à un autre site web géré par Automne. Cet attribut permet de s'affranchir de cette limitation. Accepte les valeurs 0, 1, true, false (défaut).

Ce tableau décrit le nombre de tags start et stop possible en fonction du type de tag atm-linx :

2. Format de 'nodespec declaration'.

Les nodespec sont des spécifications de pages cibles. Ils peuvent faire référence à une page par sa référence ou par sa position par rapport à la page courante (la page où se trouve le lien) ou la racine.

Voici le format :

<nodespec type="NODESPECTYPE" value="NODESPECVALUE" [reloffset="OFFSET"] [website="CODENAME"] />

Voici un tableau récapitulatif des valeurs possibles des attributs :

ATTENTION : Par 'racine du site' on entend la racine du plus proche site parent créé   !

3. Format de 'noselection declaration'

noselection déclare un affichage alternatif dans le cas où le tag 'selection' ne cible aucune page. Il est optionnel.

Voici le format :

<noselection>Code XHTML valide</noselection>

4. Format de 'display declaration'.

Le display est la spécification du HTML qui remplacera le tag linx pour toutes les pages cibles définies dans la selection declaration. Un display peut contenir plusieurs conditions, et il peut y avoir plusieurs display dans le tag atm-linx. Dans ce cas, pour chaque cible, on examine les display dans leur ordre d'apparition dans le tag et si la cible passe toutes les conditions, c'est ce display qui est adopté. Si aucun display ne convient, la cible est rejetée. Si un display n'a pas de condition, on l'appelle le display par défaut. Il est inutile de mettre plusieurs display sans condition, ceux qui suivent le premier seront ignorés.

Voici le format :

<display>
    [<condition>...</condition>]
    <htmltemplate> Code XHTML valide </htmltemplate>
    [<subleveltemplate> Code XHTML valide </subleveltemplate>]
</display>

Tag <htmltemplate> : il comporte le code XHTML qui permettra de générer les liens pour les pages sélectionnées.

Dans ce tag <htmltemplate>, les valeurs spéciales suivantes peuvent apparaître :

• {{href}} : sera remplacé par l'URL absolue de la cible
• {{title}} : sera remplacé par le champ "titre du lien" de la cible
• {{jstitle}} : idem que le précédent, mais les simple et doubles quotes seront échappés afin de l'inclure dans du javascript ou des attributs de tags XHTML.
• {{pagetitle}} : Titre de la page
• {{jspagetitle}} : Titre de la page, mais les simple et doubles quotes seront échappés afin de l'inclure dans du javascript ou des attributs de tags XHTML.
• {{desc}} : Description de la page.
• {{id}} : Affiche l'identifiant unique de la page cible.
  
• {{codename}} : Nom de code (codename) de la page cible.
• {{currentClass}} : Affiche CMS_current si la cible courante est la même que la page en cours de navigation. Cette information peut-être utile pour un post traitement CSS ou javascript.
• id="{{currentID}}" : Affiche id="CMS_current" si la cible courante est la même que la page en cours de navigation. Cette information peut-être utile pour un post traitement CSS ou javascript.
  
• {{number}} : Uniquement pour les liens de type sublinks. Affiche le compte du nombre de lien. Cette information peut-être utile pour un post traitement CSS ou javascript.
• {{modulo}} : Uniquement pour les liens de type sublinks. Affiche alternativement 0 ou 1 pour chaque page. Cette information peut-être utile pour un post traitement CSS ou javascript.
• {{isParent}} : Affiche CMS_parent si la cible courante est un parent de la page en cours de navigation. Cette information peut-être utile pour un post traitement CSS ou javascript.
• {{websitetitle}} : Affiche le libellé du site dans lequel se trouve la page cible.
  
• {{websitecodename}} : Affiche le codename du site dans lequel se trouve la page cible.
• id="{{isParent}}" : Affiche id="CMS_parent" si la cible courante est un parent de la page en cours de navigation. Cette information peut-être utile pour un post traitement CSS ou javascript.
• class="{{isParent}}" : Uniquement pour les liens de type sublinks. Affiche class="CMS_parent" si la cible courante est un parent de la page en cours de navigation. Cette information peut-être utile pour un post traitement CSS ou javascript.

Le tag optionnel <subleveltemplate> permet de définir un encadrement optionnel du contenu du tag htmltemplate pour tous les types de liens. Il contient une zone de code XHTML dans laquelle doit être définie la valeur {{sublevel}} ou se positionnera le code produit par le tag <htmltemplate>.

Spécificité du tag recursivelinks :

La syntaxe du tag display du lien de type 'recursivelinks' possède quelques nuances par rapport aux autres tags :

<display [mode="MODE" root="ROOT"]>
    [<condition>...</condition>]
    <htmltemplate> Code XHTML valide </htmltemplate>
    <subleveltemplate> Code XHTML valide </subleveltemplate>
    [<mode>MODE</mode>]
    [<root>ROOT</root>]
</display>

En plus des valeurs spéciales des autres tags, le tag <htmltemplate> possède ces valeurs supplémentaires :

• "{{lvlClass}}" : Uniquement pour les liens de type recursivelinks. Affiche CMS_lvln. n étant le niveau courant de récursivité (nombre). Cette information peut-être utile pour un post traitement CSS ou javascript.
• "{{typeClass}}" : Uniquement pour les liens de type recursivelinks. Affiche CMS_sub si la cible courante possède des sous niveaux, CMS_nosub si la cible courante ne possède pas de sous niveaux ou CMS_open si la cible courante possède des sous niveaux et que ces niveaux sont affichés (uniquement en mode close). Cette information peut-être utile pour un post traitement CSS ou javascript.
• "{{sublevel}}" : Uniquement pour les liens de type recursivelinks. Positionnement de la zone récursive. C'est à cet endroit que sera affiché le niveau de récursivité (profondeur) supplémentaire si il existe.

Le tag optionnel <subleveltemplate> permet de définir un encadrement optionnel d'un niveau de récursivité. Il contient une zone de code XHTML dans laquelle doit être définie la valeur {{sublevel}} ou se positionnera le niveau suivant de récursivité (profondeur). Cette zone HTML peut aussi contenir la valeur {{lvlClass}} qui sera remplacé - de la même manière que dans le tag <htmltemplate> - par le niveau courant de recursivité.

Le tag optionnel <mode> permet de définir le mode d'affichage d'un tag recursivelinks. Il n'est utile que pour ce type de tag. <mode> prends deux valeurs : open ou close. Un tag ayant la valeur open affichera l'ensemble complet de l'arborescence. Un tag ayant le mode close n'affichera que la zone d'arborescence nécessaire à la localisation de la page courante.

A partir de la version 4.0.0rc2 : le tag <mode> peut être remplacé par un attribut mode sur le tag <display>. Cet attribut accepte lui aussi les valeurs open ou close.
Il est aussi possible d'ajouter un tag ou un attribut <root> permettant d'afficher ou non le premier niveau de récursivité. Ce tag (ou cet attribut) prennent les valeurs 0 ou 1 pour activer ou non l'affichage du premier niveau de récursivité.

4. Format de 'condition declaration'.

La condition permet de définir une règle que doit vérifier une cible si elle veut passer la condition. Elle contient un tag value qui déterminera la valeur qui servira de comparaison avec l'autre valeur de la condition qui est la plupart du temps une propriété de la cible testée.

Voici le format :

Où, de façon simplifiée :

• PROPERTY : peut contenir les valeurs suivantes : rank, title, id, lvl, father, website, codename
  
• OPERATOR : peut contenir les valeurs suivantes : ==, !=, >, <, >=, <=, %2==

IMPORTANT : Ces caractères doivent si besoin être encodés en HTML pour éviter tout problème de parsing (le caractère < devient &lt; et le caractère > devient &gt; ).

• VALUETYPE : peut contenir les valeurs suivantes : data, nodeproperty
• VALUEPROPERTY : peut contenir les valeurs suivantes : rank, title, id
• VALUEDATA : peut contenir le type de valeurs suivantes : valeur scalaire ou tag nodespec

Où, de façon détaillée :

• PROPERTY est une propriété de la cible qui servira pour le test, ou "rank", le rang de la cible (numéro d'ordre) dans le tableau des cibles. Les propriétés admises sont restreintes : title ou id pour le titre ou la référence de la cible, "rank" pour son rang (position par rapport aux pages frères et soeurs), "lvl" pour son niveau de récursivité (profondeur) pour les tags recursivelinks uniquement.
• OPERATOR est un opérateur de comparaison simple : ("==", ">=", ...) ou composé : "%2==". Il n'y a pas de limite aux opérateurs composés, si ce n'est qu'ils doivent être binaires.
• VALUETYPE défini le type de valeur qui servira à la comparaison. Elle peut avoir pour valeur data ou nodeproperty, le premier déterminera que la valeur entre le tag de début et de fin du tag value est une valeur scalaire à prendre telle quelle ; le second déterminera que c'est une valeur à tirer d'une nodespec.
• VALUEPROPERTY est optionnel, définit la propriété que l'on doit extraire du nodespec qui va suivre afin de servir de valeur.
• VALUEDATA définit la valeur (cas où VALUETYPE="data") ou le nodespec dont on va extraire la propriété afin de définir une des deux valeurs de la comparaison.

5. Quelques exemples de liens créées à l'aide des tags atm-linx :

Lien direct :

<atm-linx type="direct">
    <selection>
        <start><nodespec type="codename" value="home" /></start>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>

Pour cet exemple on peut aussi utiliser la syntaxe courte : 

<atm-linx type="direct" codename="home"><a href="{{href}}">{{title}}</a></atm-linx>

C'est le plus simple, ce tag sera remplacé par un lien vers la page portant le nom de code "home" (si elle existe) ce qui créera le code XHTML suivant :

<a href="url_home">Titre page</a>

Liens vers les sous-pages :

<atm-linx type="sublinks">
    <selection>
        <start><nodespec type="relative" value="self" /></start>
    </selection>
    <display>
        <htmltemplate><li><a href="{{href}}">{{title}}</a></li></htmltemplate>
        <subleveltemplate><ul>{{sublevel}}</ul></subleveltemplate>
    </display>
</atm-linx>

Là aussi ce tag est très simple, il sera remplacé par lune liste de liens vers toutes les sous pages (si il y en a) de la page en cours

ce qui créera le code XHTML suivant :

<ul>
    <li><a href="url_fils1">Titre fils1</a></li>
    <li><a href="url_fils2">Titre fils2</a></li>
</ul>

Liens descendants (simple) :

<atm-linx type="desclinks">
    <selection>
        <start><nodespec type="relative" value="root" /></start>
        <stop><nodespec type="relative" value="self" /></stop>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>
Voici un exemple simple de lien desclinks. Il permet de créer une liste des liens allant de la page d'accueil (root) jusqu'à la page en cours ce qui créera le code XHTML suivant :

<a href="url_accueil">Titre page Accueil</a><a href="url_page_sous_accueil">Titre page sous Accueil</a><a href="url_actuelle">Titre page actuelle</a>

Lien descendants (complexe) :

<atm-linx type="desclinks">
    <selection>
        <start><nodespec type="relative" value="root" /></start>
        <stop><nodespec type="relative" value="self" /></stop>
    </selection>
    <display>
        <condition property="id" operator="!=">
            <value type="nodeproperty" property="id"><nodespec type="relative" value="self" /></value>
        </condition>
        <htmltemplate><a href="{{href}}" title="{{jstitle}}">{{title}}</a> &gt;</htmltemplate>
    </display>
    <display>
        <condition property="id" operator="==">
            <value type="nodeproperty" property="id"><nodespec type="relative" value="self" /></value>
        </condition>
        <htmltemplate>{{title}}</htmltemplate>
    </display>
</atm-linx>

Cet exemple est un peu plus complexe car il fait appel aux conditions. Il permet de ne pas faire de lien vers la page actuelle (inutile car c'est la page sur laquelle nous sommes). Il ajoutera aussi des chevrons entre chaque lien de manière à séparer proprement le chemin de navigation. Cela génèrera le code XHTML suivant :

<a href="url_accueil">Titre page Accueil</a> &gt;<a href="url_page_sous_accueil">Titre page sous Accueil</a> &gt;Titre page actuelle

Lien recursivelinks "ouvert" :

<atm-linx type="recursivelinks">
    <selection>
        <start><nodespec type="relative" value="root" /></start>
        <condition property="lvl" operator="&lt;=">
            <value type="data">3</value>
        </condition>
    </selection>
    <display>
        <mode>open</mode>
        <htmltemplate><li class="{{lvlClass}} {{typeClass}} {{currentClass}}"><a class="{{lvlClass}}" href="{{href}}">{{title}}</a>{{sublevel}}</li></htmltemplate>
        <subleveltemplate><ul class="{{lvlClass}}">{{sublevel}}</ul></subleveltemplate>
    </display>
</atm-linx>

Ce lien permettra de générer une liste à puce imbriquées décrivant toute l'arborescence sous la page d'accueil (root) jusqu'au troisième niveau de profondeur au maximum.
Cela génèrera le code XHTML suivant :

<ul class="CMS_lvl1">
    <li class="CMS_lvl1 CMS_sub ">
        <a class="CMS_lvl1" href="url_accueil">Titre page Accueil</a>
        <ul class="CMS_lvl2">
            <li class="CMS_lvl2 CMS_nosub ">
                <a class="CMS_lvl2" href="url_sous_page1">Titre sous page 1</a>
            </li>
            <li class="CMS_lvl2 CMS_sub ">
                <a class="CMS_lvl2" href="url_sous_page2">Titre sous page 2</a>
                <ul class="CMS_lvl3">
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-1">Titre sous page 2 - 1</a></li>
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-2">Titre sous page 2 - 2</a></li>
                    <li class="CMS_lvl3 CMS_nosub CMS_current"><a class="CMS_lvl3" href="url_page_actuelle">Titre page actuelle</a></li>
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-4">Titre sous page 2 - 4</a></li>
                </ul>
            </li>
            <li class="CMS_lvl2 CMS_sub ">
                <a class="CMS_lvl2" href="url_sous_page3">Titre sous page 3</a>
                <ul class="CMS_lvl3">
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page3-1">Titre sous page 3 - 1</a></li>
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page3-2">Titre sous page 3 - 2</a></li>
                </ul>
            </li>
        </ul>
    </li>
</ul>

Vous noterez la présence de classes permettant de savoir quelle est la page en cours, (CMS_current) quels sont les différents niveaux (CMS_lvln) et si chacune des page possède des sous pages (CMS_sub ou CMS_nosub). Toutes ces classes permettant d'ajouter des feuilles de styles ainsi que des scripts javascript adéquat.

Lien recursivelinks "fermé" :

<atm-linx type="recursivelinks">
    <selection>
        <start><nodespec type="relative" value="root" /></start>
        <condition property="lvl" operator="&lt;=">
            <value type="data">3</value>
        </condition>
    </selection>
    <display>
        <mode>close</mode>
        <htmltemplate><li class="{{lvlClass}} {{typeClass}} {{currentClass}}"><a class="{{lvlClass}}" href="{{href}}">{{title}}</a>{{sublevel}}</li></htmltemplate>
        <subleveltemplate><ul class="{{lvlClass}}">{{sublevel}}</ul></subleveltemplate>
    </display>
</atm-linx>

La seule différence par rapport à l'exemple précédent se trouve dans la tag <mode> qui cette fois spécifie que l'arborescence de liens doit être "fermée".

Cela génèrera le code XHTML suivant :

<ul class="CMS_lvl1">
    <li class="CMS_lvl1 CMS_sub ">
        <a class="CMS_lvl1" href="url_accueil">Titre page Accueil</a>
        <ul class="CMS_lvl2">
            <li class="CMS_lvl2 CMS_nosub "><a class="CMS_lvl2" href="url_sous_page1">Titre sous page 1</a></li>
            <li class="CMS_lvl2 CMS_sub ">
                <a class="CMS_lvl2" href="url_sous_page2">Titre sous page 2</a>
                <ul class="CMS_lvl3">
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-1">Titre sous page 2 - 1</a></li>
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-2">Titre sous page 2 - 2</a></li>
                    <li class="CMS_lvl3 CMS_nosub CMS_current"><a class="CMS_lvl3" href="url_page_actuelle">Titre page actuelle</a></li>
                    <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-4">Titre sous page 2 - 4</a></li>
                </ul>
            </li>
            <li class="CMS_lvl2 CMS_sub "><a class="CMS_lvl2" href="url_sous_page3">Titre sous page 3</a></li>
        </ul>
    </li>
</ul>

La seule différence se situe dans l'affichage des sous pages de la sous page 3 qui cette fois ne sont plus visibles car elles ne se trouvent pas dans l'arborescence directe de la page actuelle.

Lien direct multiple et conditionnel :

<atm-linx type="direct">
    <selection>
        <start><nodespec type="relative" value="self" /></start>
        <start><nodespec type="node" value="12" /></start>
        <start><nodespec type="node" value="15" /></start>
    </selection>
    <display>
        <condition property="title" operator=">=">
            <value type="data">C</value>
        </condition>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>

Ce code permettra de créer des liens vers les pages 12, 15 et la page en cours. Si elles ont un titre qui commence par la lettre C ou 'plus' sur l'échelle ASCII.

Liens vers de multiples sites :

Faire un lien vers la même page sur un autre site spécifié par son codename :

<atm-linx type="direct">
    <selection>
        <start><nodespec type="relative" value="self" website="en" /></start>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>
Faire un lien vers la même page sur un autre site (site FR si EN actuellement et inversement) :

<atm-linx type="direct">
    <selection crosswebsite="1">
        <start><nodespec type="relative" value="self" website="fr" /></start>
        <start><nodespec type="relative" value="self" website="en" /></start>
        <condition property="website" operator="!=">
            <value type="nodeproperty" property="website"><nodespec type="relative" value="self" /></value>
        </condition>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>
Titre du site actuel :

<atm-linx type="direct">
    <selection>
        <start><nodespec type="relative" value="self" /></start>
    </selection>
    <display>
        <htmltemplate>{{websitetitle}}</htmltemplate>
    </display>
</atm-linx>
ou bien plus simplement :

<atm-website name="title" />

Titre du site EN si on est en FR (et inversement) :

<atm-linx type="direct">
    <selection crosswebsite="1">
        <start><nodespec type="codename" value="home" website="fr" /></start>
        <start><nodespec type="codename" value="home" website="en" /></start>
        <condition property="website" operator="!=">
            <value type="nodeproperty" property="website"><nodespec type="relative" value="self" /></value>
        </condition>
    </selection>
    <display>
        <htmltemplate>{{websitetitle}}</htmltemplate>
    </display>
</atm-linx>

Faire un lien vers tous les accueils de tous les sites :

<atm-linx type="direct">
    <selection crosswebsite="1">
        <start><nodespec type="codename" value="home" /></start>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>
et les accueils de tous les sites sauf le site en cours :

<atm-linx type="direct">
    <selection crosswebsite="1">
        <start><nodespec type="codename" value="home" /></start>
        <condition property="website" operator="!=">
            <value type="nodeproperty" property="website"><nodespec type="relative" value="self" /></value>
        </condition>
    </selection>
    <display>
        <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate>
    </display>
</atm-linx>

Il y aurait plein d'autres exemples possibles à ajouter pour décrire les multiples possibilités offertes par le tag atm-linx. N'hésitez pas à consulter ceux existant dans la démo fournie avec Automne ou à poser vos questions sur le forum.