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 :
function balise_JOHN_DOE($p) {
return calculer_balise_dynamique($p, 'JOHN_DOE', array());
}
function balise_JOHN_DOE_stat($args, $filtres) {
return $args;
}
function balise_JOHN_DOE_dyn() {
return array(
'formulaires/john_doe',
0,
array(
)
);
}
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.
Discussions par date d’activité
2 discussions
Bonjour,
Merci pour cet article. Il est très ancien, mais je ne vois pas où apporter ma petite pierre à l’édifice. J’ai beaucoup de difficultés avec les balises dynamiques.
Je pense avoir compris comment cela fonctionne avec un squelette de formulaire, mais je n’ai pas réussi à faire fonctionner le filtrage sur une balise dynamique renvoyant une valeur simple.
Dans les exemples qui suivent, la fonction get_saas_usages() retourne un array associatif. Je suppose que c’est tout ce qu’il y a à en connaître, je ne pense pas qu’il soit utile de la décrire plus :
Mon but est d’afficher et/ou d’appliquer des filtres sur la valeur retournée par la balise, par exemple :
Balise statique
Juste pour montrer la différence avec la balise dynamique qui va suivre :
Cette balise fonctionne avec des filtres. Mais la valeur retournée est statique dans le sens où elle est mise en cache par SPIP au rafraîchissement de la page, on obtient la valeur précédente, pas la valeur courante, tant que délai du cache ( de la page où la balise est incluse ? ) n’est pas écoulé.
Balise dynamique
Sous la forme simple :
USAGES{testuat}
par exemple, la balise affiche correctement la valeur, et ce, de façon dynamique, c’est à dire sans mise en cache. Mais si on lui applique des filtres, rien ne va plus.
Contournement avec un filtre
Je pense avoir compris qu’appliquer les filtres classiques à une balise dynamique n’aurait pas de sens. Pourtant l’écriture :
[(#USAGES{testbrw}|=={0}|oui) ... ]
serait cohérente me semble-t-il.
Il faut donc y arriver autrement.
Voici une méthode mettant en jeu un filtre particulier appliqué à une balise #REM :
[(#REM|usage{testbrw}|=={0}|oui) ... ]
Voici le filtre usage, qui est un simple appel à la fonction get_usages() :
Cela fonctionne exactement comme je le souhaite.
Ce qui se passe, c’est que la balise statique #REM accepte le filtre, et c’est ce dernier qui assure la lecture des données de façon dynamique.
J’espère avoir aidé à quelque chose. Si je me suis égaré ( en particulier si j’ai mal écrit la balise dynamique ) merci pour les commentaires.
Merci encore et bravo à tous ceux qui font la doc de SPIP !
Répondre à ce message
Bonjour,
Merci pour cet article. Il est très ancien, mais je ne vois pas où apporter ma petite pierre à l’édifice. J’ai beaucoup de difficultés avec les balises dynamiques.
Je pense avoir compris comment cela fonctionne avec un squelette de formulaire, mais je n’ai pas réussi à faire fonctionner le filtrage sur une balise dynamique renvoyant une valeur simple.
Dans les exemples qui suivent, la fonction get_saas_usages() retourne un array associatif. Je suppose que c’est tout ce qu’il y a à en connaître, je ne pense pas qu’il soit utile de la décrire plus :
Mon but est d’afficher et/ou d’appliquer des filtres sur la valeur retournée par la balise, par exemple :
Balise statique
Juste pour montrer la différence avec la balise dynamique qui va suivre :
Cette balise fonctionne avec des filtres. Mais la valeur retournée est statique dans le sens où elle est mise en cache par SPIP au rafraîchissement de la page, on obtient la valeur précédente, pas la valeur courante, tant que délai du cache ( de la page où la balise est incluse ? ) n’est pas écoulé.
Balise dynamique
Sous la forme simple :
USAGES{testuat}
par exemple, la balise affiche correctement la valeur, et ce, de façon dynamique, c’est à dire sans mise en cache. Mais si on lui applique des filtres, rien ne va plus.
Contournement avec un filtre
Je pense avoir compris qu’appliquer les filtres classiques à une balise dynamique n’aurait pas de sens. Pourtant l’écriture :
[(#USAGES{testbrw}|=={0}|oui) ... ]
serait cohérente me semble-t-il.
Il faut donc y arriver autrement.
Voici une méthode mettant en jeu un filtre particulier appliqué à une balise #REM :
[(#REM|usage{testbrw}|=={0}|oui) ... ]
Voici le filtre usage, qui est un simple appel à la fonction get_usages() :
Cela fonctionne exactement comme je le souhaite.
Ce qui se passe, c’est que la balise statique #REM accepte le filtre, et c’est ce dernier qui assure la lecture des données de façon dynamique.
J’espère avoir aidé à quelque chose. Si je me suis égaré ( en particulier si j’ai mal écrit la balise dynamique ) merci pour les commentaires.
Merci encore et bravo à tous ceux qui font la doc de SPIP !
Répondre à ce message
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 : |