![]() Un générateur de site statique qui casse des briques. VenC est tellement rapide qu'il enfreint le principe de causalité et produit de l'énergie surunitaire ! |
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.
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);
Ce module Javascript permet de charger automatiquement les pages du blog quand vous arrivez à la fin de la page courante.
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
.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> :: :. :.
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
.IfInfiniteScrollEnabled
permet d'activer/désactiver l'inclusion du module depuis le fichier de
configuration principale de votre blog à l'aide de la variable booléenne disable_infinite_scroll
.Il y a deux façons de procéder :
$(venc -pp)/themes_assets
. C'est cette méthode qui est recommandée.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.
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>
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.
__VENC_LOADING__
: optionnel. L'élément ayant cet id
peut être une image ou n'importe quoi d'autre
faisant office d'animation de chargement.__VENC_NAVIGATION__
: il s'agit de l'id
de l'élément
contenant les liens de navigation. Quand le défilement infini est activé,
par défaut l'élément correspondant est rendu invisible.data-venc-api-infinite-scroll-hook
: l'élément ayant cet attribut permet 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 que l'élément possède 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
..: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>
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: 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: 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: 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: 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 : 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 : 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: 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é.
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"; }
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"; }
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.
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
.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
.
Il y a deux façons de procéder :
$(venc -pp)/themes_assets
. C'est cette méthode qui est recommandée si vous souhaitez distribuer votre thème.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 :
<ul>
ouvrant le nœud courant.<li>
ouvrant de la branche courante.</li>
fermant de la branche courante.</ul>
fermant le nœud courant.En particulier, pour que le module arbre fonctionne sur les listes hiérarchiques ciblées :
__VENC_TREE_ROOT__
.<ul>
a toujours au moins une classe __VENC_TREE_NODE__
.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.
+
et est défini dans button_show
.-
et est défini dans button_hide
.○
et n'est pas cliquable. Ce bouton est défini dans button_disabled
.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
.