Les points d’entrée (pipelines)

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 nom prefixe_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 :

NomCatégorieRô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).

cf 11681

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)

post_propre

post_syndication

post_typo

pre_boucle

pre_edition

pre_indexation

pre_liens

pre_propre

pre_syndication

pre_typo

rechercher_liste_des_champs

rechercher_liste_des_jointures

requete_dico

taches_generales_cron

traiter_raccourci_ancre

verifie_js_necessaire