Motifs de mise en page

Il s'agit de motifs qui intéragissent le plus souvent directement avec le système de pagination et les chemins manipulés par VenC. Il sont conçus spécifiquement pour vous aider à la mise en page et peuvent par exemple générer du code HTML ou formater du texte.

Motifs conditionnels

Ce type de motifs s'exécutent sous condition. Ils permettent une mise en page plus fine et spécifique en renvoyant l'un ou l'autre argument selon que la condition du test est remplie ou non.

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInThread::string1[::string2]:.

La fonction teste si la page courante est généréee dans le contexte d'un fil de publications (catégories, archives de chapitres, ou fil principal).

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInFirstPage::string1[::string2]:.

La fonction teste si le numéro de page courant correspond à la première page du fil de publication courant. Si la page est générée dans le contexte d'une page individuelle de publication ou d'un chapitre, le test échoue.

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInLastPage::string1[::string2]:.

La fonction teste si le numéro de page courant correspond à la dernière page du fil de publication courant. Si la page est généré dans le contexte d'une page individuelle de publication ou d'un chapitre, le test échoue.

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

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

  • id : un nombre entier différent de 0 identifiant une publication.
  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

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

La fonction teste si le fil de publication courant à plus d'une page.

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition est fausse. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

IfFeedsEnabled::string1[::string2]:.

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

IfRSSEnabled::string1[::string2]:.

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

IfAtomEnabled::string1[::string2]:.

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

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInThreadAndHasFeeds::string1[::string2]:.

La fonction teste si le fil de publication courant peut produire un flux Atom et/ou RSS. Seul les categories et le fil principal valident la condition.

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInFeed::string1[::string2]:.

Certains éléments contenus dans une publication ne peuvent pas être présent 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 publication courant est un flux RSS ou Atom.

  • string1 : texte retourné si la condition est remplie.
  • string2 : texte retourné si la condition n'est pas remplie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:IfInfiniteScrollEnabled::string1[::string2]:.

Permet de tester si la variable disable_infinite_scroll est définie dans le fichier de configuration principal et, si c'est le cas, quelle en est la valeur booléenne.

  • string_1 : texte retourné si la variable testée vaut True.
  • string_2 : texte retourné si la variable testée vaut False ou si elle n'est pas définie. Si le second argument est absent, le motif est ignoré et supprimé.

Ce motif n'a pas de variable contextuelle.

.:PreviewIfInThreadElseContent:.

Ce pattern ne peut être utilisé que dans le chunk entry.html.

Il renvoie le résumé de la publication courante si VenC génère la page dans un fil de publication. Sinon, VenC renvoie le contenu complet de la publication courante.

Générateurs de chemins

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

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

  • length : définit la longueur de la liste.
  • string : le texte à formater, contenant les valeurs des variables contextuelles utilisées.
  • separator : le texte servant de séparateur.

Ce motif possède les variables contextuelles suivantes :

  • entry_id : si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page courante. Sinon, la variable est ignorée.
  • entry_title : si le contexte le permet, cette variable contient le titre de la publication associée à la page courante. Sinon, la variable est ignorée.
  • page_number : si le contexte le permet, cette variable contient le numéro de la page courante. Sinon, la variable est ignorée.
  • path : contient le chemin relatif de la page courante.

.:GetNextPage::string:.

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

  • string : le texte à formater, contenant les valeurs des variables contextuelles utilisées.

Ce motif possède les variables contextuelles suivantes :

  • entry_id : si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page suivante. Sinon, la variable est ignorée.
  • entry_title : si le contexte le permet, cette variable contient le titre de la publication associée à la page suivante. Sinon, la variable est ignorée.
  • page_number : si le contexte le permet, cette variable contient le numéro de la page suivante. Sinon, la variable est ignorée.
  • path : contient le chemin relatif de la page suivante, si elle existe.

.:GetPreviousPage::string:.

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

  • string : le texte à formater, contenant les valeurs des variables contextuelles utilisées.

Ce motif possède les variables contextuelles suivantes :

  • entry_id : si le contexte le permet, cette variable contient l'identifiant de la publication associée à la page précédente. Sinon, la variable est ignorée.
  • entry_title : si le contexte le permet, cette variable contient le titre de la publication associée à la page précédente. Sinon, la variable est ignorée.
  • page_number : si le contexte le permet, cette variable contient le numéro de la page précédente. Sinon, la variable est ignorée.
  • path : contient le chemin relatif de la page précédente, si elle existe.

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

.:GetRelativeOrigin:.

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 :

../../../

.:GetRootPage:.

Ce motif renvoie le chemin relatif vers la page principal du blog qui correspond généralement au fichier index.html et qui devrait se trouver à la racine de votre site.

Générateurs de code HTML

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

  • input_code : le code source que vous souhaitez formater.
  • language : indique le langage du texte d'entrée. La liste des langages supportés par Pygments est disponible ici. Si vous ne souhaitez pas coloriser le texte d'entrée, utilisez la valeur "Text".
  • line_numbers: il s'agit d'un booléen indiquant à VenC si vous souhaitez générer le numéro des lignes dans le rendu.

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>

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, détaillé plus bas dans ce chapitre.

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

.__VENC_PYGMENTIZE_WRAPPER__ > div
	{background-color: rgba(0,0,0,0.5);
	color: #FFF;
	font-size: 0.8em;
	padding:5px;
	border-bottom: 1px solid rgba(255,255,255,0.25);
	border-radius: 5px;}
    
.__VENC_PYGMENTIZE_WRAPPER__ > div
	{font-size: 1em;
	margin-left: 15px;
	margin-right: 15px;}

.__VENC_PYGMENTIZE_WRAPPER__ > div pre
	{overflow: hidden;
	margin-top: 0px;
	margin-left: 15px;
	margin-right: 15px;
	margin-bottom: 0px;}

Il est important que le style ainsi définit soit inclut dans header.html APRÈS utilisation du motifs GetStyleSheets.

.:CodeHightlightInclude::language::line_numbers::input_code_file:.

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 inclut n'est pas traité par le moteur de motifs de VenC.

.:GetStyleSheets:.

Comme on l'a vu précédement, 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" />

.:Latex2MathML::latex_code:.

Ce motif vous permet de générer du code MathML converti depuis le très populaire langage LaTeX. Ainsi, vous pouvez facilement inclure dans votre publication des formules mathématiques.

Cette fonctionnalité dépend d'une librairie tierce, indépendante de VenC. En cas de problème ou de difficulté vous pourriez vouloir signaler un bug sur la page du projet latex2mathml.

Le seul argument du motif est :

  • latex_code : le code source LaTeX de la formule que vous souhaitez intégrer.

Par exemple :

.:Latex2MathML:: \overline{z^{n+1}} = {\overline{z}}^{n+1}:.

Produirait le code suivant :

<math display="inline" xmlns="http://www.w3.org/1998/Math/MathML">
    <mrow>
        <mover>
            <mrow>
                <msup>
                    <mi>z</mi>
                    <mrow>
                        <mi>n</mi>
                        <mo>&#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>

.:SetColor::input_text::color:.

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

  • input_text : le texte à formater. Peut contenir d'autres motifs.
  • color : la couleur désirée telle que spécifiée par CSS.

Par exemple

.:SetColor::Texte de couleur rouge::red:.

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 class __VENC_TEXT_COLOR__ ce qui permet plus de contrôle lors de la mise en page de votre blog.

.:SetStyle::tag_id::tag_class::content:.

Ce motif permet d'assigner un id et une class CSS à une paire de balises span ajoutée par VenC pour encapsuler le texte passé en paramètre.

Ce motif prend donc trois paramètres :

  • tag_id : le nom de l'id CSS à assigner au texte.
  • tag_class : le nom de la classe CSS à assigner au texte.
  • content : le texte auquel vous souhaitez appliquer un style CSS.

Par exemple :

.:SetStyle::mon_id::ma_class::Un texte quelconque à formater. :.

Produirait :

<span id="ma_class" class="ma_class">Un texte quelconque à formater.</span>

.:Table[::item1][::item2][...]:.

Ce motif permet d'organiser du contenu dans un tableau. Le motif a un nombre illimité d'arguments. Chaque argument correspond au contenu d'une cellule.

Quand VenC détect 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.