SPIP-Contrib

SPIP-Contrib

عربي | Deutsch | English | Español | français | italiano | Nederlands

286 Plugins, 197 contribs sur SPIP-Zone, 293 visiteurs en ce moment

Accueil > Outils pour plugins > Tutoriaux pour Plugins > Les balises dynamiques

Les balises dynamiques

23 juin 2007 – par madbuilder – commentaires

Toutes les versions de cet article : [français] [italiano]

2 votes

Un tutorial pour essayer de mieux comprendre la création et l’utilisation des balises dynamiques.

Voici donc un résumé de ce que j’ai appris et glané sur le canal irc de SPIP, sur la Zone et les listes de diffusion (zone devel).

Il y a surement des erreurs, mais je pense qu’un tel article peut aider.

Merci d’avance à ceux qui le corrigeront.

Utilisation

Les balises dynamiques réagissent mal, ou pas du tout, aux filtres. Il est donc inutile (jusqu’au moins en 1.9.2) d’essayer d’appliquer un filtre à une balise dynamique, ou d’utiliser une balise dynamique comme argument d’un filtre.

Conception

Contexte de l’article

Cet article se place dans la perspective de l’écriture d’un plugin pour SPIP version supérieure à 1.9.2b.

Cet article n’est pas exhaustif. Il s’efforce de résumer ce que j’ai pu apprendre lors de la réalisation de l’exercice précédemment cité. Pour ce faire je me suis entre autre inspiré de la balise formulaire_ecrire_auteur

La balise dynamique

Une balise dynamique s’oppose à une balise statique. Son implémentation doit correspondre à des besoins de traitements de données d’un formulaire par exemple. En l’absence de traitement il est préférable d’implémenter une balise statique.

Sauf indication explicite contraire, les chemins des fichiers sont relatifs à la racine du plugin, c’est à dire, relativement à la racine du site SPIP (répertoire contenant le fichier spip.php), le répertoire plugins/nom_plugin.

Une balise dynamique a un petit nom, souvent long. Considérons ici une balise nommée JOHN_DOE. Cette balise doit pouvoir être appelée dans un squelette par la syntaxe #JOHN_DOE.

Ce nom n’est pas sans conséquence car il conditionne le nom d’au moins deux fichiers implémentant la balise proprement dite. Ces fichiers sont :
-  « balise/john_doe.php »
-  « formulaires/john_doe.html »

Le fichier « formulaires/john_doe.html »

Il a la même syntaxe qu’un squelette.

Le fichier « balise/john_doe.php »

Il doit ou devrait commencer par la ligne if (!defined("_ECRIRE_INC_VERSION")) return; #securite

Puis viennent 3 fonctions dont les formes minimales semblent être les suivantes :

La première fonction « balise_JOHN_DOE($p) »

Le rôle du paramètre $p reste à éclaircir pour moi. Ce qui est chose faîtes :

$p est le contexte de compilation dont a besoin calculer_balise_dynamique, entre autres pour compiler correctement les valeurs demandées par le tableau de la première fonction, ainsi que les éventuels arguments de la balise elle-meme (forme : #BALISE_DYN{arg1, arg2...}) qui seront alors ajoutés à la fin du dit tableau.

Par contre le troisième paramètre de la fonction calculer_balise_dynamique permet de « récupérer des données du contexte dans lequel est appelée la balise ». (« .. » car mon SPIP doit être très perfectible)

Par exemple si votre balise est destinée à être appelée dans une boucle article ET que vous avez besoin de la valeur de id_article, alors ce troisième paramètre doit être array('id_article').

Ce tableau comporte autant de valeurs qu’il vous faut récupérer de données.

L’ordre de ces valeurs semble important pour pouvoir retrouver les données dans les fonctions suivantes.

La deuxième fonction « balise_JOHN_DOE_stat($args, $filtres) »

$args est un tableau comportant les données récupérées par la fonction précédente dans l’ordre dans lequel ces données ont été désignées par le troisième paramètre de ladite fonction précédente.

Dans cette fonction il est donc possible d’effectuer des traitements sur ces données, par exemple des traitements de validation des dîtes données, des traitements de lecture de la base.... la liste n’est pas exhaustive.

Si les traitements sont satisfaisant, alors la fonction retourne $args et l’aventure continue.

Dans le cas contraire la fonction peut retourner ( "return '';) et l’aventure s’arrête. C’est-à-dire, la balise #JOHN_DOE n’affichera rien. Dans une variante la fonction peut aussi retourner une chaîne de caractères à défaut d’un tableau. Cela interrompra aussi le traitement de la balise en provoquant l’affichage de la chaîne de caractères.

On note ici que cette fonction peut compléter le tableau $args avec d’autres valeurs qui devront alors aussi apparaitre comme paramètres dans la déclaration de la troisième fonction.

$filtres est le tableau des éventuels pseudo-filtres de la balise.

La troisième fonction « balise_JOHN_DOE_dyn(...) »

Dans l’exemple utilisé jusqu’à présent on aurait une déclaration du type

function balise_JOHN_DOE_dyn($id_article) {
...
}

Les paramètres de cette fonction semblent donc correspondre à une liste ordonnée des données récupérées par la première fonction. Cette liste peut être altérée de toutes les manières possibles via la deuxième fonction.

Cette troisième fonction peut être vue comme comportant deux parties principales :
-  des traitements de type traitements d’un formulaire HTML (« _request() » est votre ami), production de valeurs destinées à être affichées comme résultat de ces traitements
-  le retour de la fonction.

Le retour de la fonction

Le retour de la fonction est un tableau de 3 éléments.
-  la désignation d’un squelette, cette désignation étant au format « include_spip() », c’est à dire un nom de fichier dans le « SPIP_PATH » sans l’extension du fichier ;
-  une valeur de durée de vie du cache pour le résultat de la balise. Cette valeur devrait la plupart du temps être nulle. En effet

le code HTML produit dépend en général des valeurs figurant dans $_POST : il est rare qu’on puisse partager deux appels en POST, il vaut donc mieux ne pas encombrer le cache.

 ;
-  un tableau associatif, chaque clé de ce tableau permettant l’accès dans le squelette à la donnée associée à ladite clé par la balise #ENV{clé}.

Conclusion

Vous en savez maintenant autant que moi.

Dernière modification de cette page le 26 juin 2007

Retour en haut de la page

Vos commentaires

  • Le 23 mai 2008 à 13:54, par ? En réponse à : Les balises statiques

    I would like to know how to access id_rubrique when present in $p, the argument of function balise_JOHN_DOE($p) without using a dinamique balise.

    I tried champ_sql('id_rubrique', $p); but this doesn’t actually return the value of id_rubrique.

    print_r(champ_sql('id_rubrique', $p)) gives
    $Pile[$SP]['id_rubrique']  or $Pile[0]['id_rubrique']

    What does it means ?

    Can someone help me ?

    You can also answer in french, I can read it. Thanks

    Répondre à ce message

  • Le 28 juillet 2007 à 14:39, par Mathilde En réponse à : Merci !

    Grâce à ton article, je viens de créer mon premier balbutiement de plugin qui crée une balse dynamique ... Thank you !

    Répondre à ce message

  • Le 24 juin 2007 à 22:18, par Déesse A. En réponse à : Les balises dynamiques

    C’est sympa d’écrire cette doc que je ne me suis jamais décidé à rédiger car je suis encore insatisfait de cette architecture, bien qu’elle ait constitué déjà un progrès en mettant en squelette la partie HTML qui, avant la 1.8, était codée en dur dans les scripts PHP. En remerciement, quelques réponses à tes questions.

    $p est le contexte de compilation dont a besoin calculer_balise_dynamique, entre autres pour compiler correctement les valeurs demandées par le tableau de la première fonction, ainsi que les éventuels arguments de la balise elle-meme (forme : #BALISE_DYN{arg1, arg2...}) qui seront alors ajoutés à la fin du dit tableau.

    Effectivement ce dit tableau sera la valeur du premier paramètre de la fonction suffixée par _stat (avec les éventuels arguments de la balise donc). Si le résultat de cette deuxième fonction est un tableau (souvent identique à celui reçu mais pas forcément), ce sera la liste ordonnée des paramètres de la fonction suffixée par _dyn. Si ce n’est pas un tableau mais une chaîne (pas nécessairement vide, comme ta rédaction peut le faire croire), cette chaîne sera affichée et on s’arrête effectivement là. C’est essentiellement fait pour les formulaires interdits par la configuration du site (inscription etc) : il faut repérer la situation au plus tôt car ça économise une passe de PHP à l’affichage final.

    Le deuxième argument de la deuxième fonction est le tableau des éventuels pseudo-filtres de la balise (dans [(#FOO|bar|foobar)] ce tableau aura donc deux éléments bar et foobar). Ces valeurs ne sont pas des fonctions à appliquer, c’est pourquoi j’ai dit pseudo-filtres. Il ne faut pas utiliser cette syntaxe historique qui est trompeuse et vouée à disparaitre, et lui préférer la syntaxe #FOO{bar, foobar} décrite ci-dessus. Une balise dynamique à ce stade produit un code PHP à exécuter, non pas déjà du HTML filtrable : c’est comme pour INCLURE, on ne peut appliquer un traitement postérieur, ce sera déjà parti dans le flux de sortie.

    Dans le résultat de la troisième fonction, le deuxième élément est la durée de vie du cache que l’on va produire. Dans la plupart des utilisations il faut le mettre à 0 en effet, car le code HTML produit dépend en général des valeurs figurant dans $_POST : il est rare qu’on puisse partager deux appels en POST, il vaut donc mieux ne pas encombrer le cache.

    Les balises dynamiques, en dernière analyse, sont des INCLURE conditionnels (grâce aux fonctions _stat quand elles ne renvoient pas un tableau) et dont l’environnement est spécifié dans le code PHP plutôt que dans le squelette, ce qui est plus concis mais moins clair. Il faudrait unifier tout ça.

    • Le 25 juin 2007 à 11:48, par madbuilder En réponse à : Les balises dynamiques

      Bonjour,

      merci,

      j’ai intégré ce que j’ai compris. Je pense que l’article va encore évoluer.

    • Le 26 juin 2007 à 06:55, par Committo, Ergo Sum En réponse à : Les balises dynamiques

      Attention les accolades ne sont pas toujours passées dans les extraits que tu as insérés dans le corps de l’article.

    Répondre à ce message

  • Le 25 juin 2007 à 02:15, par FredoMkb En réponse à : Les balises dynamiques

    Bonjour et merci pour ce très bon article.

    La documentation officielle de Spip ayant quelques lacunes, je trouve que toute initiative permettant de mieux comprendre le développement des squelettes, filtres, balises, plugins, etc. est à saluer absolument et, je dirais même, à encourager vivement, c’est pourquoi : un grand BRAVO !!!

    Quelque petites remarques cependant :

    -  J’aurais aimé trouver quelques exemples d’utilisation des balises dynamiques et statiques, histoire de mieux en faire la différence et savoir, en somme, quand et pourquoi utiliser l’une ou l’autre, si quelqu’un pouvait apporter un éclairage sur ce sujet, ce serait très utile je pense...

    -  Au niveau du texte de l’article, dans un souci de clareté, je trouve qu’il serait mieux d’indiquer le nom d’une fonction lorsqu’il faut l’évoquer à plusieurs reprises, au lieu de « la fonction précédente » ou « la dîte fonction précédente », mais ce n’est qu’une opinion personnelle...

    -  Enfin, à mon humble avis, l’idéal aurait été de développer, pas à pas, une balise d’exemple (même bidon) à la fin de l’article, afin de bien comprendre, par la pratique, l’utilisation des différentes fonctions, le passage des arguments, l’utilisation dans un squelette, etc.

    Bref, encore bravo et merci pour cet article fort instructif, j’espère qu’il sera peu à peu étoffé par quelques exemples et, qui sait, par le développement détaillé et commenté d’une balise dynamique "fonctionnelle", histoire que chaqu’un puisse s’en servir comme base de travail pour en concevoir d’autres.

    à+ :-)

    Répondre à ce message

Répondre à cet article

Qui êtes-vous ?

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 Les choses à faire avant de poser une question (Prolégomènes aux rapports de bugs. )
Ajouter un document

Retour en haut de la page

Ça discute par ici

  • Mailsubscribers

    16 janvier 2013 – 274 commentaires

    Ce plugin permet de gérer les inscriptions (ou abonnements) à la diffusion de contenu par email. Mailsubscribers permet de gérer les inscriptions par Opt-in simple ou double et la désinscription par URL. Ce plugin gère également plusieurs listes (...)

  • noiZetier v2

    9 novembre 2012 – 36 commentaires

    Le noiZetier offre une interface d’administration permettant d’insérer au choix des éléments modulaires de squelettes (noisettes) et de les ajouter ainsi à ses squelettes. Compatibilité La version 2 du noizetier fonctionne sous SPIP 3. Elle est (...)

  • cirr : plugin « rédacteur restreint »

    29 octobre 2010 – 60 commentaires

    Ce plugin « cirr : rédacteur restreint » permet d’affecter des rubriques aux rédacteurs et modifie les droits afin qu’un rédacteur restreint (ou un administrateur restreint) voit dans l’espace privé uniquement les rubriques qui lui sont affectées (et leur (...)

  • Un retour d’expérience d’utilisation de Formidable

    26 octobre – commentaires

    Il s’agissait de créer un formulaire d’inscription à un évènement modérer les inscriptions dans le privé publier les inscriptions dans le public Nous avons discuté de cette présentation lors de l’apéro SPIP du 15 février 2016 à la Cantine (...)

  • Métas +

    3 décembre – 14 commentaires

    Améliorez l’indexation de vos articles dans les moteurs et leur affichage sur les réseaux sociaux grâce aux métadonnées Dublin Core, Open Graph et Twitter Card. Installation Activer le plugin dans le menu dédié. Dans le panel de configuration, (...)

Ça spipe par là