4.6.2.3 Arbre

Ce module JavaScript permet d'animer et de condenser une liste hiérarchique de catégories ou une table des matières générées avec un pattern VenC.

En effet, si la liste d'éléments contenue dans l'un de ces types d'objets est très longue, ce peut être visuellement rédhibitoire. Ce module permet donc de plier/déplier les sous-parties d'une liste.

Inclure le module arbre dans votre page

Pour pouvoir utiliser ce module, vous devez inclure dans le fichier header.html de votre thème deux scripts :

• VenC-Scripts-Bootstrap-x.y.z.js : ce script est obligatoire pour faire fonctionner n'importe quel module.
• VenC-Tree-x.y.z.js : il s'agit du script permettant d'animer un arbre d'éléments. Il doit être inclus après VenC-Scripts-Bootstrap.

Une bonne façon de faire est d'inclure ces deux scripts de la façon suivante :

<script type="text/javascript" src=".:GetRelativeRoot:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
.:IfCategories::
    <script type="text/javascript" src=".:GetRelativeRoot:.VenC-Tree-x.y.z.js"></script>
:.

Dans cet exemple, on suppose que l'on souhaite appliquer le module à une liste hiérarchique de catégories. On utilise donc le pattern IfCategories pour n'inclure le module que si c'est nécessaire. Si l'on avait souhaité utiliser le module pour rendre interactif une table des matières, on aurait utilisé le pattern IfChapters.

Précisons également que si vous n'avez pas prévu d'utiliser d'autres modules que VenC-Tree-x.y.z.js dans votre thème, vous pouvez passer la ligne d'inclusion de VenC-Bootstrap-x.y.z.js en paramètre de IfCategories ou IfChapters.

Inclure le module arbre dans votre thème

Il y a deux façons de procéder :

• Vous pouvez copier le module et sa dépendance dans le répertoire assets de votre thème depuis $(venc -pp)/themes_assets. C'est cette méthode qui est recommandée si vous souhaitez distribuer votre thème.
• Vous pouvez définir un fichier de configuration de thème dans lequel vous indiquez les noms de fichier des modules que vous souhaitez voir être exportés pendant la génération de votre blog.

Structure d'une liste hiérarchique

Vous pouvez appliquer le module arbre à des listes hiérarchiques, qui sont générées par VenC avec le pattern GetChapters ou avec le pattern TreeForBlogCategories.

Commençons par observer que l'utilisation de ces deux patterns présente des similarités :

<!-- TreeForBlogCategories (TreeForEntryCategories run similarly) -->
<div class="__VENC_TREE_ROOT__">
    .:GetBlogCategoriesTree::
        <ul class="__VENC_TREE_NODE__">
    ::
        <li><a href="{path}" title="{count} publications">{value}</a>
    ::
        {childs}</li>
    ::
        </ul>
    :.
</div>

<!-- GetChapters -->
<div class="__VENC_TREE_ROOT__">
    .:GetChapters::
        <ul class="chapter-level-{level} __VENC_TREE_NODE__">
    ::
        <li>{index}. <a href="{path}">{title}</a>
    ::
        </li>
    ::
        </ul>
    :.
</div>

Entre autres choses, dans l'un ou l'autre pattern :

• Le premier argument contient toujours le tag <ul> ouvrant le nœud courant.
• Le second argument contient toujours le tag <li> ouvrant de la branche courante.
• Le troisième argument contient toujours le tag </li> fermant de la branche courante.
• Le quatrième argument contient toujours le tag </ul> fermant le nœud courant.

En particulier, pour que le module arbre fonctionne sur les listes hiérarchiques ciblées :

• Le pattern générant la liste hiérarchique est toujours contenu dans un élément ayant la classe __VENC_TREE_ROOT__.
• L'élément <ul> a toujours au moins une classe __VENC_TREE_NODE__.

Personnaliser le module arbre

L'API définit une variable globale appelée VENC_TREE.

var VENC_TREE = {
    button_show: '+',
    button_hide: '-',
    button_disabled: '○',
    ul_style: function(ul) {}
}

Chaque élément d'une liste hiérarchique se voit assigner un petit bouton qu'il est possible de définir soi-même.

• Pour un élément dépliable, par défaut le bouton est le caractère + et est défini dans button_show.
• Pour un élément repliable, par défaut le bouton est le caractère - et est défini dans button_hide.
• Pour un élément qui n'est ni dépliable, ni repliable, par défaut le bouton est ○ et n'est pas cliquable. Ce bouton est défini dans button_disabled.

Vous n'êtes pas obligé de définir un caractère, ce peut être du texte, ou des éléments HTML.

Vous pouvez assigner la valeur que vous souhaitez à l'un de ses trois attributs de la façon suivante :

<script type="text/javascript">
    VENC_TREE.button_disabled = '';
</script>

Il est également possible de redéfinir complètement le style CSS des listes ayant la classe __VENC_TREE_NODE__ avec ul_style. Par exemple :

<script type="text/javascript">
    VENC_TREE.ul_style = function(ul) {
        ul.style.listStyleType = "none";
    }
</script>

La redéfinition des attributs de VENC_TREE doit se faire après avoir inclus dans votre page VenC-Tree-x.y.z.js.