Structure et configuration d'un projet

Dans cette partie nous verrons comment sont organisés les fichiers d'un projet VenC, comment ceux-là sont structurés et comment configurer tout ça.

Arborescence

La racine du projet porte le nom du blog, par exemple, "MooFooBar". Lorsque vous créez un nouveau projet, VenC produit un certain nombre de répertoires listés ci-dessous.

  • blog : le dossier où est exporté le projet.
  • extra : un dossier contenant des ressources quelconques copiées vers blog/ au moment de l'exportation.
  • entries : contient toutes les publications sous forme de fichiers textes numérotés et datés.
  • theme : contient les templates HTML, les feuilles de style et éventuellement les scripts JS.
  • templates : contient des modèles vierges pour de futurs publications.
  • includes : ce répertoire contient des fichiers HTML que vous pouvez inclure n'importe où dans votre projet avec la fonction IncludeFile.
  • caches : ce répertoire n'est pas généré automatiquement à la création de votre projet. Mais il peut apparaître plus tard, notamment si vous utilisez la fonction GetEmbedContent.

Fichier de configuration principal

blog_configuration.yaml est un document YAML à la racine du projet définissant les propriétés du blog, comme son titre, le nom de son auteur, ainsi que des détails fonctionnels comme le nombre de publications par pages ou l'ordre d'affichage de celles-ci.

Immédiatement après avoir créé votre blog, il s'agira sans doute du premier fichier que vous éditerez. Après avoir rempli ces champs, dont l'usage est détaillé ci-dessous, vous n'aurez normalement plus besoin d'y revenir.

blog_name

Sans surprise, il s'agit du titre de votre blog.

disable_threads

Empêche VenC de générer les fils de publications spécifiés dans une liste. Les noms de fils peuvent appartenir à des catégories ou à des archives. Ces noms sont listés en étant séparés par une virgule.

disable_archives

Empêche VenC de générer les fils de publications des archives. Ce champ est un booléen, fixé à False par défaut.

disable_chapters

Empêche VenC de générer les chapitres. Ce champ est un booléen, fixé à True par défaut.

disable_categories

Empêche VenC de générer les fils de publications des catégories. Ce champ est un booléen, fixé à False par défaut.

disable_single_entries

Empêche VenC de générer les publications individuelles. Ce champ est un booléen, fixé à False par défaut.

disable_main_thread

Empêche VenC de générer le fil principal de publication. Ce champ est un booléen, fixé à False par défaut.

disable_rss_feed

Empêche VenC de générer un flux RSS. Ce champ est un booléen, fixé à False par défaut.

disable_atom_feed

Empêche VenC de générer un flux Atom. Ce champ est un booléen, fixé à False par défaut.

text_editor

L'éditeur de texte choisi pour éditer une nouvelle publication du blog.

date_format

"%A %d. %B %Y" par défaut. Définit le format de date utilisé à l'intérieur du blog. Le format des dates est en fait le même que celui utilisé par Python. Pour en savoir plus sur ce format, rendez vous ici.

author_name

Le nom de l'administrateur ou l'auteur du blog.

blog_description

Un très court résumé de ce dont parle votre site.

blog_keywords

Les mots-clefs associés au site, séparés par une virgule.

author_description

Un court texte à propos de l'auteur du blog.

license

La licence appliquée au contenu de votre site.

blog_url

L'URL du blog. Peut être laissée vide, selon le thème utilisé.

ftp_host

Optionel. Il s'agit du nom d'hôte de votre serveur FTP, s'il existe.

blog_language

Définit la langue du site.

author_email

Votre adresse e-mail.

code_highlight_css_override

Génère à nouveau le code CSS créé par le module Pygments. Ce champ est un booléen, fixé à False par défaut. Attention si ce champ est fixé à True, à chaque exportation de votre blog, les anciens codes CSS créés par Pygments seront écrasés.

path

Il s'agit d'une variable contenant différents chemins, vous ne devriez normalement pas avoir besoin d'y toucher. La liste de ces chemins est détaillée ci-dessous.

ftp

Le chemin absolu du répertoire de destination sur votre serveur FTP.

entries_sub_folders

Le nom de sous-répertoire qui contiendra les publications individuelles.

categories_sub_folders

Le nom du sous-répertoire qui contiendra les catégories

index_file_name

"index{page_number}.html" par défaut. Spécifie le nom de fichier des pages d'un fil de publication. Devrait toujours contenir la variable {page_number}.

category_directory_name

"{category}" par défaut. Définit le répertoire où sera exporté le fil de publication de la catégorie courante. Ce champ devrait donc toujours contenir la variable {category}.

chapter_directory_name

"{chapter_name} par défaut. Définit les noms de répertoire où seront exportés les chapitres, s'il en existe. Ce champ devrait donc toujours contenir la variable {chapter_name}.

archives_directory_name

"%Y-%m" par défaut. Définit le format de date utilisé pour les noms de répertoires des archives. Le format des dates est en fait le même que celui utilisé par Python. Pour en savoir plus sur ce format, rendez vous ici.

entry_file_name

"entry{entry_id}.html" par défaut. Définit le nom de fichier d'une publication unique.

rss_file_name

"rss.xml" par défaut. Définit le nom de fichier du flux RSS.

atom_file_name

"atom.xml" par défaut. Définit le nom de fichier du flux Atom.

entries_per_pages

10 par défaut. Définit le nombre de publications par page.

columns

1 par défaut. Ce champ définit le nombre de colonnes dans une page.

feed_lenght

5 par défaut. Définit le nombre de publications à afficher dans le flux RSS.

reverse_thread_order

Ce champ est un booléen, fixé à True par défaut. Définit l'ordre de publication. Du plus récent au plus ancien (True), ou l'inverse (False).

markup_language

Ce champ spécifie le langage de balisage par défaut utilisé dans toutes les publications. Cette valeur peut cependant être localement écrasée dans l'entête d'une publication.

Les valeurs possibles de ce champ sont :

  • Markdown
  • reStructuredText
  • none

path_encoding

Permet de spécifier l'encodage des chemins générés par VenC. Utile dans certains cas, quand un ou plusieurs liens internes contiennent des accents ou des caractères spéciaux mal supportés par le serveur hôte. Ce champ n'a pas de valeur par défaut.

server_port

Spécifie le port du server HTTP local. Ce champ est fixé à 8888 par défaut.

sort_by

Pour être ordonnées, les publications sont généralement évaluées selon la valeur de leur identifiant. C'est pourquoi la valeur de ce champ est 'id' par défaut. Il est possible de spécifier le nom d'une autre propriété pour les publications.

Les valeurs possibles sont :

  • authors
  • date
  • filename
  • formatted_date
  • id
  • tags
  • title

Vous pouvez également spécifier le nom d'une métadonnée définie manuellement dans l'entête de vos publications.

enable_jsonld

Active la création de fichier JSON-LD pour le référencement à l'aide des technique du web sémantique. Ce champ est un booléen qui vaut False par défaut. Selon la taille de votre blog, ces fichiers peuvent vite prendre de la place.

enable_jsonp

Active la création de fichier JSON-P contenant des données jsonld pour le moteur de recherche décentralisé côté client. Il s'agit d'une fonctionnalité expérimental. Ce champ est un booléen qui vaut False par défaut. Selon la taille de votre blog, ces fichiers peuvent vite prendre de la place.

Les publications

Une publication est un fichier dans lequel vous allez pouvoir rédiger votre contenu. Cela peut-être un billet d'humeur ou d'opinion, un article de fond, une galerie d'images, etc. Pour faciliter l'édition de votre blog avec VenC, vous êtes fortement encouragé à utiliser des templates.

Le nom de fichier d'une publication est formaté de la façon suivante :

<id>__<mois>-<jour>-<année>-<heure>-<minute>__<titre>

Une publication contient une première partie au format YAML contenant les métadonnées de la publication, puis une seconde au format Markdown qui contiendra la publication à proprement parler. Cette seconde partie est elle-même scindée en deux. L'une contiendra la prévisualisation de la publication, et l'autre son véritable contenu.

Une publication vierge se présente de la façon suivante:

authors: ''
categories: ''
tags: ''
title:
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---

Métadonnées

Il y a donc quatre champs qu'il est possible de compléter.

authors

C'est la liste des auteurs de la publication, séparés par une virgule. Par exemple : Denis Salem, Benjamin Bayard, Richard Stallman.

categories

C'est la liste des catégories de la publication, séparées par une virgule. Vous pouvez également avoir des sous-catégories pour une publication qui définiront ensuite un arbre de catégories. Pour définir une sous-catégories il faut séparer la catégorie parente de la catégorie fille par ' > '. Ce procédé peut être répété autant de fois que nécessaire. Par exemple : Metal > Copper, Metal > Steel > Properties, Materials.

tags

C'est la liste des mots-clefs de la publication, séparés par une virgule. Par exemple : Libre, Open-source, Linux.

title

C'est le nom de votre publication, tel que vous l'avez définit au moment de créer la publication avec la commande : venc -ne .

Métadonnées optionnelles

Il est également possible de rajouter librement des champs optionnels. Il y a cependant deux champs réservés :

chapter

Indique à quel chapitre correspond la publication. La convention qu'utilise VenC pour reconnaître les chapitres est la suivante : chaque chapitre et chaque sous-partie sont numérotés, et séparés par un point. Quelques exemples pour aider à visualiser le truc.

  • '2' : indique que la publication correspond au chapitre deux.
  • '1.2' : indique que la publication correspond au premier chapitre, seconde sous-partie
  • '3.3.5' : indique que la publication correspond au troisième chapitre, troisième sous-partie, cinquième sous-partie de la partie parente.

Important : le champ chapter doit explicitement être une chaîne de caractères. Pour ce faire, l'index du chapitre doit être entre guillement.

markup_language

Il est possible de spécifier un langage de balisage qui sera utilisé pour la publication courante, en lieu et place du langage définit dans le fichier de configuration du blog.

VenC supporte deux langages de balisage :

  • Markdown : qui est le langage par défaut.
  • reStructuredText : un peu plus complet et puissant que Markdown.
  • none : Le langage de balisage est désactivé. Permet d'incorporer de l'HTML/CSS dans une publication.

Métadonnée

Il est possible d'ajouter aux publications et au fichier de configuration principal des métadonnées supplémentaires.

Type de métadonnées

Il y a trois type possibles de métadonnées pour Venc.

Chaîne de caractères

C'est le type par défaut de la plupart des métadonnées. Par exemple :

free_artist: 'Revolution Void'

Liste de chaînes de caractères

C'est le type par défaut des champs tags et authors. Il s'agit d'une liste d'éléments formatés selon la convention de YAML.

Il peut s'agir d'une liste explicite :

liste_de_chose_à_faire: ['Devenir un dieu de la prog', 'Niquer le capitalisme', 'Assassiner Hitler']

Ou bien d'une chaîne de caractères qui peut être convertie en liste si nécessaire :

liste_de_chose_à_faire: 'Devenir un dieu de la prog, Niquer le capitalisme, Assassiner Hitler'

Pour ce faire, la liste est créée en utilisant les virgules comme séparateurs.

Dictionnaire de données

Ce type n'est utilisé qu'en interne par VenC, et pour le moment l'utilisateur a très peu d'intérêt à le manipuler. Il se présente comme spécifié par le format YAML. Par exemple :

mon_dico:
    bidule: 'kekchose'
    trucs: ['machin', 'chose']
    sous_dico:
        autre_bidule: 'trucmuche'
        autre_trucs: ['moo','foo','bar']

Les templates

Un template est en fait une publication vierge qui a cependant été préformatée pour contenir des choses redondantes à rédiger ou à programmer manuellement. Typiquement, pour une galerie, vous pourriez vouloir un template qui contiendrait déjà la ou les balises Markdown pour inclure une ou plusieurs images, les champs categories et tags préremplis, etc.

Par exemple :

authors: 'Denis Salem'
categories: 'Photographies > Nature'
tags: 'Forêt, Champignons'
title: Champignons trop mignons (Mais pas commestible, alors calme toi)
---VENC-BEGIN-PREVIEW---
---VENC-END-PREVIEW---
![.:GetEntryTitle:.]( ".:GetEntryTitle:.")

VenC est livrés avec des exemples de templates. En voici la liste :

  • example_code_highlight
  • example_Escape
  • example_Latex2MathML
  • markdown_example_footnotes
  • tessellation_example_display_title_in_entry
  • tessellation_example_display_title_in_threads

Parmi ces templates, certains servent surtout à illustrer l'usage de certaines fonctionnalités de VenC.

Pour utiliser un template il suffit de passer son nom de fichier (sans le chemin) à VenC au moment de la création d'une nouvelle publication. Par exemple :

jeanrochefort@anonymous ~ $ venc -ne "Amanite tue-mouches" champignons_magiques

VenC va d'abord essayer de trouver votre template dans le répertoire templates de votre blog. Sinon, il essayera de le trouver parmi ceux prédéfinis et listés plus haut.

Les Thèmes

Un thème est l'ensemble des fragments qui seront assemblés et interprétés par VenC pour former votre blog, c'est dans un thème que sera définit la mise en page de votre site. Typiquement, un thème est un répertoire contenant au moins le dossier chunks et un autre, optionel, assets.

  • assets : contient des ressources nécessaires à la mise en page ou au fonctionnement du blog. Cela peut être des images, des feuilles de style CSS ou des scripts JS. Vous pouvez également y entreposer des librairies comme JQuery ou Bootstrap.

  • chunks : doit contenir les fichiers suivant :

    • header.html
    • entry.html
    • footer.html
    • rssHeader.html
    • rssEntry.html
    • rssFooter.html
    • audio.html
    • video.html
  • config.yaml : Un fichier de configuration YAML permettant d'indiquer les dépendances du thème, supplanter des options de configuration et décrire le thème. Plus d'infos plus bas dans ce chapitre.

Comme vous l'avez sans doute compris, VenC met bout à bout les morceaux de votre blog en formattant l'entête (header.html) et en répétant un certain nombre de fois l'opération qui consiste à formater le morceau qui définit une publication (entry.html) pour la publication courante. La page courante est alors terminée en y ajoutant le morceau pied de page (footer.html) également formaté.

C'est exactement le même principe pour le flux RSS, qui est construit de façon identique.

Il n'est pas forcément évident de créer un thème de toute pièce et vous n'avez peut-être pas envie de perdre trop de temps à tester le fonctionnement de tout ça. Le meilleur moyen de créer un thème soi-même est de jeter un œil au thème dummy normalement installé avec VenC dans :

~/.local/share/VenC/themes/dummy

Ce thème en l'état n'est pas utilisable, mais c'est une solide base pour créer le vôtre. Le style CSS reste à définir, et vous pourriez vouloir réorganiser les éléments de la page.

Une autre approche est de regarder comment sont construits d'autres thèmes. Ceux-là seront ajoutés au fur et à mesure sur les repositories git de VenC.

Vous pouvez également vous aider de la partie Tutoriels, dans laquelle sont décrites des techniques pour réaliser des mises en pages très spécifiques et pour lesquelles l'utilisation du langage de balisage interne de VenC sera illustrée.

Configuration d'un thème

Il s'agit d'un fichier de configuration au format YAML qui accompagne chaque thème installable dans le blog avec la commande :

jeanrochefort@anonymous ~ $ venc --intall-theme

Ce fichier s'appel config.yaml et est structuré de la façon suivante :

info:
    description : ''
    
override:
    whatever_field_1: 'whatever_value'
    whatever_field_2: 'whatever_value2'
    ...

assets_dependencies: ['awesome.css','not_so_shitty_script.js',]

includes_dependencies: ['source_code.example','whatever_you_want.file']
  • info : ce champ contient les métadonnées du thème.
    • description : il s'agit d'un cours texte présentant le thème.
    • version : optionnel. Indique la version du thème.
    • author : optionnel. Indique le ou les auteurs du thème.
  • override : Ce champ est optionnel et contient les propriétés remplaçant ou s'ajoutant au fichier de configuration principal. Typiquement, un thème qui fonctionne avec trois colonnes, par exemple, devra inclure le champ 'columns' ayant la valeur 3.
  • assets_dependencies : il s'agit d'une liste contenant les assets (images, feuilles de styles, scripts) contenu dans ~/.local/share/VenC/themes_assets. C'est notamment utile pour inclure des modules VenC Javascript.
  • includes_dependencies : comme pour le champ précédent, il s'agit d'une liste contenant des noms de fichiers. Il s'agit de fichiers HTML à inclure avec .:IncludeFile:: ... :.. Ces fichiers sont installés par défaut avec VenC et se trouve dans ~/.local/share/VenC/themes_includes.

Paramétrage des thèmes par défaut

Les thèmes par défaut sont partiellement personnalisables à l'aide de variables à définir dans votre fichier de configuration principal.

Academik

  • header_image : nom de fichier de l'image servant d'en-tête au blog. L'image doit être localisée à la racine du blog.
  • disable_infinite_scroll: booléen indiquant si le défilement infini doit être désactivé ou non.
  • author_avatar : nom de fichier de l'image servant d'avatar de l'auteur. L'image doit être localisée à la racine du blog.
  • loading_image : nom de fichier de l'image servant d'icône de chargement pour le défilement infini. L'image doit être localisée à la racine du blog.
  • override_theme_css_with : nom d'un fichier css à placer dans extra/ (il sera automatiquement exporté à la racine de votre blog). Si cette variable est définie, le fichier ainsi référencé sera utilisé comme style CSS en plus de l'existant.

Gentle

  • header_image : nom de fichier de l'image servant d'en-tête au blog. L'image doit être localisée à la racine du blog.
  • disable_infinite_scroll: booléen indiquant si le défilement infini doit être désactivé ou non.
  • loading_image : nom de fichier de l'image servant d'icône de chargement pour le défilement infini. L'image doit être localisée à la racine du blog.
  • override_theme_css_with : nom d'un fichier css à placer dans extra/ (il sera automatiquement exporté à la racine de votre blog). Si cette variable est définie, le fichier ainsi référencé sera utilisé comme style CSS en plus de l'existant.

Tessellation

  • header_image : nom de fichier de l'image servant d'en-tête au blog. L'image doit être localisée à la racine du blog.
  • disable_infinite_scroll: booléen indiquant si le défilement infini doit être désactivé ou non.
  • loading_image : Nom de fichier de l'image servant d'icône de chargement pour le défilement infini. L'image doit être localisée à la racine du blog.
  • override_theme_css_with : nom d'un fichier css à placer dans extra/ (il sera automatiquement exporté à la racine de votre blog). Si cette variable est définie, le fichier ainsi référencé sera utilisé comme style CSS en plus de l'existant.

Modules Javascript

VenC fournit quelques modules Javascript qui sont utilisés dans les thèmes par défaut, mais que vous pouvez utiliser dans vos thèmes à vous. Ce chapitre présente ces modules et en explique le fonctionnement.

Chargeur de scripts JS

Avant tout chose, il convient de prendre connaissance du chargeur de script.

Dans le cas où vous souhaiteriez écrire votre script pour un thème de votre confection, il est fortement recommandé de l'exécuter à l'aide de VenC-Scripts-Bootstrap-x.y.z.js (x.y.z étant la version disponible avec la distribution de VenC que vous possédez).

Ce script déclenche l'effet des modules JS quand la page est chargée.

var VENC_ON_LOAD_CALLBACK_REGISTER = [];

function VENC_ON_LOAD_CALLBACK() {
    var i;
    for (i = 0; i < VENC_ON_LOAD_CALLBACK_REGISTER.length; i++) {
        VENC_ON_LOAD_CALLBACK_REGISTER[i]();
    }
}

window.onload = VENC_ON_LOAD_CALLBACK

Pour fonctionner, VenC-Scripts-Bootstrap-x.y.z.js doit être le premier script appelé dans votre page.

<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
<script type="text/javascript" src=".:GetRelativeOrigin:.Mon-Module-Trop-Badass.js"></script>

Ce module définit la variable VENC_ON_LOAD_CALLBACK_REGISTER accessible depuis les autres scripts que vous importez dans votre page. Il s'agit d'une liste de callbacks s'exécutant quand window.onload est appelé.

Typiquement, à la fin de votre script, pour que son effet se déclenche, ajoutez votre callback comme ci-dessous :

VENC_ON_LOAD_CALLBACK_REGISTER.push(LE_CALLBACK_DE_MON_SUPER_MODULE_JS);

Défilement infini

Ce module Javascript permet de charger automatiquement les pages du blog quand vous arrivez à la fin de la page courante.

Inclure le défilement infini dans votre page

Pour pouvoir utiliser ce module, vous devez inclure dans le fichier header.html de votre thème deux scripts :

  • VenC-Scripts-Bootstrap-x.y.z.js : ce script est obligatoire pour faire fonctionner n'importe quel module.
  • VenC-Infinite-Scroll-x.y.z.js : il s'agit du script permettant le défilement infini. Il doit être inclus après VenC-Scripts-Bootstrap.

Pour connaître la version disponible de ces scripts sur votre système, vous pouvez jeter un œil au répertoire où ceux-là sont normalement installés.

ls ~/.local/share/VenC/themes_assets/

Une bonne façon de faire est d'inclure ces deux scripts de la façon suivante :

<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-x.y.z.js"></script>

.:IfInfiniteScrollEnabled::
    .:IfInThread::
        <script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Infinite-Scroll-x.y.z.js"></script>
    ::

    :.
:.
  • IfInThread permet de n'inclure le script que si le contexte l'exige, ce qui permet de ne pas alourdir la page inutilement. Si dans votre thème vous prévoyez de n'utiliser que le module de défilement infini, alors vous pouvez déplacer le code incluant VenC-Scripts-Bootstrap dans le premier argument de IfInThread.
  • Si vous prévoyez de distribuer votre thème, le pattern IfInfiniteScrollEnabled permet d'activer / désactiver l'inclusion du module depuis le fichier de configuration principal de votre blog à l'aide de la variable booléenne disable_infinite_scroll.

Inclure le défilement infini dans votre thème.

Il y a deux façons de procéder :

  • Vous pouvez copier le module et sa dépendance dans le répertoire assets de votre thème depuis ~/.local/share/VenC/themes_assets. C'est cette méthode qui est recommandée.
  • Vous pouvez définir un fichier de configuration de thème dans lequel vous indiquez les noms de fichier des modules que vous souhaitez voir être exporté pendant la génération de votre blog.

Structure d'une page

Pour que le défilement infini fonctionne, votre thème doit être structuré d'une certaine manière que nous allons détailler ici.

Les exemples ci-dessous constituent un code minimal pour faire fonctionner le défilement infini. Il manque, évidemment, de nombreuses choses pour que votre thème soit pleinement opérationnel.

header.html

Comme nous l'avons vu, il faut que les scripts soient inclus dans le fichier header.html. Idéalement de la façon suivante :

<!DOCTYPE html>
<html>
    <head>
        <!-- Insérer ici tout un tas de truc utile, genre les balises meta, title, les feuilles de styles... -->
        <script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
        .:IfInfiniteScrollEnabled::
            .:IfInThread::
                <script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Infinite-Scroll-x.y.z.js"></script>
            ::
        
            :.
        :.
    </head>
    <body>
        <header>
            <!-- Les en-têtes de votre page, une bannière, un menu déroulant, un nuage de tags. Tout ce que vous voulez. -->
        </header>
        <div id="__VENC_THREAD__">

entry.html

Chaque bloc contenant une publication doit avoir la class "entry". Sinon, le script de défilement infini n'est pas capable de reconnaître les publications qu'il doit charger.

            <div class="entry>
                <!-- Contenu de la publication -->
            </div>

footer.html

Ici il y a trois éléments à considérer qui devrait se trouver dans footer.html mais qui, si votre design de mise en page l'exige, pourrait se trouver dans header.html. Chaque élément ne devrait être présent qu'une et une seule fois dans la page.

  • __VENC_LOADING__ : cet élément est optionnel, dans notre exemple, il s'agit d'une image, mais ce pourrait être n'importe quoi d'autre faisant office d'animation de chargement.
  • __VENC_NAVIGATION__ : il s'agit de l'élément contenant les liens de navigation. Quand le défilement infini est activé, par défaut cet élément est rendu invisible.
  • data-venc-api-infinite-scroll-hook : l'élément permettant au script de connaître la page suivante. Ce n'est pas nécessairement un lien, mais dans la pratique, c'est plus commode que ce soit le cas. Ce qui compte c'est qu'il a l'attribut data-venc-api-infinite-scroll-hook dont la valeur correspond au chemin de la page suivante. Cette valeur est accessible avec le pattern GetNextPage.
        </div> <!-- fin du bloc __VENC_THREAD__ -->
        .:GetBlogMetadataIfExists::
            loading_image
        ::
            <img id="__VENC_LOADING__" src=".:GetRelativeOrigin:.{value}" />
        :.
        <footer>
            <div id="__VENC_NAVIGATION__">
                <!-- Insérer ici des patterns VenC permettant de générer les liens de navigations -->
                .:GetNextPage:: <a id="next" href="{path}" data-venc-api-infinite-scroll-hook="{path}"></a>:.
            </div>
        </footer>
    </body>
</html>

Personnaliser le défilement infini

VenC fourni une API pour personnaliser le défilement infini. Pour cela, vous pouvez modifier les attributs de la variable globale VENC_INFINITE_SCROLL

hideVenCNavigation

hideVenCNavigation: true

Normalement, les liens de navigation (numéro de page, page suivante/précédente) contenus dans l'élément ayant l'id __VENC_NAVIGATION__ sont désactivés pour le défilement infini. Mais il est possible de ne pas le faire et laisser ces éléments visibles en changeant la valeur de cette variable.

interval

interval: 250

Cette variable définit le temps, en milliseconde, entre chaque test visant à savoir si la fin de la page a été atteinte et donc s'il faut charger la suite. La valeur par défaut est 250 millisecondes.

imageDefaultSetup

imageDefaultSetup: function(img) {}

Cette méthode ne fait rien par défaut, mais permet si vous souhaitez la redéfinir de configurer l'était initial des images dans une publication au moment où celle-ci est chargé dans le DOM.

entryDefaultSetup

entryDefaultSetup: function(entry) {
    entry.style.opacity = "0.0";
}

Cette méthode permet d'initialiser l'état d'une publication au moment où elle est chargée dans le DOM. Par défaut, les publications sont invisibilisées.

onLoadImage

onLoadImage : function(img) {}

Par défaut, cette fonction ne fait rien de particulier, mais permet si vous souhaitez la redéfinir, de configurer l'état ou l'animation d'apparition d'une image au moment où son téléchargement est terminé.

onLoadEntry

onLoadEntry : function(entry){
    entry.style.transition = "opacity 0.5s ease";
    entry.style.opacity = "1.0";
}

dontWait

dontWait: false

Par défaut, VenC attend que la page en cours de chargement soit entièrement téléchargée avant de récupérer la suivante. Il est possible en changeant la valeur de cette variable à True, de charger plusieurs pages en même temps, ce n'est cependant pas recommandé.

loading

Quand le chargement d'une page est en cours, le script rend par défaut visible l'icône de chargement de la page, si l'élément HTML ayant pour id __VENC_LOADING__ existe. Cet élément est passé en argument à la fonction suivante, qu'il est possible de redéfinir.

loading : function(loading_image) {
    loading_image.style.opacity = "1.0";
}

idle

Quand le chargement est inactif, le script rend par défaut invisible l'icône de chargement de la page, si l'élément HTML ayant pour id __VENC_LOADING__ existe. Cet élément est passé en argument à la fonction suivante, qu'il est possible de redéfinir.

idle : function(loading_image) {
    loading_image.style.opacity = "0.0";
}

Arbre

Ce module Javascript permet d'animer et de condenser une liste hiérarchique de catégories ou une table des matières qui auraient été générés avec un pattern VenC.

En effet, si la liste d'éléments contenue dans l'un de ces types d'objets est très longue, ce peut être visuellement rédhibitoire. Ce module permet donc de plier/déplier les sous-parties d'une liste comme c'est le cas ici pour la table des matières de cette documentation.

Inclure le module arbre dans votre page.

Pour pouvoir utiliser ce module, vous devez inclure dans le fichier header.html de votre thème deux scripts :

  • VenC-Scripts-Bootstrap-x.y.z.js : ce script est obligatoire pour faire fonctionner n'importe quel module.
  • VenC-Tree-x.y.z.js : il s'agit du script permettant d'animer un arbre d'éléments. Il doit être inclus après VenC-Scripts-Bootstrap.

Pour connaître la version disponible de ces scripts sur votre système, vous pouvez jeter un œil au répertoire où ceux-là sont normalement installés.

ls ~/.local/share/VenC/themes_assets/

Une bonne façon de faire est d'inclure ces deux scripts de la façon suivante :

<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
.:IfCategories::
    <script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Tree-x.y.z.js"></script>
:.

Dans cet example, on supose que l'on souhaite appliquer le module à une liste hiérarchique de catégories. On utilise donc le pattern IfCategories pour n'inclure le module que si c'est nécessaire. Si l'on avait souhaité utiliser le module pour rendre interactif une table des matières, on aurait utilisé le pattern IfChapters.

Précisons également que si vous n'avez pas prévu d'utiliser d'autre module que VenC-Tree-x.y.z.js dans votre thème, vous pouvez passer la ligne d'inclusion de VenC-Bootstrap-x.y.z.js en paramètre de IfCategories ou IfChapters.

Inclure le module arbre dans votre thème.

Il y a deux façon de procéder :

  • Vous pouvez copier le module et sa dépendance dans le répertoire assets de votre thème depuis ~/.local/share/VenC/themes_assets. C'est cette méthode qui est recommandée.
  • Vous pouvez définir un fichier de configuration de thème dans lequel vous indiquez les noms de fichier des modules que vous souhaitez voir être exportés pendant la génération de votre blog.

Structure d'une liste hiérarchique

Dans la pratique, vous souhaitez appliquer le module arbre à des listes hiérarchiques générées par VenC ; soit avec le pattern GetChapters ou TreeForBlogCategories.

Commençons par observer que l'utilisation de ces deux patterns présentent des similarités :

<!-- TreeForBlogCategories (TreeForEntryCategories run similarly) -->
<div class="__VENC_TREE_ROOT__">
    .:TreeForBlogCategories::
        <ul class="__VENC_TREE_NODE__">
    ::
        <li><a href="{path}" title="{count} publications">{value}</a>
    ::
        </li>
    ::
        </ul>
    :.
</div>

<!-- GetChapters -->
<div class="__VENC_TREE_ROOT__">
    .:GetChapters::
        <ul class="chapter-level{level} __VENC_TREE_NODE__">
    ::
        <li>{index}. <a href="{path}">{title}</a>
    ::
        </li>
    ::
        </ul>
    :.
</div>

Entre autres choses, dans l'un ou l'autre pattern :

  • Le premier argument contient toujours le tag <ul> ouvrant le nœud courant.
  • Le second argument contient toujours le tag <li> ouvrant de la branche courante.
  • Le troisième argument contient toujours le tag </li> fermant de la branche courante.
  • Le quatrième argument contient toujours le tag </ul> fermant le nœud courant.

En particulier, pour que le module arbre fonctionne sur les listes hiérarchiques ciblées :

  • Le pattern générant la liste hiérarchique est toujours contenu dans un élément ayant la classe __VENC_TREE_ROOT___
  • L'élément <ul> a toujours au moins une classe __VENC_TREE_NODE___

Personnaliser le module arbre

Chaque élément d'une liste hiérarchique se voit assigner un petit bouton qu'il est possible de définir soi-même.

  • Pour un élément dépliable, par défaut le bouton est le caractère +.
  • Pour un élément repliable, par défaut le bouton est le caractère -.
  • Pour un élement qui n'est ni dépliable, ni repliable, par défaut le bouton est et n'est pas cliquable.

Vous n'êtes pas obligé de définir un caractère, ce peut être du texte, ou des éléments HTML.

L'API définit une variable globale appelé VENC_TREE.

var VENC_TREE = {
    button_show: '+',
    button_hide: '-',
    button_disabled: '○'
}

Vous pouvez assigner la valeur que vous souhaitez à l'un de ses trois attributs de la façon suivante :

<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Scripts-Bootstrap-0.0.0.js"></script>
<script type="text/javascript" src=".:GetRelativeOrigin:.VenC-Tree-0.1.0.js"></script>
<script type="text/javascript">
    VENC_TREE.button_disabled = '';
</script>

L'exemple ci-dessus est extrait du code source du thème de cette documentation. La redéfinition des attributs de VENC_TREE doit se faire après avoir inclut dans votre page VenC-Tree-x.y.z.js et sa dépendance.

Contenu NSFW

Comme vous êtes un filou, vous pourriez vouloir mettre du contenu NSFW sur votre site. Mais vous êtes un filou responsable ; vous voulez avertir les visiteurs de votre site que celui-ci contient des choses à ne pas regarder en famille, ou au travail avec les collègues autour.

Les thèmes par défaut de VenC propose l'utilisation d'un fichier à inclure avec le pattern IncludeFile. Ce fichier c'est nsfw.html. Voilà comment il s'utilise :

.:IncludeFile::
    False
::
    nsfw.html
:: 
    .:GetEntryID:.
::
    Insérer ici votre contenu sensible dont vous souhaitez avertir le lecteur.
:.

Les paramètres importants ici sont le second et le troisième argument, respectivement nsfw.html et .:GetEntryID:..

  • nsfw.html : il s'agit du fichier à inclure. Il contient le code HTML nécessaire pour cacher/révéler le contenu sensible.

  • .:GetEntryID:. : cet argument définit l'identifiant CSS du block html à cacher/révéler. Si vous souhaitez dissimuler une publication entière, le mieux c'est d'utiliser, comme ici, l'identifiant de la publication.

Pour plus de détails sur le fonctionnement du pattern, rendez-vous ici.