4.6 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éfinie la mise en page de votre site. Typiquement, un thème est un répertoire contenant au moins le dossier chunks et un autre, optionnel, assets.

Comme vous l'avez sans doute compris, VenC met bout à bout les morceaux de votre blog en formatant l'entête (header.html), puis en répétant autant de fois qu'il y a de publications sur une page le formatage du corps de la publication (entry.html). La page courante est alors terminée en y ajoutant le 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 toutes pièces 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 concrete normalement installé avec VenC dans : $(venc -pp)/themes/concrete.

Ce thème en l'état offre un aperçu de ce qu'il est possible de faire avec VenC. C'est une solide base pour créer le vôtre.

Vous pouvez également vous aider des "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.

4.6.1 Configuration d'un thème

Lorsque vous créez votre thème, et si vous souhaitez le distribuer, il est possible et même recommandé de configurer le fichier config.yaml dans le répertoire racine de votre thème.

Comme le nom de fichier le laisse penser, il s'agit d'un fichier de configuration au format YAML. Celui-ci 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',]

4.6.2 Modules JavaScript

VenC fournit quelques modules JavaScript pour vous aider à mettre en page votre contenu. Ces scripts sont installés dans le dossier : $(venc -pp)/themes_assets

Ce chapitre présente ces modules et en explique le fonctionnement.

4.6.2.1 Chargeur de scripts JS

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

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=".:GetRelativeRoot:.VenC-Scripts-Bootstrap-x.y.z.js"></script>
<script type="text/javascript" src=".:GetRelativeRoot:.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);

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

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

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

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

    :.
:.

Inclure le défilement infini dans votre thème

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

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.

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>
        <script type="text/javascript" src=".:GetRelativeRoot:.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>

entry.html

Chaque bloc contenant une publication doit être de la classe "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>

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

        .: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 navigation -->
                .: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 millisecondes, 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 si vous le souhaitez vous pouvez y configurer l'était initial des images dans une publication au moment où celle-ci est chargée 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 le souhaitez 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";
}

Par défaut quand une publication est chargée, elle apparaît avec une petite animation de transparence. Vous pouvez redéfinir la fonction pour créer l'animation que vous souhaitez.

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";
}

4.6.2.3 Arbre

Ce module JavaScript permet d'animer et de condenser une liste hiérarchique de catégories ou une table des matières générées 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.

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 :

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

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

Dans cet exemple, on suppose 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'autres modules 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çons de procéder :

Structure d'une liste hiérarchique

Vous pouvez appliquer le module arbre à des listes hiérarchiques, qui sont générées par VenC avec le pattern GetChapters ou avec le pattern TreeForBlogCategories.

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

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

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

Personnaliser le module arbre

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

var VENC_TREE = {
    button_show: '+',
    button_hide: '-',
    button_disabled: '○',
    ul_style: function(ul) {}
}

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

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

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

<script type="text/javascript">
    VENC_TREE.button_disabled = '';
</script>

Il est également possible de redéfinir complètement le style CSS des listes ayant la classe __VENC_TREE_NODE__ avec ul_style. Par exemple :

<script type="text/javascript">
    VENC_TREE.ul_style = function(ul) {
        ul.style.listStyleType = "none";
    }
</script>

La redéfinition des attributs de VENC_TREE doit se faire après avoir inclus dans votre page VenC-Tree-x.y.z.js.

4.6.3 Thème par défaut

Usage

Pour vous faciliter la vie, VenC est livré avec au moins un thème qui peut vous servir de base pour créer le vôtre. C'est également idéal pour voir comment sont mis en pratique certains concepts de VenC. Quand vous installez VenC, ce thème est placé dans : $(venc -pp)/themes/concrete

Ce thème s'appelle concrete. Vous pouvez donc l'utiliser en générant votre site avec :

venc -xb concrete

Ou en l'installant localement dans votre projet avec la commande suivante :

venc -it concrete

L'avantage de cette dernière méthode étant qu'elle vous permet de modifier le thème en profondeur.

Configuration

Ce thème peut être adapté à vos besoins sans le modifier directement à l'aide d'une série de variables à définir dans votre fichier de configuration principal :

Affichage et contrôle des catégories

Les catégories sont gérées avec GetBlogCategoriesTreeFromBranches et GetFlattenedBlogCategoriesFromBranches, en conséquence le thème utilise une métadonnée obligatoire nommée taxonomy contenant une liste de sous-catégories à afficher.

Autres options