Motifs de type Accesseur

Il existe plusieurs type de motifs que VenC reconnaît. Le premier d'entre eux est le type accesseur. Il permet de récupérer le contenu d'une variable dont la disponibilité dépend du contexte.

Accesseur de publications

Les accesseurs de publications ne sont disponibles que pendant le traitement d'une publication, donc à l'intérieur des fichiers entry.html, rssEntry.xml et atomEntry.xml et de la publication elle-même.

Il est aussi possible d'utiliser ceux-là dans des templates. Pour en savoir plus sur les templates, rendez vous ici

.:GetEntryContent:.

Ce pattern ne peut pas être utilisé dans un template.

Ce pattern renvoie le contenu complet de la publication courante.

.:GetEntryPreview:.

Ce pattern ne peut pas être utilisé dans un template.

Ce pattern renvoie le résumé de la publication courante.

.:GetEntryID:.

Retourne l'identifiant unique de la publication.

.:GetEntryTitle:.

Retourne le nom de la publication.

.:GetEntryMonth:.

Retourne le mois de création de la publication.

.:GetEntryYear:.

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

.:GetEntryDay:.

Retourne le jour de création de la publication.

. :GetEntryHour:.

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

.:GetEntryMinute:.

Retourne la minute de création de la publication.

.:GetEntryDate[::format]:.

Retourne la date de la publication formatée comme définit 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.

.:GetEntryDateURL:.

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

.:GetEntryURL:.

Retourne l'URL de la publication si VenC est configuré pour générer une page par publication. Sinon, le motif est ignoré et supprimé.

.:ForEntryAuthors::string::separator:.

Retourne la liste des auteurs de la publication.

Le premier argument est une chaîne de caractères à formater avec la variable contextuelle {value} contenant le nom de l'auteur courant.

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

.:ForEntryTags::string::separator:.

Retourne la liste des mots-clefs de la publication.

Le premier argument est une chaîne de caractères à formater avec la variable contextuelle {value} contenant le mot-clef courant.

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

.:ForEntryMetadata::variable_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 la variable contextuelle {value} contenant l'élément courant de la liste.

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

.:GetEntryMetadata::metadata_name:.

Il est possible de définir ses propres champs dans les métadonnées de la publication ou du template.

Par exemple, si on définie 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 vous indiquera où en est l'origine.

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

Il est possible d'utiliser des variables contextuelles propre à la fonction pour formater le texte :

  • {value} : la valeur de la métadonnée qu'on référence.

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 rempli. Si cet argument n'est pas présent, le pattern est ignoré.

.:GetEntryMetadataIfNotNull::metadata_name[::string][::string2]:.

Identique à GetEntryMetadataIfExists, mais la métadonnée spécifié ne doit pas être vide.

<div id="entry.:GetEntryID:." .:GetMetadataIfExists::alternate_style::class="{value}":. >

Si la variable référencée n'est pas définie, VenC ignore le motif et le supprime.

Si le second argument n'est pas définie, l'accesseur renvoie directement la variable référencée, si elle existe.

.:LeavesForEntryCategories::string::separator:.

Les catégories sont organisées sous la forme d'un arbre. Il est possible de ne récupérer que les "feuilles" de cet arbres, c'est-à-dire les catégories qui n'ont pas de sous-catégories.

Les arguments du motif sont les suivants :

  • string : la chaîne de caractèress à formater avec des variables contextuelles.
  • separator : la chaîne de caractères qui sert de séparateur.

LeavesForEntryCategories possède les variables contextuelles suivante :

  • {value} : contient le nom de la catégorie courante.
  • {path} : contient le chemin relatif de la catégorie courante.
  • {branch} : contient la branche complète de la catégorie, de la racine de l'arborescence jusqu'à la catégorie courante.

Par exemple, si la publication courante se trouve dans les catégories suivantes :

categories: 'moo, foo > bar, boo > loo > poo'

Alors le motif :

.:LeavesForEntryCategories::{value}::,:.

Retournera :

moo,bar,poo

Ce motif est ignoré et supprimé si la génération des catégories est désactivée dans le fichier de configuration principal.

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

  • 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 contextuelles de ce motif sont les suivantes :

  • {value} : le nom de la catégorie courante.
  • {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 maximal de publications par catégorie.

Par exemple, pour créer un menu déroulant on peut utiliser le motif comme ci-dessous :

.:Chapters::
    <ul class="chapter-level{level}">::
    <li>{index}. <a href="{path}">{title}</a>::
    </li>::
    </ul>
:.

Si la publication était incluse dans les catégories suivantes :

categories: 'Material > Metal > Copper, Material Metal > 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>
                </ul>
            </li>
        </ul>
    </li>
    <li>
        <a href="../Material-Metal/" title="1 publications">Material Metal</a>
        <ul>
            <li>
                <a href="../Material-Metal/Steel/" title="1 publications">Steel</a>
            </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égorie 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é dans le fichier de configuration principal.

Accesseurs globaux

Ces motifs sont disponibles quelque soit le contexte et leurs valeurs sont définis dans blog_configuration.yaml.

.:GetAuthorName:.

Retourne le nom de l'auteur du blog.

.:GetBlogName:.

Retourne le titre du blog.

.:GetBlogDescription:.

Retourne la description du blog.

.:GetBlogKeywords:.

Retourne les mots-clefs décrivant le blog.

.:GetAuthorDescription:.

Retourne la description de l'auteur du blog.

.:GetBlogLicense:.

Retourne la licence appliquée au contenu du blog.

.:GetBlogURL:.

Retourne l'URL du blog.

.:GetBlogLanguage:.

Retourne la langue du blog.

.:GetAuthorEmail:.

Retourne l'adresse email de l'auteur du blog.

.: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 rajoutant la ligne suivante dans le fichier de configuration :

Banner: 'maBanniere.jpg'

Vous pourrez ensuite récupérer la valeurs 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 y inclure celle-ci.

Le formatage du texte se fait en utilisant des variables contextuelles propre à la fonction :

  • {value} : la valeur de la métadonnée qu'on référence.

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

.:GetBlogMetadataIfNotNull::metadata_name[::string][::string2]:.

Identique à GetBlogMetadataIfExists, mais la métadonnée spécifiée ne doit pas être vide.

.:GetBlogMetadataIfExists::mastodon::
    <a href="{value}" class="social-network-item">
        <img src="{relative_origin}mastodon.png" alt="Mastodon" title="Mastodon"/>
    </a>
:.

Dans cet example, 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 la variable contextuelle {relative_origin}.

Si la variable référencée n'est pas définie VenC ignore le motif et le supprime.

Si le second argument n'est pas définit, l'accesseur renvoie directement la variable référencée si elle existe.

.:ForBlogArchives::string::separator:.

Ce motif permet de récupérer la listes des périodes archivées. Le format de la période de temps est défini dans le fichier de configuration principal par le champ archives_directory_name.

  • Le premier argument string contient le texte à formater pour chaque élément de la liste de période.
  • Le second argument separator contient le texte utilisé comme séparateur.

Les variables contextuelles de la fonction sont les suivantes :

  • {value} : la période courante, tel que défini par archives_directory_name dans le fichier de configuration principal du blog.
  • {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é.

.:LeavesForBlogCategories::string::separator:.

Les catégories sont organisées sous la forme d'un arbre. Il est possible de ne récupérer que les "feuilles" de cet arbres, c'est-à-dire les catégories qui n'ont pas de sous-catégories.

Le motif fonctionne comme LeavesForEntryCategories mais construit l'arborescence des catégories en compilant toutes les catégories de toutes les publications.

Les arguments du motif sont les suivants :

  • string : la chaîne de caractères à formater avec des variables contextuelles.
  • separator : la chaîne de caractère qui sert de séparateur.

LeavesForBlogCategories possède les variables contextuelles suivante :

  • {value} : contient le nom de la catégorie courante.
  • {path} : contient le chemin relatif de la catégorie courante.
  • {branch} : contient la branche complète de la catégorie; de la racine de l'arborescence, jusqu'à la catégorie courante.

Par exemple, imaginons que l'arborescence des catégories du blog se présente de la façon suivante :

├─── Science 
│    ├─── Chemistry
│    └─── Physics
└─── Art
     ├─── Music
     └─── Painting

Alors :

.:LeavesForEntryCategories::{value}::,:.

Retournera :

Chemestry,Physic,Music,Painting

Ce motif est ignoré et supprimé si la génération des catégories est désactivée dans le fichier de configuration principal.

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

Le motif fonctione comme TreeForEntryCategories mais construit l'arborescence des catégories en compilant toutes les catégories de toutes les publications.

Les arguments du motif sont :

  • open_node : contient la chaîne de caractère d'ouverture pour la catégorie parente.
  • open_branch : contient la chaîne de caractère d'ouverture de la catégorie courante.
  • close_branch : contient la chaîne de caractère de fermeture de la catégorie courante.
  • close_node : contient la chaîne de caractère de fermeture de la catégorie parente.

Les variables contextuelles de ce motif sont les suivantes :

  • {value} : le nom de la catégorie courante.
  • {path} : le chemin relatif de la catégorie courante.
  • {count} : le nombre de publication dans la catégorie courante.
  • {weight} : le nombre de publication dans la catégorie courante divisé par le nombre maximal de publication par catégorie.

Par exemple, pour créer un menu déroulant, on utilisera le motif comme ci-dessous :

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

Si l'ensemble des catégories du blog formait l'arborescence suivante :

├─── Material
│    └─── Metal
│          ├─── Copper
│          └─── Steel
└─── Science

Alors le motif générera 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>
                </ul>
            </li>
        </ul>
    </li>
    <li>
        <a href="../Material-Metal/" title="1 publications">Material Metal</a>
        <ul>
            <li>
                <a href="../Material-Metal/Steel/" title="1 publications">Steel</a>
            </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 principal.

.:GetChapters::open_node::open_branch::close_branch::close_node:.

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 TreeForEntryCategories et TreeForBlogCategories :

  • open_node : contient la chaîne de caractère d'ouverture du chapitre parent.
  • open_branch : contient la chaîne de caractère d'ouverture du chapitre courant.
  • close_branch : contient la chaîne de caractère de fermeture du chapitre courant.
  • close_node : contient la chaîne de caractère 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 un chapitre avec l'index '3.2' aurait le niveau 1. Un chapitre avec l'index '4.2.1' aurait le niveau 2 et un chapitre avec l'index '2' aurait le niveau 0.
  • {title} : le titre du chapitre courant.
  • {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 par exemple 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é.

.:GetThreadName[::string1][::string2]:.

Ce motif permet de récupérer le nom du fil de publication courant.

Par exemple, si la page courange est générée dans un fil de publication de type categorie et que ladite catégorie s'appel "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 publication n'a pas de nom alors c'est string2 qui est renvoyée.

  • string1 : premier argument du motif, c'est celui qui est renvoyé si le fil de publication a un nom. Pour accéder au nom du fil de publication dans l'argument, il faut utiliser la variable contextuelle {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 publication, sans formatage particuler.
  • string2 : second argument du motif, c'est celui qui est renvoyé si le fil de publication 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é.

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

  • 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, entre autres métadonnées définis dans le header YAML de la publication, l'url de celle-ci. Par exemple :

.:GetEntryAttributeByID::url::1337:.

Renverra le permalien relatif de la publication dont l'identifiant est 1337.

.:GetChapterAttributeByIndex::attribute::index:.

Ce motif permet de récupérer n'importe quelle métadonnée d'un chapitre en renseignant son index.

  • attribute : nom de la métadonnée du chapitre.
  • index : index du chapitre dont on veut récupérer la métadonnée.

Typiquement ce pattern sert à récupérer le titre du chapitre, ou son chemin. Par exemple :

.:GetChapterAttributeByIndex::path::1.2.3:.

Renverra le permalien relatif du chapitre 1.2.3.

.:GetChapterAttributeByIndex::title::4.2:.

Renverra le permalien relatif du chapitre 4.2.