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

<plugin>
    <nom>Mon dernier plugin (colore_spip)</nom>
    <version>1.0</version>
    <prefix>demo</prefix>
    <options>exemple_options.php</options>
    <pipeline>
        <nom>post_typo</nom>
        <action>demo_colore_spip</action>
        <inclure>exemple_fonctions.php</inclure>
    </pipeline>
</plugin>

exemple_fonctions.php

<?php

function demo_colore_spip($texte) {
    global $couleur;
    return preg_replace(
        '/([^(class=")])(spip)/i',
        '$1<span style="color: '.$couleur.';">$2</span>',
        $texte
    );
}

?>

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 :

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