Arbre

Ce module Javascript permet d'animer et de condenser une liste hiérarchique de catégories ou une table des matières qui auraient été générés 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 comme c'est le cas ici pour la table des matières de cette documentation.

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.

Pour connaître la version disponible de ces scripts sur votre système, vous pouvez jeter un œil au répertoire où ceux-là sont normalement installés.

ls ~/.local/share/VenC/themes_assets/

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

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

Dans cet example, on supose 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'autre module 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çon de procéder :

  • Vous pouvez copier le module et sa dépendance dans le répertoire assets de votre thème depuis ~/.local/share/VenC/themes_assets. C'est cette méthode qui est recommandée.
  • 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

Dans la pratique, vous souhaitez appliquer le module arbre à des listes hiérarchiques générées par VenC ; soit avec le pattern GetChapters ou TreeForBlogCategories.

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

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

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 +.
  • Pour un élément repliable, par défaut le bouton est le caractère -.
  • Pour un élement qui n'est ni dépliable, ni repliable, par défaut le bouton est et n'est pas cliquable.

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

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

var VENC_TREE = {
    button_show: '+',
    button_hide: '-',
    button_disabled: '○'
}

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

<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-0.0.0.js"></script>
<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Tree-0.1.0.js"></script>
<script type="text/javascript">
    VENC_TREE.button_disabled = '';
</script>

L'exemple ci-dessus est extrait du code source du thème de cette documentation. La redéfinition des attributs de VENC_TREE doit se faire après avoir inclut dans votre page VenC-Tree-x.y.z.js et sa dépendance.