Où placer les noisettes
Une noisette est un fichier HTML placée dans un sous-répertoire noisettes
situé dans le répertoire d’un plugin ou dans le répertoire squelettes
.
Pour être utilisée par le noiZetier, une noisette doit impérativement être accompagnée d’un fichier de configuration au format YAML [1].
Nommage des noisettes
Une noisette pouvant s’insérer sur n’importe quelle page sera nommée tout simplement nom_noisette.html
. Par convention, seuls les lettres minuscules et l’underscore (_) sont autorisés pour nom_noisette.
L’usage du tiret (-) est réservé pour spécifier les noisettes ne pouvant être incluses que sur une page spécifique et qui sont nommées nom_page-nom_noisette.html
. Ainsi, une noisette spécifique à la page article sera nommée article-nom_noisette.html
et le noiZetier ne la proposera que sur la page article et les compositions de la page article.
Au cas où une noisette ne devrait être proposée que sur une composition spécifique, elle sera nommée type-composition-nom_noisette.html
Décrire une noisette au format YAML
Pour bénéficier de toutes les possibilités offertes par le plugin Saisies ainsi que des vérifications offertes par le plugin Vérifier, il est nécessaire de décrire la noisette au format YAML.
Le fichier de configuration sera nommé de la même manière que la noisette. Seule son extension sera modifiée en .yaml
.
Exemple :
nom: '<:aveline:nom_menu:>'
description: '<:aveline:description_menu:>'
icon: 'images/menus-24.png'
necessite:
- 'menus'
contexte:
- 'id_rubrique'
- 'page'
parametres:
-
saisie: 'menu'
options:
nom: 'identifiant'
label: '<:aveline:label_identifiant_menu:>'
cacher_option_intro: 'oui'
obligatoire: 'oui'
-
saisie: 'oui_non'
options:
nom: 'afficher_titre_menu'
label: '<:aveline:label_afficher_titre_menu:>'
defaut: 'on'
nom
est obligatoire. Il indique le nom de la noisette à afficher dans l’interface de configuration. Peut être une chaîne de langue.
description
est facultatif. Permet de détailler ce que fait la noisette. Peut être une chaîne de langue.
icon
est facultatif. Il s’agit du chemin relatif à une image qui sera utilisée comme icône de la noisette.
parametres
est optionnel et permet de spécifier les paramètres configurables que l’on souhaite passer à la noisette.
Les paramètres sont dès lors décrits en suivant les spécifications du plugin Saisies. Il est alors possible de décrire finement un formulaire de configuration de la noisette.
Il est possible d’ajouter des vérifications à effectuer sur les valeurs des paramètres. Exemple :
-
saisie: 'input'
options:
nom: 'pas_pagination'
label: '<:aveline:label_pas_pagination:>'
defaut: 5
verifier:
type: 'entier'
options:
min: 1
contexte
permet de spécifier les variables de contexte à transmettre à la noisette. Si l’on ne doit transmettre qu’une seule variable, on pourra écrire
contexte: 'une_variable'
[2]. Si plusieurs variables doivent être transmises, on optera pour l’écriture suivante :
contexte:
- 'variable_1'
- 'variable_2'
- 'variable_3'
Si contexte
n’est pas spécifié, toutes les variables d’environnement seront transmises à la noisette. Il est également possible de spécifier explicitement que toutes les variables d’environnement doivent être transmises avec contexte: 'env'
.
Si aucune variable d’environnement ne doit être transmise à la noisette, on indiquera contexte: 'aucun'
.
necessite
est facultatif et permet de spécifier que cette noisette ne doit être proposée que si un plugin spécifique est activé. Cela peut être utilisé pour des noisettes fournies par un squelette compatible avec certains plugins sans les imposer.
Récupérer les paramètres de la noisette
Lors de l’inclusion de la noisette, le noiZetier transmet les paramètres en tant que variable d’environnement. Ceux-ci se récupèrent donc très facilement avec #ENV{param}
.
Le noiZetier transmet systématiquement à la noisette les variables d’environnement bloc
, type
et composition
.
Inclusion AJAX
Le noiZetier inclut les noisettes avec le critère {ajax}
. Il est donc possible d’utiliser des liens avec la classe ajax
. Voir la documentation de SPIP pour plus de détails.
Il est possible de spécifier au noiZetier qu’une noisette ne doit pas être inclue en AJAX. Pour cela, il suffit d’ajouter au YAML de la noisette la ligne suivante :
ajax: 'non'
Inclusion dynamique
Le noiZetier inclut par défaut les noisettes de manière statique. Elles n’ont donc pas de cache autonome mais le cache de la page englobante.
À partir de la version 0.12.0, il est cependant possible d’inclure dynamiquement une noisette. Cette dernière aura alors sa propre durée de cache définie avec la balise #CACHE
au début du fichier HTML de la noisette. Cela est notamment utilise pour des noisettes nécessitant un cache nul.
Pour indiquer au noiZetier d’inclure dynamiquement la noisette, il faut ajouter la ligne suivante au YAML de la noisette :
inclusion: 'dynamique'
Utilisation des noisettes en dehors du noiZetier
Une noisette restant un squelette inclus, elle peut être utilisée par simple inclusion dans un squelette : <INCLURE{fond=noisettes/nom-complet-noisette}{param=val}>
.
Le cache des noisettes
Afin d’améliorer la rapidité du noiZetier, les descriptions des noisettes, des variables de contexte à transmettre aux noisettes et l’inclusion en AJAX ou non sont mises en cache.
De fait, lorsque vous développez une noisette et testez en même temps comment se présente le formulaire de configuration dans le noiZetier, il est possible que vos dernières modifications ne soient pas affichées à moins que vous ne rajoutiez &var_mode=recalcul
dans l’URL de la page.
Aperçu de la noisette
À partir de la version 2 du noizetier, vous pouvez définir un aperçu de la noisette. Il s’agit d’un squelette nommé noisettes/nom_noisette-preview.html
qui recevra les paramètres de la noisette et qui permettra de produire un résumé de ce que fera la noisette.
Voici par exemple le contenu du fichier noisettes/article-filariane-preview.html
du plugin Aveline :
[(#SET{ariane_separateur, #ENV{ariane_separateur}|is_null|non|?{#ENV{ariane_separateur},'>'}})]
[(#SET{longueur_max_titres, #ENV{longueur_max_titres}|sinon{80}})]
[(#ENV{afficher_lien_accueil}|oui)<:accueil_site:>]
[(#ENV{afficher_secteur}|oui) [(#GET{ariane_separateur})] <:aveline:secteur:>]
[(#GET{ariane_separateur})] <:rubriques:> [(#ENV{afficher_secteur}|non) (<:aveline:secteur_exclu:>)]
[(#ENV{afficher_titre_article}|oui) [(#GET{ariane_separateur})] <:article:>]
Aucune discussion
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |