3 Tutoriels

Ce chapitre vise à vous aider à prendre en main VenC. Pour une utilisation avancée de VenC, vous pouvez vous référer au chapitre 4 et au chapitre 5.

3.1 Créer son blog en moins de 5 minutes !

Eh ouais, c'est possible !

Dans un terminal, tapez la commande suivante :

venc --new-blog "MonSuperBlog"

Après cette commande, VenC a créé un répertoire appelé "MonSuperBlog" à l'endroit où vous avez lancé la commande. Ce répertoire contient toutes les informations de votre blog. Il faut donc le garder précieusement, et même en faire des sauvegardes de temps à autre, avec git par exemple !

jeanrochefort@anonymous ~ $ venc --new-blog "MonSuperBlog"
VenC: Votre blog a été créé!
jeanrochefort@anonymous ~ $ ls MonSuperBlog/
blog blog_configuration.yaml entries extra includes templates theme

La prochaine étape consiste à paramétrer un peu le blog. Pour ça, il suffit d'éditer le fichier blog_configuration.yaml à la racine de ce répertoire. Vous pourrez notamment y définir le nom de votre blog, sa langue, ses mots-clés, entre autres choses parmi les nombreux paramètres à configurer, ou à laisser par défaut.

author_description: 'Je suis Jean Rochefort et je suis mort, mais je reviendrai.'
author_name: 'Jean Fucking Rochefort'
blog_description: 'Les tribulations du roy de France Jean Rochefort en direct du paradis.'
blog_keywords: 'cinéma,moustache,punchline,boloss'
blog_language: 'fr'
blog_name: 'Le blog de Jean Rochefort, élu roy de France par les internets.'
license: 'Licence royale'

Pour plus d'informations sur la configuration du blog, rendez-vous ici.

Et voilà, c'est terminé ! Votre blog est prêt à l'emploi !

Si vous avez rencontré une difficulté durant ce tutoriel, jetez un œil à la FAQ, la solution s'y trouvera certainement !

3.2 Créer une nouvelle publication

Une publication valide doit avoir un nom de fichier avec un format particulier. Vous pourriez le faire vous-même, mais ça craint un peu...

VenC vous permet de créer une publication en une commande avec le bon nom de fichier et un contenu de base prêt à être complété.

venc -ne "nom de la publication"

Ou :

venc --new-entry "nom de la publication"

Pour créer une nouvelle publication, vous devez :

Si vous ne spécifiez pas de nom de template de publication, VenC produira une publication totalement vierge. Le nom de template est en fait le nom de fichier du template désiré. Les fichiers de template se trouvent dans le répertoire templates de votre projet ou dans :

~/.local/share/VenC/themes_templates

Par exemple :

venc -ne "nom de la publication" nom_de_fichier_du_template

À noter que certains templates nécessitent des paramètres supplémentaires pour fonctionner. Le chapitre 4.5.1 fournit des exemples sur la façon dont cela fonctionne.

À l'issue de cette commande, VenC essaiera d'ouvrir la nouvelle publication avec l'éditeur de texte spécifié dans la variable d'environnement EDITOR ou à défaut dans le fichier de configuration principale blog_configuration.yaml.

Maintenant, il faut rédiger le contenu de votre choix. Vous voulez sans doute le faire dans un langage de balisage cool et décontracté. Avec Markdown par exemple. VenC supporte aussi AsciiDoc ou reStructuredText. Dans tous les cas, ces langages de balisage nécessitent les modules Python correspondant. Ceux-là ne sont pas installés par défaut et vous devez les installer explicitement :

Une fois que le module que vous souhaitez utiliser est installé il faut indiquer le langage de markup dans les métadonnées de votre publication.

3.3 Générer votre blog

Vous avez donc écrit un ou plusieurs articles et vous voulez voir ce que ça donne ? Pas de souci ! Placez-vous dans le répertoire de votre blog et lancez la commande suivante :

jeanrochefort@anonymous ~ $ venc --export-blog concrete

Cette commande va créer les pages HTML de votre blog en utilisant le thème Concrete. Il s'agit du thème par défaut livré avec VenC. Il peut vous servir de base pour construire le vôtre. Pour en savoir plus sur la façon dont ça fonctionne, rendez-vous au chapitre 4.6.

VenC utilise par défaut le thème local quand aucun nom de thème ne lui est précisé. Si vous avez suivi ce tutoriel depuis le début, le répertoire theme de votre projet devrait être vide, il ne peut donc pas être utilisé en l'état.

Le contenu de votre site est maintenant disponible dans le répertoire blog de votre projet. Pour visualiser le résultat, vous pouvez utiliser la commande :

jeanrochefort@anonymous ~ $ venc --serv

VenC crée alors un serveur HTTP local accessible par défaut à l'adresse suivante :

http://localhost:8888

(Une fois que vous aurez fini de visualiser le résultat, pour arrêter le serveur HTTP local, il suffit de taper CTRL+C dans le terminal actif). À noter que cette fonctionnalité ne sert qu'à la prévisualisation ! N'utilisez pas ça sur un serveur pour donner un accès public à votre site. Il vous arriverait malheur, ou pire...

Et voilà ! Le moins que l'on puisse dire, c'est que vous pesez lourd dans le game maintenant !

3.4 Comment mettre en ligne votre site

Maintenant que votre blog vous plaît, il est temps de le mettre en ligne et d'en faire profiter les internautes !

Il y a plusieurs façons de faire. La première approche consiste à copier manuellement le contenu du répertoire blog/ vers le serveur en ligne. Mais ce peut être un peu fastidieux quand on sait que VenC peut prendre en charge le transfert de votre blog via FTP.

Pour que VenC puisse mettre en ligne votre blog, vous devez lui fournir quelques informations dans le fichier blog_configuration.yaml :

Attention : soyez vigilant en renseignant le champ ftp qui détermine le chemin de destination. Au moment de l'exportation en ligne, VenC efface le contenu de ce répertoire ! Assurez-vous de savoir ce que vous faites !

Une fois que vous avez fourni les informations dont VenC a besoin, vous pouvez copier votre blog sur le serveur de destination avec :

jeanrochefort@anonymous ~ $ venc --remote-copy

De cette façon, VenC vous demandera de vous authentifier auprès du serveur. Le transfert ne commencera qu'une fois que vous vous serez authentifié.

Vous pouvez aller vous chercher un café, ou un jus de tomate. Perso, je préfère le jus de tomate pour patienter. Avec du parmesan, du sel de céleri et du Tabasco.

Avec cette première méthode, le blog doit déjà avoir été exporté localement avec :

venc -xb

VenC vous permet d'exporter localement et de mettre en ligne en une seule commande :

jeanrochefort@anonymous ~ $ venc --export-via-ftp [thème à préciser en option]

Comme pour la commande précédente, vous devrez vous authentifier. Vous pouvez également préciser un nom de thème avec lequel vous voulez générer votre blog.

Voilà, c'est tout ! Normalement, votre blog devrait être en ligne avec ça !

3.5 Créer votre thème

C'est le moment d'attaquer le sujet qui croustille sous la dent : comment créer un thème et organiser visuellement le contenu de son site avec VenC ?

C'est ce que nous allons voir dans la joie et la bonne humeur dans ce qui va suivre.

Le prérequis étant tout de même d'avoir quelques notions en HTML, il faut également noter que ce chapitre et l'ensemble des parties qui le composent n'ont pas vocation à faire de vous des mages noirs spé web design. L'enjeu ici est de voir comment intégrer les fonctionnalités de VenC dans du code HTML, tout en comprenant la structure des fichiers composant un thème.

Bonne lecture !

3.5.1 Structure du thème

Un thème est composé d'un ensemble de fichiers que VenC charge en mémoire et dont il va se servir pour générer votre site. Nous allons créer dans cette première partie ces fichiers dont nous avons besoin et nous les remplirons au fur et à mesure dans la suite de ce tutoriel.

Pour commencer, placez-vous dans la racine de votre projet :

anonyme@anonymous /path/to/your/project $ ls
blog  blog_configuration.yaml  caches  entries  extra  includes  theme

Si vous n'avez pas déjà installé un thème, le répertoire theme devrait être vide.

Nous allons y créer à l'intérieur deux répertoires :

anonyme@anonymous ~ $ cd /path/to/your/project/theme
anonyme@anonymous /path/to/your/project/theme $ mkdir assets chunks

Ceci étant fait, on va créer les morceaux composant notre site dans le répertoire chunks :

touch \
    header.html \
    entry.html \
    footer.html \
    rssHeader.xml \
    rssEntry.xml \
    rssFooter.xml \
    atomHeader.xml \
    atomEntry.xml \
    atomFooter.xml \
    video.html \
    autio.html

Se pose donc maintenant la question de ce à quoi servent ces fichiers. On peut remarquer une récurrence dans le nom de ceux-là :

header.htmlentry.htmlfooter.html
rssHeader.xmlrssEntry.xmlrssFooter.xml
atomHeader.xmlatomEntry.xmlatomFooter.xml

Pour construire une page, VenC prend d'abord un entête (header.html) où il va chercher des motifs VenC à interpréter.

Puisque VenC est spécialisé dans la construction de blogs, il va ensuite mettre bout à bout le corps d'une publication (entry.html) pour chaque publication à afficher sur la page courante. Comme pour l'entête, VenC va y chercher des motifs à interpréter.

Enfin, une fois que toutes les publications de la page courante ont été rassemblées, VenC termine la construction de la page courante avec un pied de page (footer.html). Comme pour les autres morceaux, VenC cherchera des motifs à interpréter.

C'est la même logique qui est utilisée pour les flux Atom et RSS.

Voilà pour les neuf premiers fichiers.

Il reste maintenant video.html et audio.html : HTML5 permet d'inclure dans une page du contenu multimédia. Il existe un lecteur par défaut avec une configuration minimale, mais il est aussi possible de personnaliser ce lecteur pour avoir les fonctionnalités et l'apparence que vous souhaitez. C'est donc dans ces deux derniers fichiers que ça va se jouer.

3.5.2 Créer l'entête HTML

L'entête HTML de VenC est défini dans le fichier header.html du répertoire chunks de votre thème. Ce fichier est réutilisé à chaque fois que VenC génère une page HTML. Les motifs VenC permettent de mettre en contexte cette portion du code pour l'adapter au contexte dans lequel il se trouve.

La structure de ce fichier ressemble à ça :

<!DOCTYPE HTML>
<html lang=".:GetBlogLanguage:.">
    <head>
        <meta charset="utf-8">
        <title>.:GetBlogName:. .:GetThreadName::| {value}:.</title>
        .:GetStyleSheets:.
        <link rel="stylesheet" href=".:GetRelativeRoot:./style.css" type="text/css">
        <meta name="description" content=".:GetBlogDescription:.">
    </head>
    <body>
    <!-- TOP LEVEL MENU, BANNER, ETC ... --> 

Enfin on remarque également que le contenu de ce fichier s'arrête à peu près à l'ouverture de la balise body. Nous pouvons insérer à ce niveau le code pour un menu latéral, avec l'index des catégories ou des chapitres de votre site. Ou bien il pourrait y avoir un nuage de mots-clés, ou la liste des périodes archivées. À vous de voir !

3.5.2.1 Créer un menu

Maintenant que nous avons vu comment se goupille l'entête, nous pouvons le compléter selon nos besoins.

Pour commencer, à la fin de notre fichier header.html nous allons rajouter la paire de balise suivante :

<header>
</header>

Nous y mettrons ici les éléments qui composent un menu générique :

Utiliser les deux premiers points peut être redondant dans la mesure ou VenC utilise la même source de données pour construire ces listes. En général, c'est soit l'un soit l'autre, mais nous verrons évidemment les deux cas de figure.

Concernant la liste d'archives, il faut noter qu'il s'agit d'une liste simple : il n'est pas possible pour le moment de la rendre hiérarchisée.

Enfin, et dans tous les cas, il faut rappeler que même si vous utilisez les motifs VenC correspondant à ces fonctionnalités, elles ne seront pas actives si vous ne dites pas explicitement à VenC de le faire.

En effet, ces listes sont dans la pratique un moyen de naviguer sur votre site et ceci implique donc que VenC a généré le contenu organisé correspondant. En l'occurrence, il faut s'assurer que dans votre fichier de configuration les options suivantes soient configurées à false pour activer, respectivement, les archives et les catégories :

VenC fonctionne de cette manière parce que la responsabilité de ce qui doit être généré relève de l'utilisateur final. C'est au thème de s'adapter et d'anticiper que l'utilisateur final veut ou ne veut pas générer tel ou tel contenu organisé. Si vous prévoyez de créer un thème et de le distribuer sur les Internets, il faudra donc en tenir compte.

3.5.2.2 Créer une liste d'archives

Avant toute chose, comme nous l'avons vu précédemment, il faut que dans votre fichier de configuration l'option disable_archives soit configurée correctement.

Entre les balises header que nous avons ajoutées à la fin du fichier header.html, nous allons ajouter le code suivant en utilisant le motif ForBlogArchives :

.:ForBlogArchives::{value}:: :. 

L'idée ici est d'itérer à travers la liste des archives de VenC, afin de récupérer la valeur de chaque élément de cette liste. Ici, la valeur correspond au nom de l'archive courante. Ce nom est défini par le format de date que vous avez indiqué dans votre fichier de configuration principale avec l'option archives_directory_name.

Mais évidemment le code ci-dessus ne suffit pas, puisque ce que nous voulons c'est une liste HTML de liens vers les archives. Du coup, faisons plutôt quelque chose comme ça :

<ul id="blogarchives">
  .:ForBlogArchives::
  <li class="blogarchivesitem">
    <a href="{path}" title="{value} ({count})">{value}</a>
  </li>
  ::
  :. 
</ul>

Ça n'a plus la même tête, hein ? En effet :

Avec ça, VenC va nous générer ce que nous voulons.

Cependant comme nous l'avons dit dans le chapitre 3.5.2.1, la bonne pratique est de faire en sorte que le thème, si l'on veut le distribuer, s'adapte à la configuration du blog. En effet, si jamais les archives sont désactivées, alors ForBlogArchives ne produira rien et on se retrouvera avec une paire de balises ul vide. Ça n'est pas très propre. C'est d'autant plus problématique quand la liste est décorée avec un titre ou est contenue dans une boîte.

Pour pallier ces problèmes, VenC permet de tester la configuration du projet afin d'adapter le thème à la situation avec le motif IfBlogMetadataIsTrue.

 
.:IfBlogMetadataIsTrue::disable_archives::
    <!-- Bloc HTML à conserver si la variable vaut `true` -->
    ::
    <!-- Bloc HTML à conserver si la variable vaut `false` -->
:.
 

Ici, ce qu'on teste c'est l'option disable_archives avec IfBlogMetadataIsTrue. Si elle vaut true, alors on ne fait rien. Sinon, on met le bloc de code que nous avons écrit tout à l'heure, ce qui nous donne au final :

 
.:IfBlogMetadataIsTrue::disable_archives::
    <!-- Pas de liste d'archives à afficher -->
::
    <ul id="blogarchives">
    .:ForBlogArchives::
          <li class="blogarchivesitem">
            <a href="{path}" title="{value} ({count})">{value}</a>
          </li>:
          ::
    :.
    </ul>
:.
 

Avec ça, on est vraiment bon et le thème que vous construisez sera modulable et capable de s'adapter à vos besoins, mais aussi à la configuration de ceux qui utiliseront votre thème !

3.5.2.3 Afficher les catégories

De façon similaire aux archives, il faut que dans votre fichier de configuration l'option disable_categories soit configurée correctement.

Il y a plusieurs façons d'afficher les catégories de votre blog :

Nous verrons les deux cas.

Pour commencer, nous allons préparer le terrain pour que le thème soit modulable par les utilisateurs finaux.

Entre les balises header que vous avez ajoutées dans le chapitre 3.5.2.1, ajoutez maintenant le code suivant :

.:IfBlogMetadataIsTrue::disable_categories::
    <!-- Bloc HTML à conserver si la variable vaut `true` -->
    ::
    <!-- Bloc HTML à conserver si la variable vaut `false` -->
:.

À l'aide du motif IfBlogMetadataIsTrue, on teste si les pages des catégories doivent être créées par VenC. On peut aller plus loin, en demandant à VenC de conserver ou non des blocs de codes de façon plus précise, de la façon suivante :

.:IfBlogMetadataIsTrue::disable_categories::
    <!-- Bloc HTML à conserver si la variable vaut `true` -->
    ::
        .:IfBlogMetadataIsTrue::display_categories_as_list::
            <!-- Bloc HTML à conserver si la variable vaut `true` -->
        :.
        
        .:IfBlogMetadataIsTrue::display_categories_as_tree::
            <!-- Bloc HTML à conserver si la variable vaut `true` -->
        :.
:.

On utilise à nouveau IfBlogMetadataIsTrue pour tester les variables suivantes (à noter que ce ne sont pas des options réservées par VenC, vous pouvez donc définir les vôtres si vous le souhaitez) :

Ce faisant, vous pourrez contrôler depuis votre fichier de configuration quels types d'affichage vous souhaitez pour vos catégories ! Malin !

On arrive maintenant au gros morceau : l'affichage de la liste des catégories !

Affichage des catégories en nuage

C'est le cas le plus simple. Nous allons pour ce faire utiliser GetFlattenedBlogCategories.

Par exemple :

<ul id="blogcategorieslist">

.:GetFlattenedBlogCategories::
  <li class="blogcategoriesitem">
    <a href="{path}" title="{value} ({count})">{value}</a>
  </li>
  ::
  :. 
</ul>

Ici, on définit une liste avec la balise HTML ul. On y insère le motif VenC GetFlattenedBlogCategories. qui va générer itérativement les items de la liste. Nous y écrivons donc en premier argument dudit motif le couple de balise li, qui correspond à l'item courant de la liste.

Enfin, les variables du motif permettent de récupérer respectivement :

Il n'y a plus qu'à insérer tout ça dans le code que nous avons préparé dans la balise header :

.:IfBlogMetadataIsTrue::disable_categories::
    <!-- Bloc HTML à conserver si la variable vaut `true` -->
    ::
        .:IfBlogMetadataIsTrue::display_categories_as_list::
            <ul id="blogcategorieslist">
            .:GetFlattenedBlogCategories::
              <li class="blogcategoriesitem">
                <a href="{path}" title="{value} ({count})">{value}</a>
              </li>
              ::
            :.
            </ul>
        :.
        
        .:IfBlogMetadataIsTrue::display_categories_as_tree::
            <!-- Bloc HTML à conserver si la variable vaut `true` -->
        :.
:.

Affichage des catégories en arbre

Cet affichage est un peu plus complexe et ne se prête pas à toutes les mises en page, mais il a le mérite de rendre plus clair l'organisation de votre site.

L'idée de l'affichage en arbre de catégories, c'est de mettre en évidence le fait que plusieurs sous-catégories peuvent appartenir à une catégorie parente.

Par exemple, si votre blog parle de science et d'art, vous aurez donc deux catégories de base. Pour avoir plus de granularité sur l'organisation de vos publications, vous pouvez indiquer à VenC qu'une publication traite aussi de peinture ou de littérature. Deux sous-catégories de la catégorie "Art". Et bien sûr, il n'y a pas de limite dans l'imbrication de catégories, ce qui vous laisse beaucoup de latitude pour trier vos publications.

Pour savoir comment définir des catégories dans une publication, rendez-vous ici.

Pour afficher un arbre hiérarchique de catégories, on utilise le motif VenC GetBlogCategoriesTree. La documentation technique propose l'exemple suivant, qui convient tout à fait à la majorité des cas de figure :

.:GetBlogCategoriesTree::
    <ul>::
    <li><a href="{path}" title="{count} publications">{value}</a>::
    {childs}</li>::
    </ul>
:.

Ce motif fonctionne différemment de GetFlattenedBlogCategories. En effet, il faut indiquer à la fonction :

On remarque également que comme pour GetFlattenedBlogCategories, on peut utiliser les variables path, count et value.

Enfin, un autre élément est requis pour créer une structure récursive de catégories : c'est la variable childs, qui contient le nœud enfant. Si vous oubliez de placer cette variable dans les arguments 2 ou 3, le résultat de l'appel du motif ne sera pas celui attendu.

Avec ça on est bon et on peut maintenant placer notre code dans celui que nous avons préparé dans la balise header de notre entête HTML :

.:IfBlogMetadataIsTrue::disable_categories::
    <!-- Bloc HTML à conserver si la variable vaut `true` -->
    ::
        .:IfBlogMetadataIsTrue::display_categories_as_list::
            <ul id="blogcategorieslist">
            .:GetFlattenedBlogCategories::
              <li class="blogcategoriesitem">
                <a href="{path}" title="{value} ({count})">{value}</a>
              </li>
              ::
            :.
            </ul>
        :.
        
        .:IfBlogMetadataIsTrue::display_categories_as_tree::
            .:GetBlogCategoriesTree::
                <ul>::
                <li><a href="{path}" title="{count} publications">{value}</a>::
                {childs}</li>::
                </ul>
            :.
        :.
:.

Et voilà, c'est tout bon pour les catégories ! Si cependant vous voulez aller plus loin, avec un contrôle plus fin de l'affichage et utiliser les fonctions avancées de taxonomie vous pouvez également jeter un œil à ces fonctions :

3.5.3 Créer le corps de la publication

Dans les chapitres précédents, nous avons vu comment créer l'entête de votre site. Nous allons maintenant voir comment créer le corps de vos publications.

La première chose à faire est de modifier ou créer le fichier entry.html et d'y ajouter les balises HTML qui contiendront votre contenu :

<div class="entry" id="entry.:GetEntryID:.">
</div>

Certains modules JavaScript nécessitent que le bloc div ait pour classe la valeur "entry", c'est donc une bonne pratique de définir la classe du conteneur de cette façon. Rien ne vous empêche cependant d'ajouter d'autres classes si vous le souhaitez.

Il est également de bon ton, mais pas obligatoire, d'assigner au conteneur un identifiant unique basé sur celui de votre publication. C'est ce que permet de faire GetEntryID.

Vous pouvez également ajouter le titre de la publication. Quelque chose comme le code suivant devrait faire l'affaire :

<div class="entry" id="entry.:GetEntryID:.">
    <h1><a class="entry_title" href=".:GetEntryPath:.">.:GetEntryTitle:.</a></h1>
</div>

Ici on utilise deux nouveaux motifs :

Se pose maintenant la question de savoir quand afficher le résumé de votre billet et quand afficher son contenu complet. Il y a trois motifs à considérer pour ça :

La plupart du temps vous utiliserez GetEntryContent et c'est ce que nous ferons dans notre exemple. Nous aurions donc quelque chose comme ceci :

<div class="entry" id="entry.:GetEntryID:.">
    <h1><a class="entry_title" href=".:GetEntryPath:.">.:GetEntryTitle:.</a></h1>
    <div class="entry_content">
        .:GetEnTryContent:.
    </div>
</div>

Pas de grande modification, si ce n'est l'ajout du motif et d'une paire de balises div pour pouvoir plus tard personnaliser le style CSS de notre publication.

Voilà pour une version minimale du fichier entry.html.

Dans les chapitres suivants, nous verrons des modifications plus avancées pour personnaliser ce fichier selon vos besoins.

3.5.3.1 Ajouter et utiliser la date de la publication

Selon la façon dont vous souhaitez afficher votre site et son contenu, vous pourriez vouloir rendre visible la date de publication de votre billet. Pour ce faire, on utilise le motif GetEntryDate.

Par exemple, ligne 3 :

1
2
3
4
5
6
7
<div class="entry" id="entry.:GetEntryID:.">
    <h1><a class="entry_title" href=".:GetEntryPath:.">.:GetEntryTitle:.</a></h1>
    <span class="entry-date">.:GetEntryDate:.</span>
    <div class="entry_content">
        .:GetEnTryContent:.
    </div>
</div>

Souvent, les publications sont regroupées par période de dates de publication (par mois par exemple). Il est possible d'accéder à ces archives. Une bonne pratique est donc d'associer la date ainsi affichée à un lien vers l'archive correspondante. On utilise pour ça GetEntryArchivePath.

En changeant la ligne 3 en conséquence, on a alors par exemple :

1
2
3
4
5
6
7
<div class="entry" id="entry.:GetEntryID:.">
    <h1><a class="entry_title" href=".:GetEntryPath:.">.:GetEntryTitle:.</a></h1>
    <span class="entry-date"><a href=".:GetEntryArchivePath:.">.:GetEntryDate:.</a></span>
    <div class="entry_content">
        .:GetEnTryContent:.
    </div>
</div>

3.5.3.2 Ajouter et utiliser les catégories de la publication

Comme pour les archives, une publication peut appartenir à des catégories. Naturellement, vous pouvez afficher ces catégories dans votre publication. La récupération et l'affichage de ces catégories fonctionnent exactement de la même façon que dans le chapitre 3.5.2.3, mais au lieu d'utiliser ces motifs :

On utilisera les motifs suivants :

En effet, ces deux motifs récupèrent uniquement les catégories associées à la publication courante. La plupart du temps, dans une publication, on utilisera plutôt GetFlattenedEntryCategories. En effet, afficher l'arbre des catégories spécique à la publication n'est pertinent que dans des cas très spécifiques.

En se basant sur le chapitre 3.5.2.3 et sur ce que nous avons vu précédemment, nous aurions alors quelque chose ça :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<div class="entry" id="entry.:GetEntryID:.">
    <h1><a class="entry_title" href=".:GetEntryPath:.">.:GetEntryTitle:.</a></h1>
    <span class="entry-date"><a href=".:GetEntryArchivePath:.">.:GetEntryDate:.</a></span>
    
    .:IfBlogMetadataIsTrue::disable_categories::
    <!-- Bloc HTML à conserver si la variable vaut true -->
    ::
        .:IfBlogMetadataIsTrue::display_entry_categories_as_list::
            <ul id="entrycategorieslist">
            .:GetFlattenedEntryCategories::
              <li class="entrycategoriesitem">
                <a href="{path}" title="{value} ({count})">{value}</a>
              </li>
              ::
            :.
            </ul>
        :.
        
        .:IfBlogMetadataIsTrue::display_entry_categories_as_tree::
            .:GetEntryCategoriesTree::
                <ul>::
                <li><a href="{path}" title="{count} publications">{value}</a>::
                {childs}</li>::
                </ul>
            :.
        :.
    :.
    
    <div class="entry_content">
        .:GetEnTryContent:.
    </div>
</div>

Quelques remarques :

3.5.4 Créer le pied de page HTML

Nous avons vu comment créer l'entête d'une page et nous avons vu comment structurer le corps de nos publications. Il reste maintenant à voir comment créer le pied de page de votre site.

En premier lieu, il convient de finir ce qui a été commencé dans le chapitre 3.5.2, à savoir fermer les balises HTML qui ont été ouvertes. Pour ça, créez un nouveau fichier footer.html dans le répertoire chunks de votre thème et éditez-le comme suit :

    </body>
</html>

On y ajoute maintenant une paire de balises footer, qui contiendra les éléments de notre pied de page :

        <footer>
        </footer>
    </body>
</html>

3.5.4.1 Animation de chargement

C'est purement cosmétique mais vous pouvez configurer une animation de chargement, comme expliqué dans le chapitre 4.6.2.2, lorsque vous utilisez le module JS de défilement infini.

On peut alors écrire, lignes 2 à 4, quelque chose comme :

1
2
3
4
5
6
7
        <footer>
              .:GetBlogMetadataIfExists::loading_image::
                  <img id="__VENC_LOADING__" src=".:GetRelativeRoot:./{value}" />
              :.
        </footer>
    </body>
</html>

Avec GetBlogMetadataIfExists, on teste ici si une image de chargement a bien été définie dans le fichier de configuration principal. Si tel est le cas, alors la balise img est ajoutée.

Notez que l'attribut id a pour valeur __VENC_LOADING__. Cela permet au module JS de retrouver l'élément à afficher ou à cacher, selon que la page est ou non en cours de chargement.

Enfin, remarquons à la ligne 3 :

src=".:GetRelativeRoot:./{value}" 

Ici la variable value portera le nom de fichier contenu dans loading_image, si ce champ est défini dans votre fichier de configuration.

Enfin, comme souvent avec VenC quand on référence une ressource dans un fichier HTML, on utilise le motif GetRelativeRoot qui permet de construire le chemin relatif du fichier qu'on référence.

3.5.4.2 Ajouter du code HTML personnalisé

Une bonne pratique, si vous envisagez de diffuser votre thème est de permettre aux utilisateurs finaux de personnaliser l'entête ou le pied de page avec du code HTML.

Nous allons voir ici comment inclure du contenu HTML dans le pied de page, mais ce qui va suivre fonctionne évidemment aussi dans l'entête.

Dans l'exemple ci-dessous, ce sont les lignes 5, 6 et 7 qui nous intéressent :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
        <footer>
            .:GetBlogMetadataIfExists::loading_image::
                <img id="__VENC_LOADING__" src=".:GetRelativeRoot:./{value}" />
            :.
            .:IncludeFileIfExists::
                .:GetBlogMetadataIfNotNull::include_in_footer:.        
            :.
        </footer>
    </body>
</html>

IncludeFileIfExists permet d'inclure un fichier du type de votre choix. Généralement, il s'agira d'un fichier contenant du code HTML.

Ici le seul argument de la fonction est retourné par GetBlogMetadataIfNotNull, qui permet de récupérer le nom du fichier à inclure s'il est défini dans le fichier de configuration du blog.

Dans le cas où le nom de fichier n'est pas défini, la fonction renvoie une chaîne de caractères vide transférée à IncludeFileIfExists, qui sera ignorée en conséquence.

3.5.4.3 Ajouter des liens de navigation

Nous concluons le pied de page avec les liens de navigation. À noter que ce qui va suivre peut également être programmé dans l'entête de votre site.

Comme on s'en doute, votre blog n'affiche pas toutes les publications d'un fil sur une seule page. VenC utilise un système de pagination que vous pouvez configurer ici. En conséquence, il faut que le visiteur de votre site puisse naviguer entre ces différentes pages.

Pour cela on uitilise trois motifs différents :

En reprenant l'exemple du chapitre précédent, nous aurions alors aux lignes 8 à 14 :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
        <footer>
            .:GetBlogMetadataIfExists::loading_image::
                <img id="__VENC_LOADING__" src=".:GetRelativeRoot:./{value}" />
            :.
            .:IncludeFileIfExists::
                .:GetBlogMetadataIfNotNull::include_in_footer:.        
            :.
            .:GetPreviousPage::<a id="previous_link" href="{path}"></a>:.
            <ul id="navigation_pages_list">
                .:ForPages::5::<li class="page_list_item">
                    <a href="{path}">{page_number}</a>
                </li>:: . :.
            </ul>
            .:GetNextPage::<a id="next_link" href="{path}"></a>:.
        </footer>
    </body>
</html>

À noter que si la page courante est la première ou la dernière page, alors respectivement les motifs GetPreviousPage et GetNextPage seront ignorés et ne retourneront rien.

Notons également que si vous venez de commencer votre blog, il n'y aura probablement pas beaucoup de publications au début. Ces publications pourraient ne requérir qu'une seule page pour être toutes affichées, et il n'y aurait donc pas de liste de pages à afficher non plus.

Du coup tout ça c'est pas mal. Mais on peut encore faire mieux.

Le code ci-dessous actualise ce qui a été déjà fait pour illustrer ces remarques :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
        <footer>
            .:GetBlogMetadataIfExists::loading_image::
                <img id="__VENC_LOADING__" src=".:GetRelativeRoot:./{value}" />
            :.
            .:IncludeFileIfExists::
                .:GetBlogMetadataIfNotNull::include_in_footer:.        
            :.
            .:GetPreviousPage::<a id="previous_link" href="{path}">.:IfInThread::←::{entry_title} ←:.</a>:.
            .:IfPages::
                <ul id="navigation_pages_list">
                    .:ForPages::5::<li class="page_list_item">
                        <a href="{path}">{page_number}</a>
                    </li>:: . :.
                </ul>
            :.
            .:GetNextPage::<a id="next_link" href="{path}">.:IfInThread::→::→ {entry_title}:.</a>:.
        </footer>
    </body>
</html>

3.5.5 Syndication

VenC peut générer un flux Atom ou RSS en suivant la même logique de construction que celle des pages HTML de votre site, c'est-à-dire avec un entête, un corps et un pied de page. Vous pouvez également y utiliser les mêmes motifs que ceux que nous avons vus dans les chapitres 3.5.2, 3.5.3 et 3.5.4.

3.5.5.1 Flux Atom

Nous allons voir ici comment programmer les trois fichiers qui composent le flux Atom :

Pour en savoir plus sur le format Atom lui-même, rendez-vous ici.

atomHeader.xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <link
      href=".:GetBlogURL:..:GetRelativeLocation:./atom_feed.xml"
      rel="self"
      type="application/atom+xml"
    />
    
    <link href=".:GetBlogURL:." rel="alternate" type="text/html" />
    
    <title>.:GetBlogName:. .:GetThreadName::| {value}:.</title>
    .:GetBlogMetadataIfNotNull::blog_description::<subtitle>{value}</subtitle>:.
    <id>.:GetBlogURL:..:GetRelativeLocation:.</id>
    <updated>.:GetLastEntryTimestamp::%Y-%m-%dT%H:%M:%SZ:.</updated>

    <author>
     .:GetBlogMetadataIfNotNull::author_name::<name>{value}</name>:.
     .:GetBlogMetadataIfNotNull::author_email::<email>{value}</email>:.
    </author> 

Comme on peut le voir, il y a des similitudes avec ce qui a été réalisé et montré dans le chapitre 3.5.2.

Les nouveautés ici, c'est que l'on construit des URL uniques avec GetBlogURL et GetRelativeLocation comme on peut le voir aux lignes 4, 9 et 13.

On utilise également à la ligne 14 le motif GetLastEntryTimestamp pour avoir l'horodatage de la dernière publication du site.

atomEntry.xml

1
2
3
4
5
6
7
8
9
    <entry>
        <id>.:GetBlogURL:./.:GetEntryPath:.</id>
        <title>.:GetEntryTitle:.</title>
        <link href=".:GetBlogURL:./.:GetEntryPath:." rel="alternate" type="text/html"/>
        <updated>.:GetEntryDate::%Y-%m-%dT%H:%M:%SZ:.</updated>
        <content type="xhtml">
            <div xmlns="http://www.w3.org/1999/xhtml">.:GetEntryPreview:.</div>
        </content>
    </entry>

Ici, nous utilisons à la ligne 7 GetEntryPreview. Ici ça a du sens, car nous sommes dans un flux Atom dont le but est de présenter succinctement les dernières publications. Rien ne vous empêche cependant d'utiliser GetEntryContent.

Comme dans atomHeader.xml, on crée aux lignes 2 et 4 une même URL unique qui correspond à la publication avec GetBlogURL et GetEntryPath que nous avons déjà vu dans les chapitres précédents.

atomFooter.xml

</feed>

Facile !

3.5.5.2 Flux RSS

Nous allons voir ici comment programmer les trois fichiers qui composent le flux RSS :

Pour en savoir plus sur le format RSS, rendez-vous ici.

rssHeader.html

1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
      <title>.:GetBlogName:. .:GetThreadName::| {value}:.</title>
      <link>.:GetBlogURL:..:GetRelativeLocation:.</link>
      <description>.:GetBlogDescription:.</description> 

Sans grande surprise, ça fonctionne un peu comme le flux Atom vu au chapitre 3.5.5.1.

On indique dans l'entête, aux lignes 5 et 7, l'URL du site avec GetBlogURL et GetRelativeLocation.

rssEntry.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <item>
      <title>.:GetEntryTitle:.</title>
      <link>.:GetBlogURL:./.:GetEntryPath:.</link>
      <guid isPermaLink="true">.:GetBlogURL:./.:GetEntryPath:.</guid>
      <pubDate>.:GetEntryDate::%a, %d %b %Y %H:%M:%S GMT:.</pubDate>
      <description>
        <![CDATA[
            .:GetEntryPreview:.
        ]]>
      </description>
    </item> 

L'utilisation de GetBlogURL et de GetEntryPath aux lignes 3 et 4 sert le même usage que celui montré dans atomEntry.xml.

Idem pour GetEntryPreview, on peut également utiliser GetEntryContent.

rssFooter.html

   </channel>
</rss>

Rien à faire de bien compliqué, si ce n'est fermer ce qui a été ouvert. Trivial !

3.5.6 Multimédia

Lorsque vous utilisez les motifs Audio ou Video, VenC renvoie respectivement le contenu formaté des fichiers audio.html et video.html de votre thème.

Selon ce que vous envisagez de faire, vous pourriez avoir besoin de définir des règles CSS supplémentaires dans le répertoire assets de votre thème. Vous pourriez également vouloir utiliser des scripts JS supplémentaires, que vous auriez définis vous-même dans ce même répertoire.

Mais pour le moment, on va faire une utilisation simple des balises audio et video que propose HTML5.

Audio

<audio controls style="width: 100%;">
{source}
Your browser does not support the audio element.
</audio>

On reconnaît ici le format de variable utilisé par VenC :

Video

<video controls poster="{poster}" style="width: 100%;">
{source}
Your browser does not support the video tag.
</video>

Idem que pour audio, mais on spécifie en plus une variable poster qui contiendra une image de prévisualisation de la vidéo, celle qui sera affichée en fond dans le lecteur en attendant que le visiteur lance la lecture de la vidéo.