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