5 Pattern Processor

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.

5.1 Syntaxe

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.

5.2 Variables de motif

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.

5.3 Motifs contextuels

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à.

ForPages

Ce motif permet de générer une liste de liens de pagination.

.:ForPages::length::string::separator:.

Ce motif comporte les variables suivantes :

GetEntryContent

.: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

.: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

.: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

.:GetNextPage::string:.

Permet de récupérer des informations sur la prochaine page, si elle existe.

Ce motif comporte les variables suivantes :

GetPreviousPage

.:GetPreviousPage::string:.

Permet de récupérer des informations sur la page précédente, si elle existe.

Ce motif possède les variables suivantes :

GetRandomNumber

.: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

.: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

.: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

.: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

.: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.

IfInArchives

.:IfInArchives::string1[::string2]:.

La fonction teste si la page courante est générée dans le fil des archives.

À noter que ce motif n'a pas de variable.

IfInCategories

.:IfInCategories::string1[::string2]:.

La fonction teste si la page courante est générée dans le fil des catégories.

À noter que ce motif n'a pas de variable.

IfInEntryID

.:IfInEntryID::id::string1[::string2]:.

La fonction teste si l'identifiant de la publication correspond à celui spécifié en argument.

Ce motif n'a pas de variable.

IfInFeed

.: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.

Ce motif n'a pas de variable.

IfInFirstPage

.: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.

Ce motif n'a pas de variable.

IfInLastPage

.: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.

Ce motif n'a pas de variable.

IfInMainThread

.:IfInMainThread::string1[::string2]:.

La fonction teste si la page courante est générée dans le fil de publications principal.

Ce motif n'a pas de variable.

IfInThread

.: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.

Ce motif n'a pas de variable.

IfInThreadAndHasFeeds

.: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.

Ce motif n'a pas de variable.

IfPages

.:IfPages::string1[::string2]:.

La fonction teste si le fil de publications courant a plus d'une page.

Ce motif n'a pas de variable.

PreviewIfInThreadElseContent

.: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.

5.4 Motifs non contextuels

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.

5.4.1 Motifs de publication

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

.: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:.

CherryPickEntryMetadataIfExists

Identique à CherryPickEntryMetadata, mais est ignoré en cas d'erreur.

ForEntryAuthors

.: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 :

Le second paramètre est une chaîne de caractères servant de séparateur.

ForEntryMetadata

.: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 :

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

.: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

.:GetEntryArchivePath:.

Retourne le liens vers le groupe d'archives dans lequel se trouve la publication.

GetEntryCategoriesTree

.: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 :

Les variables de ce motif sont les suivantes :

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

 
.: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

.: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

.:GetEntryChapterPath:.

Renvoie le chemin relatif du chapitre correspondant à la publication courante.

GetEntryDate

.: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

.:GetEntryDay:.

Retourne le jour de création de la publication.

GetEntryHour

.:GetEntryHour:.

Retourne l'heure de création de la publication.

GetEntryID

.:GetEntryID:.

Retourne l'identifiant unique de la publication.

GetEntryMetadata

.: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

.: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 :

Il est possible d'utiliser la variable suivante dans l'argument string pour formater le texte :

GetEntryMetadataIfNotNull

.: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

 
.: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 :

Ce motif possède les variables suivantes :

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

  .: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

.:GetEntryMinute:.

Retourne la minute de création de la publication.

GetEntryMonth

.:GetEntryMonth:.

Retourne le mois de création de la publication.

GetEntryPath

.: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

.:GetEntryTitle:.

Retourne le titre de la publication.

GetEntryToC

.: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.

Le motif a quelques variables qu'il est possible d'utiliser dans l'argument content :

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 :

GetEntryYear

.:GetEntryYear:.

Retourne l'année de création de la publication.

GetFlattenedEntryCategories

.: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 :

Dans l'argument string vous pouvez utiliser les variables suivantes :

GetFlattenedEntryCategoriesFromBranches

 
.: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

.: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 :

5.4.2 Motifs de blog

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

.: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:.

CherryPickBlogMetadataIfExists

Identique à CherryPickBlogMetadata, mais est ignoré en cas d'erreur.

ForBlogArchives

.: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.

Les variables de la fonction sont les suivantes :

Si la génération des archives est désactivée, le motif est ignoré et supprimé.

ForBlogMetadata

.: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 :

Vous pouvez utiliser la variable suivante dans l'argument string :

ForBlogMetadataIfExists

.:ForBlogMetadataIfExists::metadata_name::string[::separator]:.

Identique à ForBlogMetadata, mais si la métadonnée demandée n'existe pas, le motif est ignoré.

ForEntriesSet

.: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 :

Les variables pouvant être utilisées sont par défaut :

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

.: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

.: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

.: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

.: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 :

Les variables de ce motif sont les suivantes :

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

 
.: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 :

Les variables de ce motif sont les suivantes :

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

.:GetBlogDescription:.

Retourne la description du blog définie dans blog_description. Si la métadonnée est absente, le motif est ignoré.

GetBlogLanguage

.:GetBlogLanguage:.

Retourne la langue du blog définie dans blog_language. Si la métadonnée est absente, le motif est ignoré.

GetBlogLicense

.: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

.: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

.: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 :

Le formatage du texte se fait en utilisant une variable propre à l'argument string :

GetBlogMetadataIfNotNull

.: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

  .: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 :

Ce motif possède les variables suivantes :

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

  .: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

.:GetBlogName:.

Retourne le titre du blog défini dans blog_name.

GetBlogURL

.: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

.: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 :

GetChapters

.: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 :

Les variables contextuelles de la fonction sont les suivantes :

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

.: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 :

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

.: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 :

Dans l'argument string vous pouvez utiliser les variables suivantes :

GetFlattenedBlogCategoriesFromBranches

 
.:GetFlattenedBlogCategoriesFromBranches::
  branches::
  sub_tree_string::
  sub_tree_separator::
  string::
  separator
:.
 

Vous pouvez utiliser les variables suivantes dans sub_tree_string et 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

.: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

.: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 :

IfAtomEnabled

.:IfAtomEnabled::string1[::string2]:.

La fonction teste si VenC est configuré pour générer un flux Atom.

IfBlogMetadataIsTrue

.: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 :

IfCategories

.: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.

IfChapters

.: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.

IfFeedsEnabled

.:IfFeedsEnabled::string1[::string2]:.

La fonction teste si VenC est configuré pour générer un flux RSS et/ou un flux Atom.

IfInfiniteScrollEnabled

.: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.

IfRSSEnabled

.:IfRSSEnabled::string1[::string2]:.

La fonction teste si VenC est configuré pour générer un flux RSS.

RangeEntriesByID

.: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}:.

5.4.3 Motifs divers

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

.: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 :

Exemple de fichier audio.html

<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.

Exemple d'utilisation

.:Audio::http://www.nyan.cat/music/original::mp3,ogg:.

On voit ici que le fichier audio est disponible en deux formats :

Il y a donc deux fichiers :

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>

CodeHighlight

.: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 :

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">&lt;stdio.h&gt;</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">&quot;Hello VenC user!</span>
            <span class="se">\n</span>
            <span class="s">&quot;</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">

CodeHighlightInclude

.: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

.: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.

Escape

.:Escape::content:.

Identique à DisableMarkup, mais permet d'ignorer également les motifs contenus à l'intérieur du texte de l'unique argument content.

GetEmbedContent

.: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 :

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

.:GetVenCVersion:.

Ce motif retourne la version de VenC avec laquelle la page courante est générée.

HTML

.: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

.: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 :

Un premier exemple

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.

Second exemple

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

.:IncludeFileIfExists::filename[::arg1][::arg2][...]:.

Identique à IncludeFile, mais le motif est ignoré si le fichier à inclure est inaccessible ou s'il n'existe pas.

Kroki

.: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 :

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">

Exemple basé sur celui proposé sur le site du projet

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 :

KrokiFromFile

.: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

.: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 :

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>&#x0002B;</mo>
                        <mn>1</mn>
                    </mrow>
                </msup>
            </mrow>
            <mo stretchy="true">&#x000AF;</mo>
        </mover>
        <mo>&#x0003D;</mo>
        <msup>
            <mrow>
                <mover>
                    <mrow>
                        <mi>z</mi>
                    </mrow>
                    <mo stretchy="true">&#x000AF;</mo>
                </mover>
            </mrow>
            <mrow>
                <mi>n</mi>
                <mo>&#x0002B;</mo>
                <mn>1</mn>
            </mrow>
        </msup>
    </mrow>
</math>

Le résultat étant :

zn+1=zn+1

SetBackgroundColor

.:SetBackgroundColor::color::input_text:.

Ce motif permet de formater du texte avec la couleur de fond de son choix et prend deux arguments :

SetColor

.:SetColor::color::input_text:.

Ce motif permet de formater du texte avec la couleur de son choix et prend deux arguments :

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

.: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 :

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

.: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

.: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 :

Exemple de fichier video.html

<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.

Exemple d'utilisation

 
.:Video::
  https://www.w3schools.com/html/mov_bbb::
  mp4,ogg::
  .:GetRelativeRoot:.bbb-poster.jpg
:.

Finalement, on obtient le résultat suivant :

5.5 Feuille de référence

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.

MotifsArgumentsVariables
Audio
  • source
  • extensions
  • source
CherryPickBlogMetadata
  • branch
CherryPickBlogMetadataIfExists
  • branch
CherryPickEntryMetadata
  • branch
CherryPickEntryMetadataIfExists
  • branch
CodeHighlight
  • langage
  • display_line_numbers
  • input_code
CodeHighlightInclude
  • langage
  • display_line_numbers
  • filename
DisableMarkup
  • content
Escape
  • content
ForBlogArchives
  • string
  • separator
  • value
  • path
  • count
  • weight
  • html_id
ForBlogMetadata
  • metadata_name
  • string
  • separator
  • value
  • html_id
ForBlogMetadataIfExists
  • metadata_name
  • string
  • separator
  • value
  • html_id
ForEntriesSet
  • entries_subset_key
  • string
  • id
  • title
  • path
  • archive_path
  • chapter_path
  • ...
ForEntryAuthors
  • string
  • separator
  • value
  • html_id
ForEntryMetadata
  • metadata_name
  • string
  • separator
  • value
  • html_id
ForEntryMetadataIfExists
  • metadata_name
  • string
  • separator
  • value
  • html_id
ForPages
  • length
  • string
  • separator
  • page_number
  • entry_id
  • entry_title
  • path
GetAuthorDescription
    GetAuthorEmail
      GetAuthorName
        GetBlogCategoriesTree
        • open_node
        • open_branch
        • close_branch
        • close_node
        • value
        • html_id
        • count
        • weight
        • path
        • childs
        GetBlogCategoriesTreeFromBranches
        • branches
        • sub_tree_string
        • separator
        • open_node
        • open_branch
        • close_branch
        • close_node
        • value
        • html_id
        • count
        • weight
        • path
        • childs
        GetBlogDescription
          GetBlogLanguage
            GetBlogLicense
              GetBlogMetadata
              • metadata_name
              GetBlogMetadataIfExists
              • metadata_name
              • if_true
              • if_false
              • ok_if_null
              • value
              GetBlogMetadataIfNotNull
              • metadata_name
              • if_true
              • if_false
              • value
              GetBlogMetadataTree
              • metadata_name
              • open_node
              • open_branch
              • value_childs
              • value
              • close_branch
              • close_node
              • value
              • tree
              • html_id
              GetBlogMetadataTreeIfExists
              • metadata_name
              • open_node
              • open_branch
              • value_childs
              • value
              • close_branch
              • close_node
              • value
              • childs
              • html_id
              GetBlogName
                GetBlogURL
                  GetChapterAttributeByIndex
                  • attribute
                  • index
                  GetChapters
                  • list_open
                  • item_open
                  • item_close
                  • list_close
                  • index
                  • title
                  • path
                  • level
                  • html_id
                  GetEmbedContent
                  • content_url
                  GetEntryArchivePath
                    GetEntryAttributeByID
                    • attribute
                    • identifier
                    GetEntryCategoriesTree
                    • open_node
                    • open_branch
                    • close_branch
                    • clode_node
                    • value
                    • html_id
                    • count
                    • weight
                    • path
                    • childs
                    GetEntryCategoriesTreeFromBranches
                    • branches
                    • sub_tree_string
                    • separator
                    • open_node
                    • open_branch
                    • close_branch
                    • close_node
                    • value
                    • html_id
                    • count
                    • weight
                    • path
                    • childs
                    GetEntryChapterLevel
                      GetEntryChapterPath
                        GetEntryContent
                          GetEntryDate
                          • date_format
                          GetEntryDay
                            GetEntryHour
                              GetEntryID
                                GetEntryMetadata
                                • metadata_name
                                GetEntryMetadataIfExists
                                • metadata_name
                                • string
                                • string2
                                • ok_if_null
                                • value
                                GetEntryMetadataIfNotNull
                                • metadata_name
                                • string
                                • string2
                                • value
                                GetEntryMetadataTree
                                • metadata_name
                                • open_node
                                • open_branch
                                • value_childs
                                • value
                                • close_branch
                                • close_node
                                • value
                                • childs
                                • html_id
                                GetEntryMetadataTreeIfExists
                                • metadata_name
                                • open_node
                                • open_branch
                                • value_childs
                                • value
                                • close_branch
                                • close_node
                                • value
                                • childs
                                • html_id
                                GetEntryMinute
                                  GetEntryMonth
                                    GetEntryPath
                                      GetEntryPreview
                                        GetEntryTitle
                                          GetEntryToC
                                          • open_ul
                                          • open_li
                                          • content
                                          • close_li
                                          • close_ul
                                          • id
                                          • level
                                          • title
                                          GetEntryYear
                                            GetFlattenedBlogCategories
                                            • string
                                            • separator
                                            • value
                                            • html_id
                                            • count
                                            • weight
                                            • path
                                            GetFlattenedBlogCategoriesFromBranches
                                            • branches
                                            • sub_tree_string
                                            • sub_tree_separator
                                            • string
                                            • separator
                                            • value
                                            • html_id
                                            • count
                                            • weight
                                            • path
                                            • childs
                                            GetFlattenedEntryCategories
                                            • string
                                            • separator
                                            • value
                                            • html_id
                                            • count
                                            • weight
                                            • path
                                            GetFlattenedEntryCategoriesFromBranches
                                            • branches
                                            • sub_tree_string
                                            • sub_tree_separator
                                            • string
                                            • separator
                                            • value
                                            • html_id
                                            • count
                                            • weight
                                            • path
                                            • childs
                                            GetGenerationTimestamp
                                            • time_format
                                            GetLastEntryTimestamp
                                            • time_format
                                            GetNextPage
                                            • string
                                            • page_number
                                            • entry_id
                                            • entry_title
                                            • path
                                            GetPreviousPage
                                            • string
                                            • page_number
                                            • entry_id
                                            • entry_title
                                            • path
                                            GetRandomNumber
                                            • min_value
                                            • max_value
                                            • precision
                                            GetRelativeLocation
                                              GetRelativeRoot
                                                GetRootPage
                                                  GetStyleSheets
                                                    GetThreadName
                                                    • string1
                                                    • string2
                                                    • value
                                                    GetVenCVersion
                                                      HTML
                                                      • content
                                                      IfAtomEnabled
                                                      • if_true
                                                      • if_false
                                                      IfBlogMetadataIsTrue
                                                      • metadata_name
                                                      • if_true
                                                      • if_false
                                                      IfCategories
                                                      • if_true
                                                      • if_false
                                                      IfChapters
                                                      • if_true
                                                      • if_false
                                                      IfEntryMetadataIsTrue
                                                      • metadata_name
                                                      • if_true
                                                      • if_false
                                                      IfFeedsEnabled
                                                      • if_true
                                                      • if_false
                                                      IfInArchives
                                                      • string1
                                                      • string2
                                                      IfInCategories
                                                      • string1
                                                      • string2
                                                      IfInEntryID
                                                      • entry_id
                                                      • string1
                                                      • string2
                                                      IfInFeed
                                                      • string1
                                                      • string2
                                                      IfInFirstPage
                                                      • string1
                                                      • string2
                                                      IfInLastPage
                                                      • string1
                                                      • string2
                                                      IfInMainThread
                                                      • string1
                                                      • string2
                                                      IfInThread
                                                      • string1
                                                      • string2
                                                      IfInThreadAndHasFeeds
                                                      • string1
                                                      • string2
                                                      IfInfiniteScrollEnabled
                                                      • if_true
                                                      • if_false
                                                      IfPages
                                                      • string1
                                                      • string2
                                                      IfRSSEnabled
                                                      • if_true
                                                      • if_false
                                                      IncludeFile
                                                      • filename
                                                      • arg 1
                                                      • arg 2
                                                      • arg n...
                                                      • venc_arg_1
                                                      • venc_arg_2
                                                      • venc_arg_n
                                                      • ...
                                                      IncludeFileIfExists
                                                      • filename
                                                      • arg 1
                                                      • arg 2
                                                      • arg n...
                                                      • venc_arg_1
                                                      • venc_arg_2
                                                      • venc_arg_n
                                                      • ...
                                                      Kroki
                                                      • endpoint
                                                      • image_format
                                                      • code
                                                      • provider
                                                      KrokiFromFile
                                                      • endpoint
                                                      • image_format
                                                      • filename
                                                      • provider
                                                      Latex2MathML
                                                      • tex_math_string
                                                      PreviewIfInThreadElseContent
                                                        RangeEntriesByID
                                                        • begin_at
                                                        • end_at
                                                        SetBackgroundColor
                                                        • color
                                                        • string
                                                        SetColor
                                                        • color
                                                        • string
                                                        SetStyle
                                                        • tag_id
                                                        • tag_class
                                                        • string
                                                        Table
                                                        • arg 1
                                                        • arg 2
                                                        • arg n...
                                                        Video
                                                        • source
                                                        • extensions
                                                        • poster
                                                        • source
                                                        • poster