4 Structure et configuration d'un projet

Dans cette partie, nous verrons comment sont organisés les fichiers d'un projet VenC, comment ceux-là sont structurés et comment configurer tout ça.

4.1 Arborescence

La racine du projet porte le nom du blog, par exemple, "MooFooBar". Lorsque vous créez un nouveau projet, VenC produit un certain nombre de répertoires listés ci-dessous.

4.2 Fichier de configuration principal

blog_configuration.yaml est un document YAML à la racine du projet définissant les propriétés du blog, comme son titre, le nom de son auteur, ainsi que des détails fonctionnels comme le nombre de publications par pages ou l'ordre d'affichage de celles-ci.

Immédiatement après avoir créé votre blog, il s'agira sans doute du premier fichier que vous éditerez. Après avoir rempli ces champs, dont l'usage est détaillé ci-dessous, vous n'aurez normalement plus besoin d'y revenir.

blog_name

Sans surprise, il s'agit du titre de votre blog. Ce champ est obligatoire.

disable_threads

Empêche VenC de générer les fils de publications spécifiés dans une liste. Les noms de fils peuvent appartenir à des catégories ou à des archives. Par exemple :

disable_threads:
  - Categorie naze
  - 24/01/1990

disable_archives

Empêche VenC de générer les fils de publications des archives. Ce champ est un booléen, fixé à False par défaut.

disable_chapters

Empêche VenC de générer les chapitres. Ce champ est un booléen, fixé à False par défaut.

disable_categories

Empêche VenC de générer les fils de publications des catégories. Ce champ est un booléen, fixé à False par défaut.

disable_single_entries

Empêche VenC de générer les publications individuelles. Ce champ est un booléen, fixé à False par défaut.

disable_main_thread

Empêche VenC de générer le fil principal de publication. Ce champ est un booléen, fixé à False par défaut.

disable_rss_feed

Empêche VenC de générer un flux RSS. Ce champ est un booléen, fixé à False par défaut.

disable_atom_feed

Empêche VenC de générer un flux Atom. Ce champ est un booléen, fixé à False par défaut.

text_editor

Par défaut VenC utilise la commande spécifiée dans la variable d'environnement EDITOR pour ouvrir et éditer une nouvelle publication.

Il est cependant possible de redéfinir ici l'éditeur de texte choisi pour éditer une nouvelle publication.

Cette variable est une liste dont le premier élément est le nom de la commande et le reste ses arguments.

Par exemple :

text_editor:
  - geany
  - -i

date_format

"%A %d. %B %Y" par défaut. Définis le format de date utilisé à l'intérieur du blog. Le format des dates est en fait le même que celui utilisé par Python. Pour en savoir plus sur ce format, rendez-vous ici. Ce champ est obligatoire.

author_name

Le nom de l'administrateur ou de l'auteur du blog.

blog_description

Un résumé de ce dont parle votre site.

blog_keywords

Une liste au format YAML des mots-clefs associés au site.

author_description

Un court texte à propos de l'auteur du blog.

license

La licence appliquée au contenu de votre site.

blog_url

L'URL du blog. Elle peut être laissée vide, selon le thème utilisé.

ftp_encoding

Par défaut l'encodage des sessions FTP est en latin-1 mais ça pourrait ne pas convenir à la configuration de votre serveur vous pouvez donc définir l'encodage qui va bien ici.

ftp_host

Il s'agit du nom d'hôte ou de l'adresse IP de votre serveur FTP.

ftp_port

Il s'agit du numéro de port à utiliser pour se connecter à votre serveur FTP. Si ce champ n'est pas défini, il est fixé à 21 par défaut.

ftp_sessions

Il s'agit d'un nombre entier spécifiant le nombre simultané de connexion FTP que VenC va utiliser pour transférer votre site. Par défaut, ce nombre est fixé à 4.

blog_language

Définit la langue du site.

author_email

Votre adresse e-mail.

code_highlight_css_override

Génère à nouveau le code CSS créé par le module Pygments. Ce champ est un booléen, fixé à False par défaut.

Attention : si ce champ est fixé à True, à chaque exportation de votre blog, les anciens codes CSS créés par Pygments seront écrasés.

paths

Ce champ et ce qu'il contient sont obligatoires. Il s'agit d'une variable de type dict contenant différents chemins.

La liste de ces chemins est détaillée ci-dessous.

ftp

Le chemin absolu du répertoire de destination sur votre serveur FTP.

entries_sub_folders

Le nom de sous-répertoire qui contiendra les publications individuelles.

categories_sub_folders

Le nom du sous-répertoire qui contiendra les catégories.

index_file_name

"index{page_number}.html" par défaut. Spécifie le nom de fichier des pages d'un fil de publication. Devrait toujours contenir la variable {page_number}.

category_directory_name

"{category}" par défaut. Définis le répertoire où sera exporté le fil de publication de la catégorie courante. Ce champ devrait donc toujours contenir la variable {category}.

chapter_directory_name

"{chapter_name}" par défaut. Définis les noms de répertoire où seront exportés les chapitres, s'il en existe. Ce champ devrait donc toujours contenir la variable {chapter_name}.

archives_directory_name

"%Y-%m" par défaut. Définit le format de date utilisé pour les noms de répertoires des archives. Le format des dates est en fait le même que celui utilisé par Python. Pour en savoir plus sur ce format, rendez-vous ici.

entry_file_name

"entry{entry_id}.html" par défaut. Définit le nom de fichier d'une publication unique.

rss_file_name

"rss.xml" par défaut. Définis le nom de fichier du flux RSS.

atom_file_name

"atom.xml" par défaut. Définis le nom de fichier du flux Atom.

themes_locations

Il s'agit d'une liste optionnelle contenant un ou plusieurs chemins vers des répertoires contenant des thèmes.

entries_per_pages

10 par défaut. Définis le nombre de publications par page. Ce champ est obligatoire.

columns

1 par défaut. Ce champ définit le nombre de colonnes dans une page.

feed_length

5 par défaut. Définis le nombre de publications à afficher dans le flux RSS. Ce champ est obligatoire.

reverse_thread_order

Ce champ est un booléen, fixé à True par défaut. Définit l'ordre de publication. Du plus récent au plus ancien (True), ou l'inverse (False). Ce champ est obligatoire.

markup_language

Ce champ spécifie le langage de balisage par défaut utilisé dans toutes les publications. Cette valeur peut cependant être localement écrasée dans l'entête d'une publication.

Les valeurs possibles de ce champ sont :

Ce champ est obligatoire.

server_port

Spécifie le port du serveur HTTP local. Ce champ est fixé à 8888 par défaut.

sort_by

Pour être ordonnées, les publications sont généralement évaluées selon la valeur de leur identifiant. C'est pourquoi la valeur de ce champ est id par défaut. Il est possible de spécifier le nom d'une autre propriété pour les publications.

Les valeurs possibles sont :

Vous pouvez également spécifier le nom d'une métadonnée définie manuellement dans l'entête de vos publications.

parallel_processing

Cette option permet de contrôler le nombre de processus enfants lors de la génération de votre site avec VenC. Le nombre idéal correspond à votre nombre de cœurs sur votre CPU. Pour les petits blogs, il n'est pas utile d'avoir plus d'un processus.

pipe_flow

Cette option permet de contrôler le volume d'octets transitant d'un sous-processus à un autre. Il permet une optimisation fine des fonctions de parallélisme de VenC. La valeur par défaut est normalement optimale et est fixée à 512. Vous pouvez néanmoins effectuer des tests pour voir ce qui est le plus rapide chez vous.

pygmentize_style

Il est possible de contrôler le style de coloration syntaxique proposé par Pygmentize en assignant un des noms de style documenté ici à cette option. Si vous changez le style et que code_highlight_css_override est configuré avec False, alors il faut supprimer les feuilles de styles déjà générées par VenC dans le répertoire extra.

default_theme

Contient le nom du thème par défaut à utiliser. Normalement, si vous n'avez pas installé de thème dans le dossier de votre projet, vous êtes obligé de spécifier le nom d'un thème installé avec VenC au moment de générer votre blog. Par exemple :

venc -xb concrete

Si aucun thème n'est installé dans votre projet et si aucun nom de thème n'est passé en paramètre à la commande venc -xb, alors VenC tentera d'utiliser l'option default_theme pour sélectionner un thème. Si vous n'avez pas de thème installé dans votre projet, il est important de définir cette variable pour que la commande venc -s fonctionne correctement.

4.3 Les publications

Une publication est un fichier dans lequel vous allez pouvoir rédiger votre contenu. Cela peut-être un billet d'humeur ou d'opinion, un article de fond, une galerie d'images, etc. Pour faciliter l'édition de votre blog avec VenC, vous êtes fortement encouragé à utiliser des templates.

Le nom de fichier d'une publication est formaté de la façon suivante :

<id>__<mois>-<jour>-<année>-<heure>-<minute>__<titre>

Une publication contient une première partie au format YAML contenant les métadonnées de la publication, puis une seconde au format Markdown (format par défaut) qui contiendra la publication à proprement parler. Cette seconde partie est elle-même scindée en deux. L'une contiendra la prévisualisation de la publication, et l'autre son véritable contenu. Vous pouvez évidemment contrôler l'affichage de la prévisualisation et de la publication en fonction de votre template/thème de blog.

Une publication vierge se présente de la façon suivante:

authors:
  - ''
categories:
  - ''
title:
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---

Entête de la publication

Il y a donc quatre champs qu'il est possible de compléter.

authors

C'est la liste des auteurs de la publication, séparés par une virgule. Par exemple : Denis Salem, Benjamin Bayard, Richard Stallman.

categories

C'est la liste des catégories de la publication au format YAML. Comme ces catégories peuvent contenir des sous-catégories, les listes peuvent être imbriquées. Par exemple :

categories:
  - Libre:
    - GNU/Linux:
      - Gentoo
    - LibreOffice
  - Open-source:
    - Android

title

C'est le nom de votre publication, tel que vous l'avez défini au moment de créer la publication avec la commande :

venc -ne "titre de la publication"

Métadonnées optionnelles

Il est également possible de rajouter librement des champs optionnels. Il y a cependant deux champs réservés :

chapter

Indique à quel chapitre correspond la publication. La convention qu'utilise VenC pour reconnaître les chapitres est la suivante : chaque chapitre et chaque sous-partie sont numérotés, et séparés par un point. Quelques exemples pour aider à visualiser le truc :

Important : le champ chapter doit explicitement être une chaîne de caractères. Pour ce faire, l'index du chapitre doit être entre guillemets.

markup_language

Il est possible de spécifier un langage de balisage qui sera utilisé pour la publication courante, en lieu et place du langage défini dans le fichier de configuration du blog.

VenC supporte trois langages de balisage :

4.4 Métadonnées

Il est possible d'ajouter aux publications et au fichier de configuration principal des métadonnées supplémentaires.

Type de métadonnées

Il y a trois types possibles de métadonnées pour VenC.

Chaîne de caractères

C'est le type par défaut de la plupart des métadonnées. Par exemple :

free_artist: 'Revolution Void'

Liste de chaînes de caractères

C'est par exemple le type par défaut des champs tags et authors dans une publication. Il s'agit d'une liste d'éléments formatés selon la convention de YAML. Par exemple :

liste_de_chose_à_faire:
  - 'Devenir un dieu du code'
  - 'Niquer le capitalisme'
  - 'Manger les riches bourgeois'

Dictionnaire de données

Il se présente comme spécifié par le format YAML. Le champ categories en est un exemple :

categories:
  - Libre:
    - GNU/Linux:
      - Gentoo
    - LibreOffice
  - Open-source:
    - Android

4.5 Les templates de publication

Un template est en fait une publication vierge qui a cependant été préformatée pour contenir des choses redondantes à rédiger ou à programmer manuellement. Typiquement, pour une galerie, vous pourriez vouloir un template qui contiendrait déjà la ou les balises Markdown pour inclure une ou plusieurs images, les champs categories et tags préremplis, etc.

Par exemple :

authors: 'Denis Salem'
categories: 
  - Photographies:
     - Nature
title: Champignons trop mignons (mais pas commestibles, alors calme-toi)
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---
![.:GetEntryTitle:.](".:GetEntryTitle:.")

VenC est livré avec des exemples de templates. En voici la liste :

Parmi ces templates, certains servent surtout à illustrer l'usage de certaines fonctionnalités de VenC.

Ces templates sont normalement installés dans : $(venc -pp)/themes_templates.

Pour utiliser un template, il suffit de passer son nom de fichier (sans le chemin) à VenC au moment de la création d'une nouvelle publication. Par exemple :

jeanrochefort@anonymous ~ $ venc -ne "Amanite tue-mouches" champignons_magiques

VenC va d'abord essayer de trouver votre template dans le répertoire templates de votre blog. Sinon, il essayera de le trouver parmi les templates de publication prédéfinis, qui sont listés plus haut.

4.5.1 Arguments d'un template

Les templates supportent la paramétrisation au moment de l'exécution de la commande --new-entry. C'est le cas par exemple du template oEmbed ou images. Quand un template est appelé sans ses arguments, la création de la publication échoue.

Avant d'utiliser un template, il faut donc connaître ses arguments à l'aide de la commande --template-arguments.

Les paramètres de template prennent la forme de placeholder Python, ceux qui sont utilisés avec la fonction format. Par exemple :

{moo} {foo} {bar}

Pour fonctionner il faut passer à VenC un troisième argument, au format JSON, qui portera les clés-valeurs nécessaires au template.

4.5.1.1 Premier cas pratique : oEmbed

Le template oEmbed se présente ainsi :

authors:
categories:
title: {venc_entry_title}
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---
.:GetEmbedContent::{embed_content}:.

Dans ce template, on voit que l'on a deux placeholders :

Pour créer une publication avec le template oEmbed il faudrait donc utiliser la commande VenC --new-entry, comme ci-dessous :

venc --new-entry \
  "Des images stylées, comme l'histoire de France" \
  oEmbed \
  '{"embed_content":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

4.5.1.2 Second cas pratique : images

Le template images se présente ainsi :

authors:
categories:
title: {venc_entry_title}
images: {images}
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---
.:ForEntryMetadata::images::<img src="{value}" title="" alt="{value}">:: :.

Dans ce template on voit que l'on a trois placeholders :

Comme la métadonnée d'origine dans l'entête YAML du template est appelée dans ForEntryMetadata, il faut que la variable images soit une liste. On doit donc utiliser la commande VenC --new-entry comme ci-dessous :

Pour plus de clarté l'exemple utilise une approche multiligne en Bash, comme expliqué ici.

JSON=$(cat <<-END
{
    "images" : [
        "https://i.kym-cdn.com/photos/images/newsfeed/000/247/207/813.gif",
        "https://i.kym-cdn.com/photos/images/newsfeed/001/390/627/208.jpg"
    ]
}
END
)
venc --new-entry \
"Des images stylées, comme l'histoire de France" \
images \
"$JSON"

4.5.2 Arguments par défaut

4.6 Thèmes

Un thème est l'ensemble des fragments qui seront assemblés et interprétés par VenC pour former votre blog, c'est dans un thème que sera définie la mise en page de votre site. Typiquement, un thème est un répertoire contenant au moins le dossier chunks et un autre, optionnel, assets.

Comme vous l'avez sans doute compris, VenC met bout à bout les morceaux de votre blog en formatant l'entête (header.html), puis en répétant autant de fois qu'il y a de publications sur une page le formatage du corps de la publication (entry.html). La page courante est alors terminée en y ajoutant le pied de page (footer.html), également formaté.

C'est exactement le même principe pour le flux RSS, qui est construit de façon identique.

Il n'est pas forcément évident de créer un thème de toutes pièces et vous n'avez peut-être pas envie de perdre trop de temps à tester le fonctionnement de tout ça. Le meilleur moyen de créer un thème soi-même est de jeter un œil au thème concrete normalement installé avec VenC dans : $(venc -pp)/themes/concrete.

Ce thème en l'état offre un aperçu de ce qu'il est possible de faire avec VenC. C'est une solide base pour créer le vôtre.

Vous pouvez également vous aider des "tutoriels", dans laquelle sont décrites des techniques pour réaliser des mises en pages très spécifiques et pour lesquelles l'utilisation du langage de balisage interne de VenC sera illustrée.

4.6.1 Configuration d'un thème

Lorsque vous créez votre thème, et si vous souhaitez le distribuer, il est possible et même recommandé de configurer le fichier config.yaml dans le répertoire racine de votre thème.

Comme le nom de fichier le laisse penser, il s'agit d'un fichier de configuration au format YAML. Celui-ci est structuré de la façon suivante :

info:
    description : ''
override:
    whatever_field_1: 'whatever_value'
    whatever_field_2: 'whatever_value2'
    ...
assets_dependencies: ['awesome.css','not_so_shitty_script.js',]

4.6.2 Modules JavaScript

VenC fournit quelques modules JavaScript pour vous aider à mettre en page votre contenu. Ces scripts sont installés dans le dossier : $(venc -pp)/themes_assets

Ce chapitre présente ces modules et en explique le fonctionnement.

4.6.2.1 Chargeur de scripts JS

Avant tout chose, il convient de prendre connaissance du chargeur de scripts.

Dans le cas où vous souhaiteriez écrire votre script pour un thème de votre confection, il est fortement recommandé de l'exécuter à l'aide de VenC-Scripts-Bootstrap-x.y.z.js (x.y.z étant la version disponible avec la distribution de VenC que vous possédez).

Ce script déclenche l'effet des modules JS quand la page est chargée.

var VENC_ON_LOAD_CALLBACK_REGISTER = [];

function VENC_ON_LOAD_CALLBACK() {
    var i;
    for (i = 0; i < VENC_ON_LOAD_CALLBACK_REGISTER.length; i++) {
        VENC_ON_LOAD_CALLBACK_REGISTER[i]();
    }
}

window.onload = VENC_ON_LOAD_CALLBACK

Pour fonctionner, VenC-Scripts-Bootstrap-x.y.z.js doit être le premier script appelé dans votre page.

<script type="text/javascript" src=".:GetRelativeRoot:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
<script type="text/javascript" src=".:GetRelativeRoot:.Mon-Module-Trop-Badass.js"></script>

Ce module définit la variable VENC_ON_LOAD_CALLBACK_REGISTER accessible depuis les autres scripts que vous importez dans votre page. Il s'agit d'une liste de callbacks s'exécutant quand window.onload est appelé.

Typiquement, à la fin de votre script, pour que son effet se déclenche, ajoutez votre callback comme ci-dessous :

VENC_ON_LOAD_CALLBACK_REGISTER.push(LE_CALLBACK_DE_MON_SUPER_MODULE_JS);

4.6.2.2 Défilement infini

Ce module Javascript permet de charger automatiquement les pages du blog quand vous arrivez à la fin de la page courante.

Inclure le défilement infini dans votre page

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

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>

.:IfInfiniteScrollEnabled::
    .:IfInThread::
        <script type="text/javascript" src=".:GetRelativeRoot:.VenC-Infinite-Scroll-x.y.z.js"></script>
    ::

    :.
:.

Inclure le défilement infini dans votre thème

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

Structure d'une page

Pour que le défilement infini fonctionne, votre thème doit être structuré d'une certaine manière, que nous allons détailler ici.

Les exemples ci-dessous constituent un code minimal pour faire fonctionner le défilement infini.

header.html

Comme nous l'avons vu, il faut que les scripts soient inclus dans le fichier header.html. Idéalement de la façon suivante :

<!DOCTYPE html>
<html>
    <head>
        <script type="text/javascript" src=".:GetRelativeRoot:.VenC-Scripts-Bootstrap-x.y.z.js">
        </script>
        .:IfInfiniteScrollEnabled::
            .:IfInThread::
                <script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Infinite-Scroll-x.y.z.js">
                </script>
            ::
        
            :.
        :.
    </head>

entry.html

Chaque bloc contenant une publication doit être de la classe "entry". Sinon, le script de défilement infini n'est pas capable de reconnaître les publications qu'il doit charger.

            <div class="entry">
                <!-- Contenu de la publication -->
            </div>

Ici il y a trois éléments à considérer qui devrait se trouver dans footer.html mais qui, si votre choix de mise en page l'impose, pourrait se trouver dans header.html. Chaque élément ne devrait être présent qu'une et une seule fois dans la page.

        .:GetBlogMetadataIfExists::
            loading_image
        ::
            <img id="__VENC_LOADING__" src=".:GetRelativeOrigin:.{value}" />
        :.
        <footer>
            <div id="__VENC_NAVIGATION__">
                <!-- Insérer ici des patterns VenC permettant de générer les liens de navigation -->
                .:GetNextPage::
                    <a id="next" href="{path}" data-venc-api-infinite-scroll-hook="{path}">→</a>
                :.
            </div>
        </footer>
    </body>
</html>

Personnaliser le défilement infini

VenC fourni une API pour personnaliser le défilement infini. Pour cela, vous pouvez modifier les attributs de la variable globale VENC_INFINITE_SCROLL.

hideVenCNavigation

hideVenCNavigation: true

Normalement, les liens de navigation (numéro de page, page suivante/précédente) contenus dans l'élément ayant l'id __VENC_NAVIGATION__ sont désactivés pour le défilement infini. Mais il est possible de ne pas le faire et laisser ces éléments visibles en changeant la valeur de cette variable.

interval

interval: 250

Cette variable définit le temps, en millisecondes, entre chaque test visant à savoir si la fin de la page a été atteinte et donc s'il faut charger la suite. La valeur par défaut est 250 millisecondes.

imageDefaultSetup

imageDefaultSetup: function(img) {}

Cette méthode ne fait rien par défaut, mais si vous le souhaitez vous pouvez y configurer l'était initial des images dans une publication au moment où celle-ci est chargée dans le DOM.

entryDefaultSetup

entryDefaultSetup: function(entry) {
    entry.style.opacity = "0.0";
}

Cette méthode permet d'initialiser l'état d'une publication au moment où elle est chargée dans le DOM. Par défaut, les publications sont invisibilisées.

onLoadImage

onLoadImage : function(img) {}

Par défaut, cette fonction ne fait rien de particulier, mais permet si vous le souhaitez de configurer l'état ou l'animation d'apparition d'une image au moment où son téléchargement est terminé.

onLoadEntry

onLoadEntry : function(entry){
    entry.style.transition = "opacity 0.5s ease";
    entry.style.opacity = "1.0";
}

Par défaut quand une publication est chargée, elle apparaît avec une petite animation de transparence. Vous pouvez redéfinir la fonction pour créer l'animation que vous souhaitez.

dontWait

dontWait: false

Par défaut, VenC attend que la page en cours de chargement soit entièrement téléchargée avant de récupérer la suivante. Il est possible en changeant la valeur de cette variable à True, de charger plusieurs pages en même temps, ce n'est cependant pas recommandé.

loading

Quand le chargement d'une page est en cours, le script rend par défaut visible l'icône de chargement de la page, si l'élément HTML ayant pour id __VENC_LOADING__ existe. Cet élément est passé en argument à la fonction suivante, qu'il est possible de redéfinir :

loading : function(loading_image) {
    loading_image.style.opacity = "1.0";
}

idle

Quand le chargement est inactif, le script rend par défaut invisible l'icône de chargement de la page, si l'élément HTML ayant pour id __VENC_LOADING__ existe. Cet élément est passé en argument à la fonction suivante, qu'il est possible de redéfinir :

idle : function(loading_image) {
    loading_image.style.opacity = "0.0";
}

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 :

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 :

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 :

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

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.

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.

4.6.3 Thème par défaut

Usage

Pour vous faciliter la vie, VenC est livré avec au moins un thème qui peut vous servir de base pour créer le vôtre. C'est également idéal pour voir comment sont mis en pratique certains concepts de VenC. Quand vous installez VenC, ce thème est placé dans : $(venc -pp)/themes/concrete

Ce thème s'appelle concrete. Vous pouvez donc l'utiliser en générant votre site avec :

venc -xb concrete

Ou en l'installant localement dans votre projet avec la commande suivante :

venc -it concrete

L'avantage de cette dernière méthode étant qu'elle vous permet de modifier le thème en profondeur.

Configuration

Ce thème peut être adapté à vos besoins sans le modifier directement à l'aide d'une série de variables à définir dans votre fichier de configuration principal :

Affichage et contrôle des catégories

Les catégories sont gérées avec GetBlogCategoriesTreeFromBranches et GetFlattenedBlogCategoriesFromBranches, en conséquence le thème utilise une métadonnée obligatoire nommée taxonomy contenant une liste de sous-catégories à afficher.

Autres options