Qu’est-ce qu’on appelle « point d’entrée » ?
Cet article est destiné à documenter les pipelines de Spip 2.0
Afin d’épargner aux contributeurs la difficulté et la dépense d’énergie que représente la réécriture partielle ou complète du code de SPIP puis de son maintien dans le temps, nous avons introduit un système de points d’entrée, aussi appelé « pipeline », permettant de glisser un calcul supplémentaire, ou une information différente à l’endroit désiré dans le code de SPIP.
Le point d’entrée est donc le moyen d’indiquer à SPIP quels sont les calculs ou modifications à faire, et où entrent-ils en ligne de compte.
Comment faire appel concrètement au « pipeline »
On réalise cette association dans un plugin via le fichier plugin.xml, en précisant le nom, la fonction et le fichier, ceci en respectant la syntaxe suivante :
<pipeline>
<nom>point_entree</nom>
<action>fonction</action>
<inclure>fichier.php</inclure>
</pipeline><pipeline> : est une balise qui contient elle-même les trois balises suivantes et dont on se sert pour insérer du code PHP dans l’un des points d’entrée de SPIP.
-
<nom>: contient le nom du point d’entrée (Cf. liste ci-dessous) au niveau duquel le plugin agira. -
<action>: contient le nom de la fonction (sans le préfixe du plugin !) -
<inclure>: contient le nom du fichier dans lequel sera définie la fonction qui aura pour nomprefixe_action.
Un plugin peut introduire plusieurs comportements supplémentaires et donc, le fichier plugin.xml contiendra autant de fois que nécessaire la balise <pipeline>.
Que fait un pipeline ?
Concrètement, la fonction PHP qui va entrer dans le pipeline reçoit un contenu, qu’on peut appeler aussi flux, comme paramètre. Cette fonction traite éventuellement ce contenu et le renvoie modifié.
Attention : chaque pipeline fournit un flux différent (ou n’en fournit pas) adapté à sa situation. Il faut donc connaître à chaque fois ce qu’il est possible ou pas de modifier.
Cas minimaliste :
function prefix_traitement($flux) {
/* on ajoute un truc au flux */
$flux .= 'du code html';
return $flux;
}Un premier exemple
Si nous reprenons l’exemple de notre premier plugin, on modifiera les deux fichiers suivants pour adapter le code au point d’entrée choisi :
plugin.xml
exemple_fonctions.php
Ce qui signifie que SPIP trouvera dans le fichier exemple_fonctions.php du plugin, la fonction demo_colore_spip() et qu’elle sera appliquée après le traitement typographique standard (post_typo).
Ainsi, le filtre |colore_spip est systématiquement appliqué, sans faire appel à la syntaxe [(#TEXTE|colore_spip)]. Vous devez même la retirer du fichier squelette pour ne laisser que #TEXTE. Enfin, il est obligatoire de vider le cache de votre site après avoir effectué toutes ces modifications. Notez que la balise <fonctions> a été entièrement remplacée par la balise <pipeline> dans cet exemple.
Liste de tous les points d’entrée
Cette liste ne représente probablement pas l’ensemble des endroits où il serait utile d’insérer du code. Si un contributeur découvre un besoin supplémentaire, qu’il n’hésite pas à le communiquer sur la liste spip-dev.
Le code lui-même nous indique une liste exhaustive mais sans doute pas très parlante. Voici donc ci-dessous un tableau récapitulatif :
| Nom | Catégorie | Rôle |
|---|---|---|
| supprimer_objets_lies | Espace privé | Pour supprimer les objets des plugins lies aux objets du core au moment de leur suppression. |
| pipeline formulaire_admin | Espace privé | pipeline pour les plugins |
| affichage_entetes_final | Espace privé | reçevant le tableau php d’entêtes de la page et permettant d’agir dessus. |
| configurer_liste_metas | reçevant le tableau des valeurs par défaut des metas de SPIP et permettant d’agir dessus (et servant à la sauvegarde des fichiers de configurations actuels de SPIP | |
| accueil_encours | Espace privé | ajoute du contenu sur la page "à suivre", à la fin du cadre foncé qui contient les contenus à valider (et avant le bouton du flux rss) |
| accueil_gadgets | ||
| accueil_informations | ||
| affichage_final | Site public | Effectuer des calculs supplémentaires sur le contenu de la page calculée, juste avant son affichage. Hors cache, donc. |
| affiche_droite | Espace privé | Ajouter des encarts en partie droite de l’espace privé (filter éventuellement la page en fonction de ’exec’) |
| affiche_gauche | Espace privé | Permet de rajouter un bloc dans la colonne de gauche de la page d’accueil de l’espace privé |
| affiche_milieu | Espace privé | |
| afficher_contenu_objet | ||
| afficher_revision_objet | ||
| agenda_rendu_evenement | ||
| ajouter_boutons | Espace privé | Ajouter des boutons dans la barre de navigation de l’espace privé de votre site. |
| ajouter_onglets | Espace privé | Ajouter des onglets dans la barre de navigation de l’espace privé de votre site. |
| autoriser | ||
| body_prive | Espace privé | |
| boite_infos | ||
| calculer_rubriques | ||
| creer_chaine_url | ||
| declarer_tables_auxiliaires | ||
| declarer_tables_interfaces | ||
| declarer_tables_principales | ||
| definir_session | ||
| delete_all | ||
| delete_statistiques | ||
| editer_contenu_objet | ||
| exec_init | Espace privé | |
| formulaire_charger | ||
| formulaire_traiter | ||
| formulaire_verifier | ||
| header_prive | Espace privé | Ajoutre une ou des lignes de votre choix à l’intérieur de la balise HTML <head> des pages de l’espace privé |
| insert_head | Site public | |
| insert_js | ||
| jquery_plugins | ||
| libelle_association_mots | ||
| lister_tables_noexport | ||
| mots_indexation | ||
| nettoyer_raccourcis_typo | Texte | Traiter une chaîne avant d’être envoyée à la fonction couper() ??? |
| notifications | ||
| post_boucle | ||
| post_edition | Tâche de fond | Après l’enregistrement qui suit pre_edition |
| post_propre | Texte | |
| post_syndication | Tâche de fond | |
| post_typo | Texte | |
| pre_boucle | ||
| pre_edition | Tâche de fond | Après création/modification d’un article et avant l’enregistrement de celui-ci dans la base de donnée |
| pre_indexation | Tâche de fond | |
| pre_liens | ||
| pre_propre | Texte | |
| pre_syndication | Tâche de fond | |
| pre_typo | Texte | |
| rechercher_liste_des_champs | ||
| rechercher_liste_des_jointures | ||
| requete_dico | ||
| taches_generales_cron | Tâche de fond | |
| traiter_raccourci_ancre | Texte | |
| verifie_js_necessaire |
accueil_encours
accueil_gadgets
accueil_informations
affichage_final
affiche_droite
affiche_gauche
affiche_milieu
afficher_contenu_objet
afficher_revision_objet
agenda_rendu_evenement
ajouter_boutons
ajouter_onglets
autoriser
body_prive
boite_infos
calculer_rubriques
creer_chaine_url
declarer_tables_auxiliaires
declarer_tables_interfaces
declarer_tables_principales
definisession
delete_all
delete_statistiques
editer_contenu_objet
exec_init
formulaire_charger
Les trois pipelines formulaire_charger, formulaire_verifier, formulaire_traiter appellés sur les 3
étapes de tous les formulaires CVT qui permettent de modifier le comportement sans surcharger (ex : limiter le nombre de mots du texte des articles en intervenant sur formulaire_verifier).
Exemple :
Pré-remplir le formulaire d’envoi de mail à un auteur avec le champ email de la personne loguée s’il est connu.
// au chargement d'un formulaire
function machin_formulaire_charger($flux){
// ajout de l'email dans le formulaire ecrire auteur, si celui ci est connu
if ($flux['args']['form']=='ecrire_auteur') {
if ($mail = $GLOBALS['visiteur_session']['email'])
$flux['data']['email_message_auteur'] = $mail;
}
return $flux;
}formulaire_traiter
formulaire_verifier
header_prive
Exemple tiré du plugin Spip-Jeux et simplifié
function jeux_header_prive($flux){
include_spip('public/assembler');
$flux .= "<link rel='stylesheet' href='../spip.php?page=jeux.css' type='text/css' media='projection, screen' />";
return $flux;
}insert_head
insert_js
jquery_plugins
libelle_association_mots
lister_tables_noexport
mots_indexation
nettoyer_raccourcis_typo
notifications
function monprefix_notifications($flux){
if($flux['args']['quoi'] == 'instituerarticle' AND
$flux['args']['options']['statut'] == 'publie') {
$id_article = $flux['args']['id'];post_boucle
post_edition
post_edition passe un tableau
[args][table] (contient la table affectée)
[id_objet] (contient l'id de l'objet)
[action] (semble être toujours "instituer")
[data][statut] ( peut être : "publie" "poubelle" "refuse" "prepa" "prop")
[date] (contient la date et l'heure si statut = publie ou prepa)