Déclarer des noisettes au noiZetier

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},'&gt;'}})]
[(#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:>]

Notes

[1Avant la version 0.8, le noiZetier acceptait de décrire des noisettes au format XML. Pour faciliter la maintenance, seul le format YAML est maintenant accepté.

[2L’écriture

contexte:
  - 'une_variable'

est également valide.

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

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.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom