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 :