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 ! |
VenC utilise un moteur de reconnaissance de motifs permettant une mise en page facilitée et automatisée, notamment quand vous souhaitez réaliser votre propre design pour votre site. Il s'agit en quelque sorte d'un langage de balisage spécifique à VenC.
Un motif est en fait une fonction pouvant prendre des paramètres. Quand VenC rencontre un motif, il exécute la fonction qui lui est associée et retourne une chaîne de caractères formatée. Typiquement, les motifs permettent d'accéder aux données du blog ou de faire de la mise en page spécifique afin, par exemple, de réaliser un menu déroulant ou une barre de navigation.
Les motifs pouvant être utilisés dépendent du contexte dans lequel ils sont lus par VenC. La notion de contexte sera expliquée dans les chapitres suivants.
La syntaxe est très simple, chaque motif
commence par :
.:
Chaque motif
se termine par :
:.
Le ou les séparateurs d'argument à l'intérieur d'un motif
sont représentés par :
::
Un motif
a donc la forme suivante :
.:PatternName[::Argument 1][::Argument 2][::Argument N] ... :.
Un exemple de motif
sans argument est :
.:GetEntryTitle:.
Un exemple de motif
avec des arguments est :
.:ForBlogMetadataIfExists::some_value::{value}:.
Les motifs
peuvent être imbriqués :
.:ForBlogMetadataIfExists:: custom_scripts:: <script type="text/javascript" src=".:GetRelativeRoot:.{value}"></script> :.
Ci-dessus, GetRelativeRoot
est appelé dans le second argument de ForBlogMetadataIfExists
.
Les motifs
sont toujours exécutés par ordre d'imbrication quand c'est possible : À type de context égal, les motifs
les plus imbriqués sont exécutés en premier.
Certains motifs comportent des variables. Il s'agit de valeurs accessibles depuis/dans les arguments du motif.
Ces variables se présentent sous la forme de placeholder
Python,
ceux qui sont utilisés avec la fonction format
. Par exemple :
.:PoudreDePerlinpinpin::{carabistouille}:.
Ici la variable est identifiée par carabistouille
. Ce que contient la variable dépend du motif dans lequel elle est utilisée. Dans
les chapitres suivants, les motifs seront exhaustivement détaillés et expliqués, ainsi que leurs variables correspondantes.
Les motifs contextuels sont les derniers motifs à être interprétés par VenC dans le processus de génération des pages. En effet, ces motifs sont "contextuels" au sens où leur fonctionnement dépend de choses comme le fil de publications que VenC traite, du numéro de la page courante ou de l'emplacement de fichier de la page ainsi généré dans l'arborescence du blog.
Les motifs contextuels sont interprétés autant de fois qu'il y a de pages pour chaque occurrence de l'un de ceux-là.
Ce motif permet de générer une liste de liens de pagination.
.:ForPages::length::string::separator:.
length
: définit la longueur de la liste.separator
: le texte servant de séparateur.string
: le texte à formater, dans lequel seront accessibles les valeurs des variables ci-dessous.Ce motif comporte les variables suivantes :
entry_id
: si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page courante. Sinon, la variable est ignorée.entry_title
: si le contexte le permet, cette variable contient le titre de la publication associée à la page courante. Sinon, la variable est ignorée.page_number
: si le contexte le permet, cette variable contient le numéro de la page courante. Sinon, la variable est ignorée.path
: contient le chemin relatif de la page courante..:GetEntryContent:.
Ce pattern ne peut pas être utilisé dans un template, ni dans le corps d'une publication, cela provoquerait une erreur de récursion.
Ce pattern renvoie le contenu complet de la publication courante.
.:GetEntryPreview:.
Ce pattern ne peut pas être utilisé dans un template, ni dans le résumé d'une publication, cela provoquerait une erreur de récursion.
Ce pattern renvoie le résumé de la publication courante.
.:GetLastEntryTimestamp::time_format:.
Permet de récupérer la date formatée avec time_format
de la publication la plus récente dans le fil de publication courant.
.:GetNextPage::string:.
Permet de récupérer des informations sur la prochaine page, si elle existe.
string
: le texte à formater, depuis lequel seront accessibles les valeurs des variables ci-dessous.Ce motif comporte les variables suivantes :
entry_id
: si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page suivante. Sinon, la variable est ignorée.entry_title
: si le contexte le permet, cette variable contient le titre de la publication associée à la page suivante. Sinon, la variable est ignorée.page_number
: si le contexte le permet, cette variable contient le numéro de la page suivante. Sinon, la variable est ignorée.path
: contient le chemin relatif de la page suivante, si elle existe.chapter
: si le contexte le permet, contient l'index du chapitre de la page suivante. Sinon, la variable est ignorée..:GetPreviousPage::string:.
Permet de récupérer des informations sur la page précédente, si elle existe.
string
: le texte à formater, depuis lequel seront accessibles les valeurs des variables ci-dessous.Ce motif possède les variables suivantes :
entry_id
: si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page précédente. Sinon, la variable est ignorée.entry_title
: si le contexte le permet, cette variable contient le titre de la publication associée à la page précédente. Sinon, la variable est ignorée.page_number
: si le contexte le permet, cette variable contient le numéro de la page précédente. Sinon, la variable est ignorée.path
: contient le chemin relatif de la page précédente, si elle existe.chapter
: si le contexte le permet, contient l'index du chapitre de la page précédente. Sinon, la variable est ignorée..:GetRandomNumber::min_value::max_value::precision:.
Génère un nombre aléatoire compris entre min_value
et max_value
avec une précision décimale définie par precision
.
Par exemple, pour générer un nombre décimal compris entre zéro inclus et dix, avec au plus quatre chiffres après la virgule, nous pouvons utiliser :
.:GetRandomNumber::0::10::4:.
Pour générer un nombre entier compris entre zéro inclus et cent, nous pouvons utiliser :
.:GetRandomNumber::0::100::0:.
Enfin pour générer un nombre décimal, par exemple entre 12,25 inclus et 12,5, avec au plus 5 chiffres après la virgule, nous pouvons utiliser :
.:GetRandomNumber::12.25::12.5::5:.
.:GetRelativeLocation:.
Ce motif renvoie le chemin depuis la racine du blog vers le répertoire courant.
Par exemple, si la page courante qui est générée se trouve dans le répertoire :
blog/Categories/Cinema/Science-Fiction
Alors le motif renverra :
/Categories/Cinema/Science-Fiction
.:GetRelativeRoot:.
Ce motif renvoie le chemin relatif de la racine du blog.
Par exemple, si la page courante qui est générée se trouve dans le répertoire :
blog/Categories/Cinema/Science-Fiction :
Alors le motif renverra :
../../..
.:GetStyleSheets:.
VenC peut générer des feuilles de style CSS. Ces fichiers peuvent être inclus dans votre thème avec le motif GetStyleSheets
.
Par exemple, pour la documentation que vous êtes en train de lire, l'utilisation de ce motif produirait le code suivant :
<link rel="stylesheet" href="../venc_source_Text.css" type="text/css" /> <link rel="stylesheet" href="../venc_source_html.css" type="text/css" /> <link rel="stylesheet" href="../venc_source_HTML.css" type="text/css" /> <link rel="stylesheet" href="../venc_source_CSS.css" type="text/css" />
.:GetThreadName[::string1][::string2]:.
Ce motif permet de récupérer le nom du fil de publications courant.
Par exemple, si la page courante est générée dans un fil de publications
de type categorie
et que ladite catégorie s'appelle "Histoire de l'informatique",
alors GetThreadName
permet de récupérer cette valeur dans une chaîne de caractères
formatée correspondant à l'argument string1
. Si au contraire, le fil de publications
n'a pas de nom alors c'est string2
qui est renvoyée, par exemple quand VenC traite le fil de publications principal.
En fait, chaque fil de publications a un nom qui lui est attribué, sauf pour le fil de publications principal.
string1
: premier argument du motif, c'est celui qui est renvoyé si le fil de publications a un nom. Pour accéder au nom du fil de publications dans l'argument, il faut utiliser la variable value
. Si c'est cet argument qui doit être utilisé par le motif et qu'il est manquant, le motif renvoie simplement le nom du fil de publications, sans formatage particuler.string2
: second argument du motif, c'est celui qui est renvoyé si le fil de publications n'a pas de nom. Cet argument n'a pas de variable contextuelle. Si c'est cet argument qui doit être utilisé par le motif et qu'il est manquant, le motif est ignoré..:IfInArchives::string1[::string2]:.
La fonction teste si la page courante est générée dans le fil des archives.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.À noter que ce motif n'a pas de variable.
.:IfInCategories::string1[::string2]:.
La fonction teste si la page courante est générée dans le fil des catégories.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.À noter que ce motif n'a pas de variable.
.:IfInEntryID::id::string1[::string2]:.
La fonction teste si l'identifiant de la publication correspond à celui spécifié en argument.
id
: un nombre entier différent de 0 identifiant une publication.string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInFeed::string1[::string2]:.
Certains éléments contenus dans une publication ne peuvent pas être présents dans le flux RSS/Atom sous peine que celui-ci ne soit pas valide et ne s'affiche pas correctement dans les lecteurs de flux RSS/Atom.
Vous pouvez utiliser IfInFeed
pour remplacer un certain type de contenus par un autre, qui lui serait valide dans un flux RSS/Atom.
En outre, la fonction teste si le fil de publications courant est un flux RSS ou Atom.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInFirstPage::string1[::string2]:.
La fonction teste si le numéro de page courant correspond à la première page du fil de publications courant. Si la page est générée dans le contexte d'une page individuelle de publication ou d'un chapitre, le test échoue.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInLastPage::string1[::string2]:.
La fonction teste si le numéro de page courant correspond à la dernière page du fil de publications courant. Si la page est générée dans le contexte d'une page individuelle de publication ou d'un chapitre, le test échoue.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInMainThread::string1[::string2]:.
La fonction teste si la page courante est générée dans le fil de publications principal.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInThreadAndHasFeeds::string1[::string2]:.
La fonction teste si le fil de publications courant peut produire un flux Atom et/ou RSS. Seuls les catégories et le fil principal valident la condition.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfInThreadAndHasFeeds::string1[::string2]:.
La fonction teste si le fil de publications courant peut produire un flux Atom et/ou RSS. Seuls les catégories et le fil principal valident la condition.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:IfPages::string1[::string2]:.
La fonction teste si le fil de publications courant a plus d'une page.
string1
: texte retourné si la condition est remplie.string2
: texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.Ce motif n'a pas de variable.
.:PreviewIfInThreadElseContent:.
Ce pattern ne peut être utilisé que dans entry.html
.
Il renvoie le résumé de la publication courante si VenC génère la page dans un fil de publications. Sinon, VenC renvoie le contenu complet de la publication courante.
Les motifs non contextuels, par opposition à ceux présentés dans le chapitre 5.3, sont les premiers à être interprétés par VenC. La plupart d'entre eux permettent de récupérer des informations dites "sans état". Typiquement, ce type de motifs vous permet d'accéder aux métadonnées du blog ou de vos publications.
À noter également que ces motifs ont une portée, c'est-à-dire qu'ils ne peuvent pas tous être utilisés n'importe où.
Les chapitres qui suivent explicitent l'usage et le fonctionnement de ces motifs.
Ces motifs permettent d'accéder à des métadonnées contenues dans une publication. Ils ne peuvent donc pas être utilisés en dehors d'une publication ou des fichiers ci-dessous composant un thème :
.:CherryPickEntryMetadata::branch_1[::branch_2::branch_n]:.
Permet de récupérer le contenu de la métadonnée contenue dans un ou plusieurs dictionnaires. Pour ce faire, cette fonction prend au moins un paramètre qui désigne le nom d'un champ à la racine du document YAML d'une publication.
Par exemple :
.:CherryPickEntryMetadata::moo::foo::bar:.
Identique à CherryPickEntryMetadata
, mais est ignoré en cas
d'erreur.
.:ForEntryAuthors::string::separator:.
Retourne la liste des auteurs de la publication.
Le premier argument est une chaîne de caractères à formater avec les variables :
value
: contient le nom de l'auteur courant.html_id
: le nom de l'auteur courant, mais formaté pour être utilisé comme un identifiant HTML.Le second paramètre est une chaîne de caractères servant de séparateur.
.:ForEntryMetadata::metadata_name::string::separator:.
Il est possible de définir des métadonnées sous la forme de listes.
Le premier argument est une chaîne de caractères à formater avec les variables :
value
: contient l'élément courant de la liste.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.Le second paramètre est une chaîne de caractères servant de séparateur.
Si la métadonnée spécifiée dans metadata_name
n'existe pas, VenC interrompra la génération du site.
.:ForEntryMetadataIfExists::metadata_name::string::separator:.
Identique à ForEntryMetadata
, mais
est ignoré si la métadonnée spécifiée dans metadata_name
n'existe pas.
.:GetEntryArchivePath:.
Retourne le liens vers le groupe d'archives dans lequel se trouve la publication.
.:GetEntryCategoriesTree::open_node::open_branch::close_branch::close_node:.
Les catégories de la publication sont organisées sous la forme d'un arbre. Il est possible de récupérer l'arbre entier afin, typiquement, de générer un menu ou une liste de catégories et de sous-catégories.
Les arguments du motif sont les suivants :
open_node
: contient la chaîne de caractères d'ouverture pour la catégorie parente.open_branch
: contient la chaîne de caractères d'ouverture de la catégorie courante.close_branch
: contient la chaîne de caractères de fermeture de la catégorie courante.close_node
: contient la chaîne de caractères de fermeture de la catégorie parente.Les variables de ce motif sont les suivantes :
value
: le nom de la catégorie courante.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.path
: le chemin relatif de la catégorie courante.count
: le nombre de publications dans la catégorie courante.weight
: le nombre de publications dans la catégorie courante, divisé par le nombre de publications appartenant à une catégorie.childs
: contient le résultat de la récursion suivante du motif.Par exemple, pour créer un menu déroulant on peut utiliser le motif comme ci-dessous :
.:GetEntryCategoriesTree:: <ul>:: <li><a href="{path}" title="{count} publications">{value}</a>:: {childs}</li>:: </ul> :.
Si la publication était incluse dans les catégories suivantes :
categories: - Material: - Metal: - Copper - Steel - Science
Alors le motif générerait quelque chose comme le code HTML suivant :
<ul> <li> <a href="../Material/" title="1 publications">Material</a> <ul> <li> <a href="../Material/Metal/" title="1 publications">Metal</a> <ul> <li><a href="../Material/Metal/Copper/" title="1 publications">Copper</a></li> <li><a href="../Material-Metal/Steel/" title="1 publications">Steel</a></li> </ul> </li> </ul> </li> <li> <a href="../Science/" title="1 publications">Science</a> </li> </ul>
À la fin de chaque branche, si la catégorie courante possède une ou plusieurs
catégories filles, alors les arguments open_node
et close_node
sont ajoutés et
une nouvelle liste de sous-catégories est générée entre ces deux arguments,
en utilisant les arguments open_branch
et close_branch
.
Ce motif est ignoré et supprimé si la génération des catégories est désactivée dans le fichier de configuration principale.
.:GetEntryCategoriesTreeFromBranches:: branches:: sub_tree_separator:: open_node:: open_branch:: close_branch:: close_node :.
Fonctionne comme GetBlogCategoriesTreeFromBranches
mais
ne garde que les catégories où se trouve la publication courante.
.:GetEntryChapterLevel:.
Renvoie le niveau du chapitre de la publication.
Par exemple si la publication correspond au chapitre '1.2.3'
, alors le motif renverrait 3
:
chapter: '1.2.3'
Si la publication correspond au chapitre '4.5'
, alors le motif renverrait 2
:
chapter: '4.5'
.:GetEntryChapterPath:.
Renvoie le chemin relatif du chapitre correspondant à la publication courante.
.:GetEntryDate[::format]:.
Retourne la date de la publication formatée comme définie dans le fichier de configuration par le champ date_format
.
Il est possible d'utiliser un autre format de date à l'aide de l'argument optionnel format
.
Pour en savoir plus sur ce format, rendez-vous ici.
.:GetEntryDay:.
Retourne le jour de création de la publication.
.:GetEntryHour:.
Retourne l'heure de création de la publication.
.:GetEntryID:.
Retourne l'identifiant unique de la publication.
.:GetEntryMetadata::metadata_name:.
Il est possible de définir ses propres champs dans les métadonnées d'une publication ou d'un template.
Par exemple, si l'on définit le champ suivant :
free_hardware : Arduino Mega
Pour accéder à celui-ci, on utilisera le motif GetEntryMetadata
de la façon suivante :
.:GetEntryMetadata::free_hardware:.
Si la métadonnée ainsi référencée n'existe pas, VenC générera une erreur et stoppera la génération du site.
.:GetEntryMetadataIfExists::metadata_name[::string][::string2]:.
De façon similaire, il est possible d'essayer d'accéder à une métadonnée, sans garantie que celle-ci existe. Si la métadonnée existe, il est possible alors de formater du texte pour l'y inclure.
Les arguments de ce pattern sont au nombre de trois :
metadata_name
: le nom de la métadonnée désirée.string
: le texte formaté retourné si la condition est remplie. Optionnel. Si cet argument n'est pas présent, la fonction renvoie la valeur de la métadonnée sans formatage.string2
: le texte non formaté retourné si la condition n'est pas remplie. Si cet argument n'est pas présent, le pattern est ignoré.Il est possible d'utiliser la variable suivante dans l'argument string
pour formater le texte :
value
: contient la valeur de la métadonnée qu'on référence..:GetEntryMetadataIfNotNull::metadata_name[::string][::string2]:.
Identique à GetEntryMetadataIfExists
, mais la métadonnée spécifiée ne doit pas être vide ou être null
.
Par exemple:
<div id="entry.:GetEntryID:." .:GetEntryMetadataIfExists::alternate_style::class="{value}":. >
Si la métadonnée référencée n'est pas définie, si elle est vide ou null
, VenC retourne string2
(si cette chaîne est définie), sinon le motif est ignoré.
Si le second argument n'est pas défini, l'accesseur renvoie directement la variable référencée, si le test réussit.
.:GetEntryMetadataTree:: metadata_name:: open_node:: open_branch:: value_childs:: value:: close_branch:: close_node :.
Ce pattern permet de formater sous la forme d'un arbre une métadonnée d'une publication qui serait une structure de données.
Les arguments de ce motif sont les suivants :
metadata_name
: le nom de la métadonnée à laquelle on souhaite accéder. Si elle n'existe pas, VenC lève une exception.open_node
: la chaîne de caractères ouvrant la liste courante.open_branch
: la chaîne de caractères ouvrant l'item courant.value_childs
: la chaîne de caractères composant l'item courant, si celui-ci a des items enfants.value
: la chaîne de caractères composant l'item courant, si celui-ci n'a pas d'item enfant.close_branch
: la chaîne de caractères fermant l'item courant.clode_node
: la chaîne de caractères fermant la liste courante.Ce motif possède les variables suivantes :
value
: contient la valeur de l'item courant. Vous pouvez utiliser cette variable dans les arguments value
et value_childs
.html_id
: le nom de la métadonnée courante, mais formaté pour être utilisé comme un identifiant HTML.childs
: contient le bloc enfant de l'item courant. Vous ne pouvez utiliser cette variable que dans l'argument value_childs
.Voici un exemple d'utilisation de ce pattern. Étant donné la métadonnée suivante dans l'entête d'une publication :
tree_test: - a: - b: - c - d - e: - f - g
Si l'on veut afficher tree_test
sous la forme de listes imbriquées on pourrait utiliser le motif comme suit :
.:GetEntryMetadataTree:: tree_test:: <ul>:: <li>:: {value} {childs}:: {value}:: </li>:: </ul> :.
Ce qui donnerait :
.:GetEntryMetadataTreeIfExists:: metadata_name:: open_node:: open_branch:: value_childs:: value:: close_branch:: close_node :.
Identique à GetEntryMetadataTree
, mais le pattern
est ignoré si la métadonnée indiquée n'existe pas.
.:GetEntryMinute:.
Retourne la minute de création de la publication.
.:GetEntryMonth:.
Retourne le mois de création de la publication.
.:GetEntryPath:.
Retourne le chemin relatif de la publication si VenC est configuré pour générer une page par publication. Sinon, le motif est ignoré et supprimé.
.:GetEntryTitle:.
Retourne le titre de la publication.
.:GetEntryToC::open_ul::open_li::content::close_li::close_ul:.
Ce motif permet de générer une table des matières multiniveaux sur la base des titres présents dans le corps d'une publication Markdown.
open_ul
: la chaîne de caractères ouvrant le niveau courant.open_li
: la chaîne de caractères ouvrant l'item courant.content
: la chaîne de caractères composant l'item courant, dans laquelle vous pouvez utiliser les variables du motif.close_li
: la chaîne de caractères fermant l'item courant.clode_ul
: la chaîne de caractères fermant le niveau courant.Le motif a quelques variables qu'il est possible d'utiliser dans l'argument content
:
id
: contient l'id
HTML de l'entête correspondant à l'item courant.title
: contient le titre de l'entête correspondant à l'item courant.level
: contient le niveau de l'entête correspondant à l'item courant.Un usage classique ressemblerait à quelque chose comme :
.:GetEntryToC:: <ul>:: <li>:: <a href="#{id}" class="toc_level_{level}">{title}</a>:: </li>:: </ul> :.
Si dans la publication on trouvait les titres suivants :
# Title 1 ## Title 1.1 ### Title 1.1.1 ## Title 1.2
Alors le code HTML généré ressemblerait à :
<ul> <li> <a href="#title-1" class="toc_level_1">Title 1</a> <ul> <li> <a href="#title-1-1" class="toc_level_2">Title 1.1</a> <ul> <li> <a href="#title-1-1-1" class="toc_level_3">Title 1.1.1</a> </li> </ul> </li> <li> <a href="#title-1-2" class="toc_level_2">Title 1.2</a> </li> </ul> </li> </ul>
Ce qui donne :
Quelques remarques :
</p>
et <p>
, respectivement au début et à la fin du texte de sortie.entry.html
ou bien directement dans votre publication..:GetEntryYear:.
Retourne l'année de création de la publication.
.:GetFlattenedEntryCategories::string::separator:.
Permet de récupérer sous la forme d'une liste chaque item de l'arbre des catégories d'une publication.
Si la génération des fils de publications triés par catégorie est désactivée, ce motif est ignoré.
Les arguments de ce motif sont :
string
: la chaîne de caractères correspondant à l'item courant.separator
: la chaîne de caractères qui sert de séparateur entre chaque item.Dans l'argument string
vous pouvez utiliser les variables suivantes :
value
: le nom de la catégorie courante.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.count
: le nombre de publications dans cette catégorie.weight
: le nombre de publications dans cette catégorie, divisé par le nombre de publications ayant une catégorie.path
: le chemin relatif menant au fil de publication de la catégorie courante..:GetFlattenedBlogCategoriesFromBranches:: branches:: sub_tree_string:: sub_tree_separator:: string:: separator :.
Identique à GetFlattenedBlogCategoriesFromBranches
mais ne récupère que les catégories de la publication courante.
.:IfEntryMetadataIsTrue::metadata_name::if_true[::if_false]:.
Permet d'afficher un texte ou un autre selon que la métadonnée indiquée est vraie ou fausse.
Ce motif possède les arguments suivants :
metadata_name
: le nom de la métadonnée qu'on teste. Le test de vérité est pythonic, c'est-à-dire que pour échouer la métadonnée ne doit pas exister ou doit être explicitement le booléen False
.if_true
: le texte à retourner si le test réussit.if_false
: optionnel. Le texte à retourner si le test échoue.Ces motifs sont globaux, donc utilisables partout. Comme pour les motifs de publications, ce sont les premiers à être interprétés par VenC. Contrairement aux motifs contextuels, ceux-là sont exécutés une et une seule fois.
.:CherryPickBlogMetadata::branch_1[::branch_2::branch_n]:.
Permet de récupérer le contenu de la métadonnée contenu dans un ou plusieurs dictionnaires. Pour ce faire, cette fonction prend au moins un paramètre qui désigne le nom d'un champ à la racine du fichier de configuration principale.
Par exemple :
.:CherryPickBlogMetadata::paths::rss_file_name:.
Identique à CherryPickBlogMetadata
, mais est ignoré en cas
d'erreur.
.:ForBlogArchives::string::separator:.
Ce motif permet de récupérer la liste des périodes archivées.
Le format de la période est défini dans le fichier de configuration
principal par archives_directory_name
.
string
: le premier argument contient le texte à formater pour chaque élément de la liste de période.separator
: le second argument contient le texte utilisé comme séparateur.Les variables de la fonction sont les suivantes :
value
: la période courante, telle que définie par archives_directory_name
dans le fichier de configuration principal du blog.html_id
: le nom de l'archive courante, mais formaté pour être utilisé comme un identifiant HTML.path
: le chemin relatif la période archivée.count
: le nombre de publications dans la période courante.weight
: le nombre de publications dans la période courante, divisé par le nombre maximal de publications par période.Si la génération des archives est désactivée, le motif est ignoré et supprimé.
.:ForBlogMetadata::metadata_name::string[::separator]:.
Ce motif permet de récupérer une métadonnée de type liste présente dans
blog_configuration.yml
. Ce motif
a trois arguments :
metadata_name
: le nom de la métadonnée que l'on souhaite récupérer. Si la métadonnée n'existe pas, VenC s'arrête avec un message d'erreur.string
: le second argument contient le texte à formater pour chaque élément de la liste.separator
: le troisième argument, optionnel, contient le texte utilisé comme séparateur pour chaque item.Vous pouvez utiliser la variable suivante dans l'argument string
:
value
: contient la valeur de l'item courant.html_id
: le nom de la métadonnée courante, mais formaté pour être utilisé comme un identifiant HTML..:ForBlogMetadataIfExists::metadata_name::string[::separator]:.
Identique à ForBlogMetadata
, mais
si la métadonnée demandée n'existe pas, le motif est ignoré.
.:ForEntriesSet::entries_subset_key::string:.
Ce motif permet d'itérer sur un sous-ensemble de publications et d'en afficher les attributs.
Il y a deux arguments :
entries_subset_key
: il s'agit de la clé correspondant au sous-ensemble de publications retourné par RangeEntriesByID
.string
: la chaîne de caractères à formater comportant les variables référençant les attributs de la publication courante.Les variables pouvant être utilisées sont par défaut :
id
: l'identifiant de la publication courante.title
: le titre de la publication courante.path
: le chemin relatif vers la publication courante.archive_path
: le chemin relatif vers le groupe d'archives de la publication courante.chapter_path
: le chemin relatif vers le chapitre correspondant à la publication courante. Si la génération de chapitre est désactivée, la variable est ignorée.Il est également possible d'accéder à n'importe quelle métadonnée définie par l'utilisateur dans une publication. Si la métadonnée n'existe pas le nom de la variable est simplement ignoré.
.:GetAuthorDescription:.
Retourne la description de l'auteur du blog définie dans author_description
.
Si la métadonnée est absente, le motif est ignoré.
.:GetAuthorEmail:.
Retourne l'adresse email de l'auteur du blog définie dans author_email
.
Si la métadonnée est absente, le motif est ignoré.
.:GetAuthorName:.
Retourne le nom de l'auteur du blog définie dans author_name
.
Si la métadonnée est absente, le motif est ignoré.
.:GetBlogCategoriesTree::open_node::open_branch::close_branch::close_node:.
Les catégories du blog sont organisées sous la forme d'un arbre. Il est possible de récupérer l'arbre entier afin, typiquement, de générer un menu ou une liste de catégories et de sous-catégories.
Les arguments du motif sont les suivants :
open_node
: contient la chaîne de caractères d'ouverture pour la catégorie parente.open_branch
: contient la chaîne de caractères d'ouverture de la catégorie courante.close_branch
: contient la chaîne de caractères de fermeture de la catégorie courante.close_node
: contient la chaîne de caractères de fermeture de la catégorie parente.Les variables de ce motif sont les suivantes :
value
: le nom de la catégorie courante.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.path
: le chemin relatif de la catégorie courante.count
: le nombre de publications dans la catégorie courante.weight
: le nombre de publications dans la catégorie courante, divisé par le nombre de publications appartenant à une catégorie.childs
: contient le résultat de la récursion suivante du motif.Par exemple, pour créer un menu déroulant on peut utiliser le motif comme ci-dessous :
.:GetBlogCategoriesTree:: <ul>:: <li><a href="{path}" title="{count} publications">{value}</a>:: {childs}</li>:: </ul> :.
Avec l'arbre de toutes les catégories du blog ci-dessous :
- Material: - Metal: - Copper - Steel - Science
Le motif générerait quelque chose comme le code HTML suivant :
<ul> <li> <a href="../Material/" title="5 publications">Material</a> <ul> <li> <a href="../Material/Metal/" title="5 publications">Metal</a> <ul> <li><a href="../Material/Metal/Copper/" title="4 publications">Copper</a></li> <li><a href="../Material-Metal/Steel/" title="1 publications">Steel</a></li> </ul> </li> </ul> </li> <li> <a href="../Science/" title="3 publications">Science</a> </li> </ul>
À la fin de chaque branche, si la catégorie courante possède une ou plusieurs
catégories filles, alors les arguments open_node
et close_node
sont ajoutés et
une nouvelle liste de sous-catégories est générée entre ces deux arguments,
en utilisant les arguments open_branch
et close_branch
.
Ce motif est ignoré et supprimé si la génération des catégories est désactivée dans le fichier de configuration principale.
.:GetBlogCategoriesTreeFromBranches:: branches:: sub_tree_string:: separator:: open_node:: open_branch:: close_branch:: close_node :.
Ce motif permet de mettre en œuvre la taxonomie avancée. En effet, via le premier argument branches
, ce motif permet de sélectionner une ou plusieurs branches
de l'arbre des catégories pour l'afficher individuellement à l'intérieur de sub_tree_string
comme le ferait GetBlogCategoriesTree
.
Les arguments du motif sont les suivants :
branches
: contient le nom de la métadonnée définie dans le fichier de configuration
, qui elle même contient une liste de noms de branches. Ces noms de branches correspondent à des items à la racine de l'arbre des catégories.sub_tree_string
: contient la chaîne de caractères contenant la branche courante.separator
: contient la chaîne de caractères de séparation. Chaque itération de la branche courante est jointe avec le contenu de separator
.open_node
: contient la chaîne de caractères d'ouverture pour la catégorie parente.open_branch
: contient la chaîne de caractères d'ouverture de la catégorie courante.close_branch
: contient la chaîne de caractères de fermeture de la catégorie courante.close_node
: contient la chaîne de caractères de fermeture de la catégorie parente.Les variables de ce motif sont les suivantes :
value
: le nom de la catégorie courante.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.path
: le chemin relatif de la catégorie courante.count
: le nombre de publications dans la catégorie courante.weight
: le nombre de publications dans la catégorie courante, divisé par le nombre de publications appartenant à une catégorie.childs
: contient le résultat de la récursion suivante ou de l'itération courante du motif
.Pour illustrer ce motif un peu complexe, nous nous donnons pour exemple l'arbre de toutes les catégories d'un blog imaginaire :
- Medium & Technique: - Dessin - Peintures: - Acrylique - Huile - Sculpture - Infographie - Licence : - CC-By-SA - CC-By-NC-ND
Nous pourrions vouloir un contrôle plus fin sur l'affichage de ces catégories. Par exemple en mettant en valeur Medium & Technique
et Licence
, qui
renseignent sur le type de catégories concerné.
.:GetBlogCategoriesTreeFromBranches::my_taxonomy:: <div class="__VENC_TREE_ROOT__"> <p class="title"><a href="{path}">{value}</a></p> {childs} </div> ::<hr> ::<ul class="__VENC_TREE_NODE__"> ::<li><a class="engrave" href="{path}" title="{count} entries">{value}</a> ::{childs}</li> ::</ul>:.
Ici, dans l'exemple, le nom de la métadonnée extraite du fichier de configuration
du blog est my_taxonomy
. Pour fonctionner
la métadonnée serait alors définie comme ci-dessous :
my_taxonomy: - Medium & Technique - Licence
Ce faisant GetBlogCategoriesTreeFromBranches
va se comporter pour chaque item comme le ferait GetBlogCategoriesTree
, en prenant pour racine l'item correspondant
au nom de la branche courante.
L'utilisation du motif comme dans l'exemple donnerait quelque chose comme :
<div class="__VENC_TREE_ROOT__"> <p class="title"> <a class="engrave" href="../Medium-&-Technique">Medium & Technique</a> </p> <ul class="__VENC_TREE_NODE__"> <li> <a class="engrave" href="../Medium-&-Technique/Dessin" title="1 entries">Dessin</a> </li> <li> <a class="engrave" href="../Medium-&-Technique/Infographie" title="1 entries">Infographie</a> </li> <li> <a class="engrave" href="../Medium-&-Technique/Peintures" title="1 entries">Peintures</a> <ul class="__VENC_TREE_NODE__"> <li> <a class="engrave" href="../Medium-&-Technique/Peintures/Acrylique" title="1 entries">Acrylique</a> </li> <li> <a class="engrave" href="../Medium-&-Technique/Peintures/Huile" title="1 entries">Huile</a> </li> </ul> </li> <li> <a class="engrave" href="../Medium-&-Technique/Sculpture" title="1 entries">Sculpture</a> </li> </ul> </div> <hr> <div class="__VENC_TREE_ROOT__"> <p class="title"><a class="engrave" href="../Licence">Licence</a></p> <ul class="__VENC_TREE_NODE__"> <li> <a class="engrave" href="../Licence/CC-By-NC-ND" title="1 entries">CC-By-NC-ND</a> </li> <li> <a class="engrave" href="../Licence/CC-By-SA" title="1 entries">CC-By-SA</a> </li> </ul> </div>
On peut faire remarquer qu'il est possible de définir dans votre fichier de configuration
plusieurs
listes de branches. Ainsi vous pouvez utiliser GetBlogCategoriesTreeFromBranches
à différent endroit de votre template graphique avec des valeurs
différentes pour l'argument branches
.
Note importante : GetBlogCategoriesTreeFromBranches
ne peut sélectionner que des branches à la racine de l'arbre des catégories.
.:GetBlogDescription:.
Retourne la description du blog définie dans blog_description
.
Si la métadonnée est absente, le motif est ignoré.
.:GetBlogLanguage:.
Retourne la langue du blog définie dans blog_language
.
Si la métadonnée est absente, le motif est ignoré.
.:GetBlogLicense:.
Retourne la licence appliquée au contenu du blog définie dans license
.
Si la métadonnée est absente, le motif est ignoré.
.:GetBlogMetadata::metadata_name:.
Vous pouvez également définir vos propres métadonnées en rajoutant des champs au fichier de configuration
blog_configuration.yaml
. Par exemple, en ajoutant la
ligne suivante dans le fichier de configuration :
Banner: 'maBanniere.jpg'
Vous pourrez ensuite récupérer la valeur de Banner
avec :
.:GetBlogMetadata::Banner:.
Comme pour GetEntryMetadata
, si la métadonnée référencée n'existe pas, VenC générera une erreur et vous en indiquera l'origine.
.:GetBlogMetadataIfExists::metadata_name[::string][::string2]:.
De façon similaire, il est possible d'essayer d'accéder à une métadonnée, sans garantie que celle-ci existe. Si la métadonnée existe, il est possible alors de formater du texte pour l'y inclure.
Les arguments de ce pattern sont au nombre de trois :
metadata_name
: le nom de la métadonnée désirée.string
: le texte formaté retourné si la condition est remplie. Optionnel. Si cet argument n'est pas présent, la fonction renvoie la valeur de la métadonnée sans formatage.string2
: le texte non formaté retourné si la condition n'est pas remplie. Si cet argument n'est pas présent, le pattern est ignoré.Le formatage du texte se fait en utilisant une variable propre à l'argument string
:
value
: la valeur de la métadonnée qu'on référence..:GetBlogMetadataIfNotNull::metadata_name[::string][::string2]:.
Identique à GetBlogMetadataIfExists
, mais la métadonnée spécifiée ne doit pas être vide pour que le test réussisse.
.:GetBlogMetadataIfExists::mastodon:: <a href="{value}" class="social-network-item"> <img src=".:GetRelativeRoot:.mastodon.png" alt="Mastodon" title="Mastodon"/> </a> :.
Dans cet exemple, on suppose que l'image de l'icône du réseau social se trouve à la
racine du blog, on a donc besoin de préciser son chemin relatif avec GetRelativeRoot
.
Si la variable référencée n'est pas définie, VenC ignore le motif et utilise à la place le bloc HTML passé en second argument.
Si le second argument n'est pas défini, le motif renvoie directement la variable référencée si elle existe et si elle n'est pas vide.
.:GetBlogMetadataTree:: metadata_name:: open_node:: open_branch:: value_childs:: value:: close_branch:: close_node :.
Ce pattern permet de formater sous la forme d'un arbre une métadonnée de blog qui serait une structure de données.
Les arguments de ce motif sont les suivants :
metadata_name
: le nom de la métadonnée auquel on souhaite accéder. Si elle n'existe pas, VenC lève une exception.open_node
: la chaîne de caractères ouvrant la liste courante.open_branch
: la chaîne de caractères ouvrant l'item courant.value_childs
: la chaîne de caractères composant l'item courant si celui-ci a des items enfants.value
: la chaîne de caractères composant l'item courant si celui-ci n'a pas d'items enfants.close_branch
: la chaîne de caractères fermant l'item courant.clode_node
: la chaîne de caractères fermant la liste courante.Ce motif possède les variables suivantes :
value
: contient la valeur de l'item courant. Vous pouvez utiliser cette variable dans les arguments value
et value_childs
.html_id
: le nom de la métadonnée courante, mais formaté pour être utilisé comme un identifiant HTML.childs
: contient le bloc enfant de l'item courant. Vous ne pouvez utiliser cette variable que dans l'argument value_childs
.Un exemple d'utilisation de ce pattern ci-dessous. Étant donné la métadonnée de publication suivante :
tree_test: - a: - b: - c - d - e: - f - g
Si l'on veut afficher tree_test
sous la forme de listes imbriquées on pourrait utiliser le motif comme suit :
.:GetEntryMetadataTree:: tree_test:: <ul>:: <li>:: {value} {childs}:: {value}:: </li>:: </ul> :.
Ce qui donnerait :
.:GetBlogMetadataTreeIfExists:: metadata_name:: open_node:: open_branch:: value_childs:: value:: close_branch:: close_node :.
Identique à GetBlogMetadataTree
, mais le pattern est ignoré si la métadonnée indiquée n'existe pas.
.:GetBlogName:.
Retourne le titre du blog défini dans blog_name
.
.:GetBlogURL:.
Retourne l'URL du blog définie dans blog_url
. Le pattern est ignoré si blog_url
n'est pas définit dans le fichier de configuration.
.:GetChapterAttributeByIndex::attribute_name::index_value:.
Ce motif permet de récupérer les propriétés d'un chapitre en spécifiant l'index de celui-ci.
Les arguments sont :
attribute_name
: le nom de la propriété du chapitre. Les noms de propriétés valides sont :
entry_id
: l'id
de la publication correspondant au chapitre spécifié dans index_value
.path
: le chemin relatif du chapitre spécifié dans index_value
.title
: le titre de la publication correspondant au chapitre spécifié dans index_value
.index_value
: la valeur de l'index du chapitre..:GetChapters::list_open::item_open::item_close::list_close:.
Ce motif permet de récupérer l'arborescence des chapitres du blog. En effet, VenC permet d'organiser votre contenu comme le serait un livre ou un e-book. La présente documentation est d'ailleurs faite ainsi.
Le motif a les mêmes arguments que GetEntryCategoriesTree
et GetBlogCategoriesTree
:
list_open
: contient la chaîne de caractères d'ouverture du chapitre parent.item_open
: contient la chaîne de caractères d'ouverture du chapitre courant.item_close
: contient la chaîne de caractères de fermeture du chapitre courant.list_close
: contient la chaîne de caractères de fermeture du chapitre parent.Les variables contextuelles de la fonction sont les suivantes :
index
: la valeur de la numérotation du chapitre courant. Par exemple : '3.2'
, '4.2.1'
ou bien '2'
.level
: le niveau du chapitre courant. Par exemple :
'2'
aurait le niveau 0.'3.2'
aurait le niveau 1.'4.2.1'
aurait le niveau 2.title
: le titre du chapitre courant.html_id
: le titre du chapitre courant, mais formaté pour être utilisé comme un identifiant HTML.path
: le chemin relatif du chapitre courant.Une utilisation typique du motif serait :
.:Chapters:: <ul class="chapter-level{level}">:: <li>{index}. <a href="{path}">{title}</a>:: </li>:: </ul> :.
La fonction générera alors le code HTML ci-dessous :
<ul class="chapter-level0"> <li> 1. <a href="../Premier-Chapitre">Premier Chapitre</a> </li> <li> 2. <a href="../Second-Chapitre">Second Chapitre</a> </li> <li> 3. <a href="../Troisième-Chapitre">Troisième Chapitre</a> <ul class="chapter-level1"> <li> 3. <a href="../Premier-Sous-Chapitre-du-Troisième Chapitre">Premier Sous-Chapitre du Troisième Chapitre</a> </li> </ul> </ul>
Si la génération des chapitres est désactivée dans le fichier de configuration principal, le motif est ignoré et supprimé.
.:GetEntryAttributeByID::attribute::identifier:.
Ce motif permet de récupérer n'importe quelle métadonnée d'une publication, en renseignant l'identifiant de la publication et le nom de la métadonnée désirée.
Les arguments du motif sont :
attribute
: le nom de la métadonnée de la publication.identifier
: un nombre entier identifiant la publication ciblée.Ce pattern permet de récupérer, en supplément des métadonnées définies dans l'entête YAML de la publication,
le chemin relatif de celle-ci avec path
. Par exemple, pour obtenir le chemin relatif de la publication dont l'identifiant est 1337 :
.:GetEntryAttributeByID::path::1337:.
.:GetFlattenedBlogCategories::string::separator:.
Permet de récupérer sous la forme d'une liste chaque item de l'arbre des catégories du blog.
Si la génération des fils de publications triés par catégories est désactivée, ce motif est ignoré.
Les arguments de ce motif sont :
string
: la chaîne de caractères correspondant à l'item courant.separator
: la chaîne de caractères qui sert de séparateur entre chaque item.Dans l'argument string
vous pouvez utiliser les variables suivantes :
value
: le nom de la catégorie courante.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.count
: le nombre de publications dans cette catégorie.weight
: le nombre de publications dans cette catégorie, divisé par le nombre de publications ayant une catégorie.path
: le chemin relatif menant au fil de publications de la catégorie courante..:GetFlattenedBlogCategoriesFromBranches:: branches:: sub_tree_string:: sub_tree_separator:: string:: separator :.
branches
: contient le nom de la métadonnée définie dans le fichier de configuration, qui elle-même contient une liste de noms de branche. Ces noms de branche correspondent à des items à la racine de l'arbre des catégories.sub_tree_string
: contient la chaîne de caractères contenant la branche courante.sub_tree_separator
: contient la chaîne de caractères de séparation. Chaque itération de la branche courante est jointe avec le contenu desub_tree_separator
.string
: la chaîne de caractères correspondant à l'item courant de la branche courante.separator
: la chaîne de caractères qui sert de séparateur entre chaque item.Vous pouvez utiliser les variables suivantes dans sub_tree_string
et string
value
: le nom de la catégorie courante dans string
et le nom de la branche courante dans sub_tree_string
.html_id
: le nom de la catégorie courante, mais formaté pour être utilisé comme un identifiant HTML.count
: le nombre de publications dans cette catégorie.weight
: le nombre de publications dans cette catégorie, divisé par le nombre de publications ayant une catégorie.path
: le chemin relatif menant au fil de publications de la catégorie courante.childs
: fonctionne uniquement dans sub_tree_string
. Cette variable contient le contenu de la branche courante formaté dans string
.Cette fonction combine le concept de GetBlogCategoriesTreeFromBranches
et de GetFlattenedBlogCategories
. C'est-à-dire
que les trois premiers arguments servent à exactement la même chose que dans GetBlogCategoriesTreeFromBranches
. Les autres arguments sont identiques à
ceux dans GetFlattenedBlogCategories
. En d'autres termes, ce motif permet de sélectionner une ou plusieurs branches de l'arbre des catégories et de construire
un nuage de catégories à partir de ces branches.
.:GetRootPage:.
Ce motif renvoie le chemin relatif vers la page principale du blog qui
correspond généralement au fichier index.html
et qui devrait se trouver
à la racine de votre site.
.:GetGenerationTimestamp::time_format:.
Ce motif renvoie la date formatée correspondant au moment où la page courante a été générée, quand VenC exporte votre site, par exemple avec :
venc -xb
Le seul paramètre de ce motif est :
time_format
: la chaîne de caractères permettant de formater la date courante. Le format utilisé est le même que celui utilisé par Python. La documentation est disponible ici..:IfAtomEnabled::string1[::string2]:.
La fonction teste si VenC est configuré pour générer un flux Atom.
string1
: texte retourné si la condition est remplie.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:IfBlogMetadataIsTrue::metadata_name::if_true[::if_false]:.
Permet d'afficher un texte ou un autre selon que la métadonnée indiquée est vraie ou fausse.
Ce motif possède les arguments suivant :
metadata_name
: le nom de la métadonnée qu'on teste. Le test de vérité est pythonic, c'est-à-dire que pour échouer la métadonnée ne doit pas exister ou doit être explicitement le booléen False
.if_true
: le texte à retourner si le test réussi.if_false
: optionnel. Le texte à retourner si le test échoue..:IfCategories::string1[::string2]:.
La fonction teste si des catégories existent et si la génération des pages de celles-ci est bien activée dans le fichier de configuration principale.
string1
: texte retourné si la condition est remplie.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:IfChapters::string1[::string2]:.
La fonction teste si des chapitres existent et si la génération des pages de ceux-là est bien activée dans le fichier de configuration principale.
string1
: texte retourné si la condition est remplie.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:IfFeedsEnabled::string1[::string2]:.
La fonction teste si VenC est configuré pour générer un flux RSS et/ou un flux Atom.
string1
: texte retourné si la condition est remplie.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:IfInfiniteScrollEnabled::string1[::string2]:.
Permet de tester si l'option disable_infinite_scroll
est définie dans le fichier de configuration principale et, si c'est le cas, quelle en est la valeur booléenne.
string1
: texte retourné si la variable testée vaut True
.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:IfRSSEnabled::string1[::string2]:.
La fonction teste si VenC est configuré pour générer un flux RSS.
string1
: texte retourné si la condition est remplie.string2
: optionnel. Texte retourné si la condition est fausse, et si en plus string2
n'est pas défini, le motif est ignoré et supprimé..:RangeEntriesByID::begin_at::end_at:.
Retourne la clé correspond à une liste de publications sélectionnées à partir de l'identifiant
begin_at
et allant dans l'ordre jusqu'à end_at
.
Si end_at
est plus petit que begin_at
alors la liste des publications associées à la clé est triée
dans l'ordre décroissant.
Ce motif seul ne sert à rien. Il doit être utilisé
conjointement avec ForEntriesSet
Par exemple pour accéder aux publications d'identifiants 4 à 8, vous pouvez utiliser :
.:ForEntriesSet:: .:RangeEntriesByID::4::8:. ::{title}:.
Ces motifs n'ont pas vocation à récupérer ou mettre en forme des informations propres à votre projet. Il s'agit plutôt de fonctionnalités avancées pour de la mise en page spécifique, ou l'utilisation d'API ou de fonctionnalités tierces. Par exemple, pour la coloration syntaxique ou pour incorporer du contenu embarqué.
Comme pour les motifs de blog, les motifs divers sont sans état et sont exécutés une et une seule fois au moment où VenC les lit.
.:Audio::source::extensions:.
Ce motif permet d'inclure un fichier audio dans la page. Pour ce faire, le fichier audio.html
faisant partie du thème est formaté avec les paramètres passés au motif :
source
: il s'agit de l'URL ou du chemin du fichier audio. Il peut s'agir d'un chemin absolu ou
relatif. S'il s'agit d'un chemin relatif, vous pouvez utiliser le motif
GetRelativeRoot
.
Attention, l'URL ou le chemin passé en paramètre ne doit pas contenir l'extension du fichier.extensions
: pour assurer la compatibilité de votre contenu avec
les différents navigateurs du marché, il est recommandé d'avoir plusieurs
sources du même fichier audio en différents formats. Ce paramètre est donc
une liste des extensions disponibles. Les éléments de la liste sont séparés par une virgule.<audio controls style="width: 100%;"> {source} Your browser does not support the audio element. </audio>
Ce qui est important ici, c'est la variable Python source
que VenC remplace par autant de balises <source>
que nécessaire pour épuiser la liste des différents formats du fichier audio courant.
.:Audio::http://www.nyan.cat/music/original::mp3,ogg:.
On voit ici que le fichier audio est disponible en deux formats :
mp3
ogg
Il y a donc deux fichiers :
original.mp3
original.ogg
Se trouvant à l'adresse "http://www.nyan.cat/music/".
Finalement, on obtient le résultat suivant :
<audio controls style="width: 100%;"> <source src="http://www.nyan.cat/music/original.mp3" type="audio/mp3"> <source src="http://www.nyan.cat/music/original.ogg" type="audio/ogg"> Your browser does not support the audio element. </audio>
.:CodeHightlight::language::display_line_numbers::input_code:.
VenC permet de formater du code source pour qu'il soit plus lisible et
agréable à lire dans vos articles. Cette fonctionnalité dépend de la
librairie tierce Pygments
.
Ce motif prend trois arguments :
language
: indique le langage du texte d'entrée. La liste des langages
supportés par Pygments est disponible ici.
Si vous ne souhaitez pas coloriser le texte d'entrée, utilisez la valeur Text
.display_line_numbers
: il s'agit d'un booléen indiquant à VenC si vous
souhaitez générer le numéro des lignes dans le rendu.input_code
: le code source que vous souhaitez formater.Par exemple, l'utilisation ci-dessous du motif :
.:CodeHighlight::C::False:: #include <stdio.h> int main(int argc, char ** argv) { printf("Hello VenC user!\n"); return 0; }:.
Générerait le code HTML suivant :
<div class="__VENC_PYGMENTIZE_WRAPPER__"> <div class="venc_source_C"> <pre> <span></span> <span class="cp">#include</span> <span class="cpf"><stdio.h></span> <span class="cp"></span> <span class="kt">int</span> <span class="nf">main</span> <span class="p">(</span> <span class="kt">int</span> <span class="n">argc</span> <span class="p">,</span> <span class="kt">char</span> <span class="o">**</span> <span class="n">argv</span> <span class="p">)</span> <span class="p">{</span> <span class="n">printf</span> <span class="p">(</span> <span class="s">"Hello VenC user!</span> <span class="se">\n</span> <span class="s">"</span> <span class="p">);</span> <span class="k">return</span> <span class="mi">0</span> <span class="p">;</span> <span class="p">}</span> </pre> </div> </div>
Qui rend ensuite à l'écran ce résultat :
#include <stdio.h> int main(int argc, char ** argv) { printf("Hello VenC user!\n"); return 0; }
Le style CSS du code source ainsi formaté est généré automatiquement
par VenC dans un fichier et est placé dans le répertoire "extra
" de
votre projet. Ces fichiers doivent être explicitement inclus dans votre
page à l'aide du motif GetStyleSheets
.
Dans l'exemple précédent, le fichier CSS créé serait le suivant :
venc_source_C.css
Pour adapter le style du formatage à votre mise en page, vous pouvez définir un style appliqué aux éléments enfants de la balise :
<div class="__VENC_PYGMENTIZE_WRAPPER__"></div>
Par exemple pour la documentation que vous êtes en train de lire, le style CSS suivant est appliqué :
blockquote, pre { background-color: #202020; margin: 0px; border-radius: 3px; padding: 3px; padding-left: 10px; padding-right: 10px; color: #808080; overflow-x: scroll; }
Il est important que le style ainsi défini soit inclus dans header.html
après utilisation du motif
GetStyleSheets
.
En effet, le nouveau style écrasera le précédent s'il est placé après. Par exemple :
.:GetStyleSheets:. <link rel="stylesheet" href="../cheat_sheet.css" type="text/css">
Enfin, il est possible de changer le thème par défaut utilisé par le module Pygments
avec
l'option pygmentize_style
.
En effet, le nouveau style écrasera le précédent s'il est placé après. Par exemple :
.:GetStyleSheets:. <link rel="stylesheet" href="../cheat_sheet.css" type="text/css">
.:CodeHightlightInclude::language::display_line_numbers::filename:.
Ce motif fonctionne exactement comme le précédent motif CodeHighlight
,
à la différence que le dernier argument ne contient pas de code source
mais le nom de fichier dans lequel se trouve celui-ci. Ce fichier source
doit être placé dans le répertoire includes
de votre projet.
Ce motif est donc à préférer au précédent quand le code source est très long, et que vous ne souhaitez pas "polluer" votre publication avec du code.
Notons que tout ce qui se trouve à l'intérieur du fichier ainsi inclus n'est pas traité par le moteur de motifs de VenC.
.:DisableMarkup::content:.
Ce motif permet d'empêcher l'interpréteur de langage de balisage de traiter le texte passé en paramètre. Attention cependant, VenC y reconnaît toujours ses propres motifs.
Ce motif ne prend qu'un seul paramètre.
content
: le texte pour lequel on veut désactiver l'interpréteur de langage de balisage..:Escape::content:.
Identique à DisableMarkup
,
mais permet d'ignorer également les motifs contenus à l'intérieur du texte de
l'unique argument content
.
.:GetEmbedContent::content_url:.
Ce motif permet de récupérer du contenu embarqué via le protocole oEmbed. Typiquement, cela vous permet d'importer un lecteur Youtube ou SoundCloud dans votre publication.
Le seul argument de ce motif est :
content_url
: il s'agit de l'URL de la ressource embarquée que vous voulez inclure.Par exemple, l'utilisation du motif comme ci-dessous :
.:GetEmbedContent::https://www.youtube.com/watch?v=y8Kyi0WNg40:.
Produit le code suivant :
<iframe src="https://www.youtube.com/embed/y8Kyi0WNg40?feature=oembed" allow=" accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share " allowfullscreen="" title="Dramatic Look" width="427" height="320" frameborder="0" > </iframe>
Le résultat étant :
Pour fonctionner, ce motif utilise une liste de plateformes disponibles ici et inclus avec VenC.
L'utilisation de ce motif génère des données mises en cache dans le répertoire de votre projet.
.:GetVenCVersion:.
Ce motif retourne la version de VenC avec laquelle la page courante est générée.
.:HTML::content:.
Identique à DisableMarkup
, mais rajoute des balises </p>
et <p>
, respectivement au début et à la fin du texte de sortie.
Si vous voulez intégrer du code HTML dans votre publication, préférez ce motif à DisableMarkup
qui lui risquerait de produire in fine une page avec des erreurs de validation W3C.
.:IncludeFile::filename[::arg1][::arg2][...]:.
Ce motif permet d'inclure le contenu d'un fichier dans la publication courante. Celui-ci ne doit comporter que des caractères imprimables.
Ce motif prend au minimum un argument :
filename
: le chemin du fichier à inclure dans la page. Celui-ci doit se trouver dans le répertoire includes
de votre projet. Si le fichier n'existe pas ou n'est pas accessible, VenC lève une exception.arg1
, arg2
, ... : ces paramètres sont optionnels. Ils vous permettent de formater l'intérieur du fichier à inclure en remplaçant des variables numérotées (venc_arg_1
, venc_arg_2
, venc_arg_n
) qui s'y trouverait par la valeur de chacun des paramètres correspondant.Avec un fichier contenant plein de trucs longs et compliqués que nous appellerons :
plein-de-trucs-longs-et-compliqués.txt
Et qui se trouverait dans le répertoire includes
de votre projet.
Nous utiliserions alors le motif comme suit :
.:IncludeFile::plein-de-trucs-longs-et-compliqués.txt:.
Notons que tout ce qui se trouve à l'intérieur du fichier ainsi inclus n'est pas traité par les interpréteurs de langage de balisage.
Nous utiliserons les paramètres optionnels pour formater le contenu du fichier à inclure.
Soit le fichier :
liste_de_choses_à_faire.txt
Qui contiendrait :
Voilà les choses qu'il faut que je fasse avant de mourir : - {venc_arg_1} - {venc_arg_2} - {venc_arg_3} - {venc_arg_4}
En utilisant le motif IncludeFile
comme suit :
.:IncludeFile::liste_de_choses_à_faire.txt:: Libérer la Corée du Nord:: Terraformer la lune:: Découvrir la matière exotique et commercialiser les trous de ver pour le voyage interstellaire:: Nourrir Tacos, mon chien. :.
Nous obtiendrions :
Voilà les choses qu'il faut que je fasse avant de mourrir - Libérer la Corée du Nord - Terraformer la Lune - Découvrir la matière exotique et commercialiser les trous de ver pour le voyage interstellaire - Nourrir Tacos, mon chien
La portion de texte ci-dessus serait incluse telle quelle dans la page générée par VenC.
.:IncludeFileIfExists::filename[::arg1][::arg2][...]:.
Identique à IncludeFile
, mais le motif
est ignoré si le fichier à inclure est inaccessible ou s'il n'existe pas.
.:Kroki::endpoint::format::code[::provider]:.
Kroki est une API en ligne permettant de générer des diagrammes depuis une description textuelle. VenC permet
d'utiliser cette API nativement, mais nécessite tout de même que la librairie Python requests
soit installée.
Les arguments sont les suivants :
endpoint
: le nom du type de diagramme que vous souhaitez générer. Vous pouvez consulter la liste de ces types de diagramme ici.format
: le format de l'image retourné par le serveur :
png
svg
code
: la description textuelle du diagramme que vous voulez générer.provider
: il s'agit du serveur depuis lequel l'API est utilisée. Par défaut, il s'agit de https://kroki.io.VenC récupère l'image est l'enregistre dans le répertoire extra
. Celle-ci est ensuite copiée à la racine du blog.
Le motif renvoie quant à lui une balise img
de la forme :
<img class="__VENC_KROKI__" src="../kroki_2b7b50208100ca9a40a3138ee72e62f7.svg">
On se propose de générer un diagramme UML avec PlantUML au format SVG :
.:Kroki:: plantuml:: svg:: skinparam ranksep 20 skinparam dpi 125 skinparam packageTitleAlignment left rectangle "Main" { (main.view) (singleton) } rectangle "Base" { (base.component) (component) (model) } rectangle "<b>main.ts</b>" as main_ts (component) ..> (base.component) main_ts ==> (main.view) (main.view) --> (component) (main.view) ...> (singleton) (singleton) ---> (model) :.
Ce qui donnerait :
.:Kroki::endpoint::format::filename[::provider]:.
Identique à Kroki, mais l'argument code
est remplacé par filename
.
Il s'agit du nom de fichier contenant le code décrivant le diagramme. Si le fichier n'existe pas ou n'est pas accessible,
VenC s'arrête sur une erreur.
.:Latex2MathML::latex_code:.
Ce motif vous permet de générer du code MathML converti depuis le très populaire langage LaTeX. Ainsi, vous pouvez facilement inclure dans votre publication des formules mathématiques.
Cette fonctionnalité dépend d'une librairie tierce, indépendante de VenC. En cas de problème ou de difficulté, vous pourriez vouloir signaler un bug sur la page du projet latex2mathml.
Le seul argument du motif est :
latex_code
: le code source LaTeX de la formule que vous souhaitez intégrer.Par exemple :
.:Latex2MathML::\overline{z^{n+1}} = {\overline{z}}^{n+1}:.
Produirait le code suivant :
<math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"> <mrow> <mover> <mrow> <msup> <mi>z</mi> <mrow> <mi>n</mi> <mo>+</mo> <mn>1</mn> </mrow> </msup> </mrow> <mo stretchy="true">¯</mo> </mover> <mo>=</mo> <msup> <mrow> <mover> <mrow> <mi>z</mi> </mrow> <mo stretchy="true">¯</mo> </mover> </mrow> <mrow> <mi>n</mi> <mo>+</mo> <mn>1</mn> </mrow> </msup> </mrow> </math>
Le résultat étant :
.:SetBackgroundColor::color::input_text:.
Ce motif permet de formater du texte avec la couleur de fond de son choix et prend deux arguments :
input_text
: le texte à formater. Peut contenir d'autres motifs.color
: la couleur désirée, telle que spécifiée par CSS..:SetColor::color::input_text:.
Ce motif permet de formater du texte avec la couleur de son choix et prend deux arguments :
input_text
: le texte à formater. Peut contenir d'autres motifs.color
: la couleur désirée, telle que spécifiée par CSS.Par exemple :
.:SetColor::red::Texte de couleur rouge:.
Produira le code HTML suivant :
<span class="__VENC_TEXT_COLOR__" style="color: red;">Texte de couleur rouge</span>
On remarque que la balise <span>
a pour classe __VENC_TEXT_COLOR__
, ce qui
permet plus de contrôle lors de la mise en page de votre blog.
.:SetStyle::tag_id::tag_class::content:.
Ce motif permet d'assigner un id
et une classe CSS à une paire de balises
span
(une ouvrante et une fermante) ajoutée par VenC pour encapsuler le texte passé en paramètre.
Ce motif prend donc trois paramètres :
tag_id
: le nom de l'id
CSS à assigner au texte.tag_class
: le nom de la classe CSS à assigner au texte.content
: le texte auquel vous souhaitez appliquer un style CSS.Par exemple :
.:SetStyle::mon_id::ma_class::Un texte quelconque à formater. :.
Produirait :
<span id="mon_id" class="ma_class">Un texte quelconque à formater.</span>
.:Table[::item1][::item2] ... :.
Ce motif permet d'organiser du contenu dans un tableau. Le motif a un nombre illimité d'arguments. Chaque argument correspond au contenu d'une cellule.
Quand VenC détecte qu'un argument est égal à la valeur NewLine
, une nouvelle ligne est insérée,
puis VenC poursuit l'ajout des cellules du tableau pour chaque argument.
Par exemple, pour créer un tableau de quatre cellules et deux lignes :
.:Table:: VenC version: :: .:GetVenCVersion:. :: NewLine:: Date :: .:GetGenerationTimestamp::%d-%m-%Y:. :.
Ce qui produira le code suivant :
<div class="__VENC_TABLE__"> <table> <tr> <td>VenC version:</td> <td>2.0.0</td> </tr> <tr> <td>Date</td> <td>11-06-2020</td> </tr> </table> </div>
Comme on le voit, il est possible d'utiliser des motifs VenC à l'intérieur du motif Table
.
Remarquons également que pour chaque cellule, les caractères blancs au début et à la fin de l'argument correspondant sont effacés.
.:Video::source::extensions[::poster]:.
Ce motif fonctionne comme Audio
, il possède cependant un argument supplémentaire
pour ajouter une vignette.
Ce motif permet donc d'inclure un fichier vidéo dans la page. Pour ce faire, le fichier video.html
faisant partie du thème est formaté avec les paramètres passés au motif :
source
: il s'agit de l'URL ou du chemin de la vidéo. Il peut s'agir d'un chemin absolu ou relatif. S'il s'agit d'un chemin relatif, vous pouvez utiliser GetRelativeRoot
. Attention, l'URL ou le chemin passé en paramètre ne doit pas contenir l'extension du fichier.extensions
: pour assurer la compatibilité de votre contenu avec les différents navigateurs du marché, il est recommandé d'avoir plusieurs sources de la même vidéo en différents formats. Ce paramètre est donc une liste des extensions disponibles pour votre vidéo. Les éléments de la liste sont séparés par une virgule.poster
: il est possible d'avoir une image de fond, en remplacement de la vidéo quand celle-ci n'est pas encore lancée. Ce paramètre contient donc l'URL ou le chemin relatif (vous pouvez également utiliser GetRelativeRoot
) ou absolu de ladite image.<video controls poster="{poster}" style="width: 100%;"> {source} Your browser does not support the video tag. </video>
Ce qui est important ici, c'est la variable Python source
que VenC remplace par autant de balises <source>
que nécessaire pour épuiser la liste des différents formats du fichier vidéo courant.
La variable optionnelle poster
contient l'URL de l'image de fond passée en argument au motif.
.:Video:: https://www.w3schools.com/html/mov_bbb:: mp4,ogg:: .:GetRelativeRoot:.bbb-poster.jpg :.
Finalement, on obtient le résultat suivant :
Ce chapitre comporte un tableau récapitulant l'ensemble des motifs reconnus par VenC, ainsi que leurs arguments.
Si vous souhaitez créer ou modifier un thème existant, c'est le bon endroit pour étudier les différentes possibilités qui s'offrent à vous.
Motifs | Arguments | Variables |
Audio |
|
|
CherryPickBlogMetadata |
| |
CherryPickBlogMetadataIfExists |
| |
CherryPickEntryMetadata |
| |
CherryPickEntryMetadataIfExists |
| |
CodeHighlight |
| |
CodeHighlightInclude |
| |
DisableMarkup |
| |
Escape |
| |
ForBlogArchives |
|
|
ForBlogMetadata |
|
|
ForBlogMetadataIfExists |
|
|
ForEntriesSet |
|
|
ForEntryAuthors |
|
|
ForEntryMetadata |
|
|
ForEntryMetadataIfExists |
|
|
ForPages |
|
|
GetAuthorDescription | ||
GetAuthorEmail | ||
GetAuthorName | ||
GetBlogCategoriesTree |
|
|
GetBlogCategoriesTreeFromBranches |
|
|
GetBlogDescription | ||
GetBlogLanguage | ||
GetBlogLicense | ||
GetBlogMetadata |
| |
GetBlogMetadataIfExists |
|
|
GetBlogMetadataIfNotNull |
|
|
GetBlogMetadataTree |
|
|
GetBlogMetadataTreeIfExists |
|
|
GetBlogName | ||
GetBlogURL | ||
GetChapterAttributeByIndex |
| |
GetChapters |
|
|
GetEmbedContent |
| |
GetEntryArchivePath | ||
GetEntryAttributeByID |
| |
GetEntryCategoriesTree |
|
|
GetEntryCategoriesTreeFromBranches |
|
|
GetEntryChapterLevel | ||
GetEntryChapterPath | ||
GetEntryContent | ||
GetEntryDate |
| |
GetEntryDay | ||
GetEntryHour | ||
GetEntryID | ||
GetEntryMetadata |
| |
GetEntryMetadataIfExists |
|
|
GetEntryMetadataIfNotNull |
|
|
GetEntryMetadataTree |
|
|
GetEntryMetadataTreeIfExists |
|
|
GetEntryMinute | ||
GetEntryMonth | ||
GetEntryPath | ||
GetEntryPreview | ||
GetEntryTitle | ||
GetEntryToC |
|
|
GetEntryYear | ||
GetFlattenedBlogCategories |
|
|
GetFlattenedBlogCategoriesFromBranches |
|
|
GetFlattenedEntryCategories |
|
|
GetFlattenedEntryCategoriesFromBranches |
|
|
GetGenerationTimestamp |
| |
GetLastEntryTimestamp |
| |
GetNextPage |
|
|
GetPreviousPage |
|
|
GetRandomNumber |
| |
GetRelativeLocation | ||
GetRelativeRoot | ||
GetRootPage | ||
GetStyleSheets | ||
GetThreadName |
|
|
GetVenCVersion | ||
HTML |
| |
IfAtomEnabled |
| |
IfBlogMetadataIsTrue |
| |
IfCategories |
| |
IfChapters |
| |
IfEntryMetadataIsTrue |
| |
IfFeedsEnabled |
| |
IfInArchives |
| |
IfInCategories |
| |
IfInEntryID |
| |
IfInFeed |
| |
IfInFirstPage |
| |
IfInLastPage |
| |
IfInMainThread |
| |
IfInThread |
| |
IfInThreadAndHasFeeds |
| |
IfInfiniteScrollEnabled |
| |
IfPages |
| |
IfRSSEnabled |
| |
IncludeFile |
|
|
IncludeFileIfExists |
|
|
Kroki |
| |
KrokiFromFile |
| |
Latex2MathML |
| |
PreviewIfInThreadElseContent | ||
RangeEntriesByID |
| |
SetBackgroundColor |
| |
SetColor |
| |
SetStyle |
| |
Table |
| |
Video |
|
|