Un générateur de site statique qui casse des briques. VenC est tellement rapide qu'il enfreint le principe de causalité et produit de l'énergie surunitaire !
|
Un générateur de site statique qui casse des briques. VenC est tellement rapide qu'il enfreint le principe de causalité et produit de l'énergie surunitaire ! |
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.
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 !
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 :
$(venc -pp)/themes_templates
$(venc -pp) étant le répertoire où se trouvent les assets de VenC.
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.
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 !
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 :
ftp_host : l'adresse du serveur FTP de destination.path:
ftp : le chemin de destination où sera copié le contenu de votre blog sur le serveur en ligne.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 !
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 !
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 :
assets : nous allons le laisser vide pour le moment, mais on peut déjà faire remarquer que c'est ici que vous mettrez des choses comme vos feuilles de style CSS.chunks : c'est le répertoire contenant les fameux fichiers dont nous parlions un peu plus haut.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.html | entry.html | footer.html |
rssHeader.xml | rssEntry.xml | rssFooter.xml |
atomHeader.xml | atomEntry.xml | atomFooter.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.
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 ... -->
GetBlogLanguage : ce pattern permet de récupérer le langage du blog que vous
avez défini dans votre fichier de configuration principal.
Ça n'est pas obligatoire, mais les moteurs de recherche apprécient l'effort.GetBlogName : ce pattern permet de récupérer le nom de votre blog. Typiquement à utiliser entre les balises title. Le nom de votre site est défini dans votre fichier de configuration principal.GetThreadName : vous pourriez vouloir afficher dans le titre de l'onglet ou de la fenêtre active plus que le titre du blog. Par exemple, le nom du fil de catégories courant ou le titre de la publication courante. C'est ce que permet de faire ce motif.GetStyleSheets : ce motif n'est pas obligatoire. Vous en aurez cependant besoin si vous prévoyez d'utiliser la coloration syntaxique dans vos publications.GetRelativeRoot : comme votre feuille de style est copiée à la racine du site, mais que celle-ci peut être référencée depuis des sous-répertoires, vous pourriez avoir besoin de construire un chemin relatif permettant d'y accéder. C'est ce que permet GetRelativeRoot.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 !
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.
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 :
ul pour avoir une liste HTML. L'identifiant de la balise ouvrante vous permettra plus tard d'en définir le style CSS.li dans le premier argument de ForBlogArchives. On a également assigné à cette balise une classe, qui vous permettra plus tard d'en définir le style CSS.li, on a ajouté une balise a pour pouvoir construire notre lien, porté par la variable path. On remarque également que l'attribut title affichera entre parenthèses le nombre de publications dans l'archive. Ça n'est pas obligatoire, mais c'est tout de même plus sympa, non ?a on retrouve bien la variable value, qui porte le nom de l'archive formatée comme indiqué plus haut.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 !
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) :
display_categories_as_treedisplay_categories_as_listCe 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 !
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` -->
:.
:.
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 :
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 :
GetEntryPath : permet de récupérer le chemin de la publication.GetEntryTitle : permet de récupérer le titre de votre publication.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 :
GetEntryContent : permet de récupérer systématiquement le contenu de votre publication.GetEntryPreview : permet de récupérer systématiquement le résumé de votre publication.PreviewIfInThreadElseContent : permet de récupérer conditionnellement le résumé ou le contenu de votre
publication. La condition étant de savoir si la page courante à générer se trouve dans un
thread ou s'il s'agit de la page de la publication elle-même. En effet, vous pourriez vouloir afficher uniquement le résumé de vos publications, à moins d'accéder à la publication elle-même.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.
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> |
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 :
display_entry_categories_as_list et display_entry_categories_as_tree qui doivent se trouver dans le fichier de configuration du blog. Or, nous pouvons imaginer
que l'on veuille contrôler l'affichage de nos catégories depuis la publication elle-même, c'est-à-dire en testant une métadonnée de la publication. Pour ce faire, on utiliserait par
exemple le motif IfEntryMetadataIsTrue
à la place de IfBlogMetadataIsTrue.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>
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.
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.
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 :
GetNextPage : permet de récupérer la page suivante si elle existe, sinon le motif est ignoré.GetPreviousPage : permet de récupérer la page précédente si elle existe, sinon le motif est ignoré.ForPages : permet de générer une liste de pages numérotées. La page courante correspond à l'item au centre de la liste.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> |
GetPreviousPage et GetNextPage devrait être assez intuitive. En effet, on utilise le motif
pour formater le texte passé en argument à la fonction. Dans ce texte, on utilise la variable {path} qui contient le chemin vers la page désirée.ForPages, on indique le nombre de page que l'on souhaite faire apparaître dans la liste. Dans le second argument, on formate l'item à générer en utilisant les variables path et page_number, qui contiennent respectivement le chemin vers la page cible ainsi que
son numéro (ligne 11).À 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.
IfPages : par exemple on voit bien que si au début votre site n'est pas très rempli
comme on l'a dit, alors il n'y aura pas de liste de pages à afficher et le motif ForPages sera ignoré. Or, les balises
HTML qui ouvrent et ferment la liste sont bien présentes, quoi qu'il arrive. On peut résoudre ce problème avec le motif IfPages,
qui permet d'afficher ou non un bloc de texte selon qu'il existe ou non plusieurs pages sur le fil de publications courant.IfInThread : avec ce motif, il est également possible de contrôler l'affichage des boutons "Suivant" ou "Précédent" selon que l'on est dans une publication individuelle, ou dans une page donnée d'un fil de publications.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> |
IfInThread permet d'ajouter une variable de motif qui sera utilisée par GetPreviousPage et GetNextPage.
Dans le cas où l'on se trouve sur une publication individuelle, on peut maintenant afficher le titre de la prochaine et de la précédente publication.IfPages embarque à la fois les balises HTML ul et le motif ForPages. S'il n'y a pas de liste de pages à générer, alors ces éléments sont supprimés.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.
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.
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.
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.
</feed>
Facile !
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.
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.
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.
</channel> </rss>
Rien à faire de bien compliqué, si ce n'est fermer ce qui a été ouvert. Trivial !
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 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 :
source va contenir les différentes sources de fichiers audios préformatés, qui seront insérés entre les balises audio.<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.