Plugin SPIP

Introduction

• Le développement de SPIP et ses outils: documentation officielle
• Développer avec SPIP: une liste de liens sur SPIP-Contrib; noter que certaines fonctionnalités des plugins sont des reprises de l'existant < v1.9, par exemple la définition de balises personnalisées.
• Plugin.xml: référence de la syntaxe
• Glossaire: un index de tous les boucles/balises/filtres et autres mots-clefs de SPIP

Le SPIP_PATH

Il s'agit du répertoire de recherche de SPIP, pour les squelettes, mais aussi pour les fichiers PHP personnalisés, (définitions de balises, de pages privées, etc.), les modèles, etc.

Dans l'ordre: la variable globale $mes_squelettes (chemins séparés par ':'), puis squelettes, plugins/mon_plugin-1, plugins/mon_plugin-2, ..., (racine), squelettes-dist, prive, ecrire

Techniquement, les chemins des squelettes sont définis dans le fichier PHP généré tmp/charger_plugins_options.php, qui définit également les constantes _DIR_PLUGIN_MONPREFIXE.

Références:

• ecrire/inc/utils.php:_chemin()
• Où placer les fichiers des squelettes

API

http://doc.spip.org/ a pour but de documentation l'API de SPIP, une page par fonction, modifiable par tous. En pratique, peu de fonctions sont documentées. Qui plus est, cette documentation étant la documentation officielle, le code source se contente d'y faire référence, souvent sans plus de détails.

La meilleure source de documentation reste la lecture du code source, et l'étude d'autres plugins.

Passer de 1.9 à 2.0

Certaines fonctions ont changé. Pour convertir le code de votre plugin, une bonne source d'information est ecrire/inc/vieilles_defs.php qui définit des anciennes fonctions avec la nouvelle API 2.0.

Insérer une nouvelle page admin

• Définir le préfixe de votre plugin (convention de nommage) dans plugin.xml:

<prefix>monprefixe</prefix>

• Créer plugins/mon_plugin-0.1/exec/monprefixe_mapage.php
• Y définir exec_monprefixe_mapage() (ou exec_monprefixe_mapage_dist())
• On y accède via http://www.monsite.tld/ecrire/?exec=prefixe_index

Contenu du fichier:

<?php
if (!defined("_ECRIRE_INC_VERSION")) return;

function exec_monprefixe_index()
{
  $commencer_page = charger_fonction('commencer_page', 'inc');
  echo $commencer_page("Titre (barre de titre du navigateur)");

  echo gros_titre("Titre (dans la page)", '<img src="logo.png" alt="" />', false);


  echo debut_grand_cadre(true);
  echo "Bandeau en haut";
  echo fin_grand_cadre(true);


  echo debut_gauche("ignored", true);
  echo "À gauche<br />";

  echo creer_colonne_droite("", true);
  echo "À droite si grand écran, à gauche sinon<br />";
  echo debut_boite_info(true);
  echo "Encadré";
  echo fin_boite_info(true);

  $res = icone_horizontale("Page 1", generer_url_ecrire("monprefixe_page1"),
			   "../"._DIR_PLUGIN_MONPREFIXE."fond.gif",
			   "../"._DIR_PLUGIN_MONPREFIXE."page1.gif", false);
  echo bloc_des_raccourcis($res); // crée creer_colonne_droite si besoin


  echo debut_droite("ignored", true); // ferme creer_colonne_droite, si utilisé
  echo "Contenu, au milieu";


  echo fin_gauche();
  echo fin_page();
}

Les true et false qui se baladent partout permettent de dire qu'on s'occupe d'afficher le contenu, sans quoi SPIP affiche un avertissement. Il faut utiliser true ou false au cas par cas, selon la fonction, cela manque de cohérence.

Pour le contenu, on peut soit l'écrire avec des echo, soit faire appel à un squelette dans plugins/mon_plugin-0.1/prive/mon_squelette.html:

recuperer_fond('prive/mon_squelette', $_GET);

Note: le préfixe n'est techniquement pas obligatoire pour le nom de la page, mais c'est une bonne habitude à prendre pour éviter les conflits avec d'autres plugins.

Exemples: ecrire/exec/sites_tous.php, et acces_restreint_3_0/exec/acces_restreint dans le plugin "Accès restreint".

Traitement dans la partie publique

Diverses solutions possibles:

Balise statique

La balise statique a pour but de présenter de l'information, si possible mise en cache.

Champ

Une balise #MONCHAMP à l'intérieur d'une boucle doit aller chercher le champ correspondant dans la base SQL.

TODO

Génération de code

SPIP va chercher une fonction balise_MABALISE($p) ou balise_MABALISE_dist($p), et charge automatiquement le fichier balise/mabalise.php s'il existe (vous pouvez donc définir la balise soit dans ce fichier, soit dans un fichier *_fonctions).

La fonction qui fournit la balise modifie et renvoie un paramètre $p qui a les attributs suivants:

• $p->code: l'expression PHP qui sera substituée à la balise
• $p->param[]: TODO - les paramètres passés à la balise? (#BALISE{param1, param2, ...})
• $p->interdire_scripts: booléen, indique si le résultat de la balise doit être filtré avec la fonction interdire_scripts(...)
• $p->etoile: booléen, détermine si la balise est de type '*' (MABALISE*) ou '**' (MABALISE**). On peut le rédéfinir. Au final, '*' signifie de ne pas appliquer divers post-traitements (cf. $table_des_traitements), et '**' signifie de, en plus, ne pas lancer interdire_scripts(...) sur $p->code (même si $p->interdire_scripts est à true). Cf. ecrire/public/references.php:applique_filtres(...).

Exemple:

function balise_CITATION_dist($p)
{
  $hasard = mt_rand(0, 1);
  if ($hasard == 1)
    $p->code = "'Gel en novembre, Noël en décembre! -- sagesse populaire'";
  else
    $p->code = "'Une de mes journées les plus productives a été de jeter 1000 lignes de code -- Ken Thompson'";
  $p->code .= " . ' ' . strftime('%T')";
  return $p;
}

Notez les deux types de code:

• D'une part, un traitement effectué au moment du recalcul: le choix de la citation. Le résultat est une expression PHP, ici une chaine de caractère - qui pour être spécifiée en PHP doit être insérée dans une autre chaine de caractères. La citation sélectionnée ne changera pas dans le cache.
• D'autre part, un traitement effectué à chaque appel de page: la date. On enregistre non pas le résultat, mais le code, qui affichera l'heure courante, même si le cache n'a pas changé. TODO: à vérifier, différents caches, cache squelette != cache page.

Attention: le fichier balise/mabalise.php n'est chargé qu'au calcul. Si vous avez besoin de fonctions auxiliaires, soit il faut les déclarer dans d'autres fichiers (xxx_options.php), soit il faut passer à une balise dynamique.

Notez qu'il existe des balises génériques, du type MABALISE_ (tout court), qui sont évaluées après pour toutes les balises MABALISE_XXX, même si la balise en question n'existe pas. Cela permet de traiter notamment les balises spéciales FORMULAIRE_XXX; lecode de SPIP définit également LOGO_XXX et URL_XXX. Cf. ecrire/public/references.php:calculer_balise(...) et ecrire/balise/logo_.php. Les balises ainsi crées peuvent être statiques (LOGO_XXX) ou dynamiques (FORMULAIRE_XXX).

Balise dynamique

Ces balises sont prévues pour traiter des données utilisateur, notamment des formulaires. Elle sont rechargées à chaque appel de page. La balise pourra afficher un <form> avec pour cible la page courante, et on utilisera _request dans le code PHP pour effectuer le traitement. Exemple: #FORMULAIRE_ABONNEMENT dans SPIP-Listes, cf. spip-listes_1_9_3/balise/formulaire_abonnement.php.

Formulaire

Techniquement: traitement déclenché par le paramètre formulaire_action

On peut s'appuyer sur les outils "CVT" (charger/vérifier/traiter) de SPIP. Cette approche crée les formulaires prédéfinis, un par squelette - ce n'est pas prévu pour la génération de formulaires à la volée:

• Formulaires CVT par l’exemple
• Les formulaires CVT de SPIP 2.0

De plus, balise_FORMULAIRE_XXX_stat (definit dans balise/formulaire_xxx.php) devrait être appelé avant la génération du formulaire, ce qui permet de renvoyer un tableau de valeurs, qui sera passé via formulaire_action_args sous forme comprimée et signée. Ces arguments seront par la suite passés en paramètre de _charger/_verifier/_traiter. Cf. ecrire/balise/formulaire_inscription.php et squelettes-dist/formulaires/inscription.php.

Techniquement les formulaires CVT sont implémentés via la balise dynamique et générique FORM_. Vous pouvez donc affiner votre formulaire en déclarant une balise dynamique de même nom.

TODO

Modèles

L'utilisation d'une syntaxe <modeleN> dans un article appelle le squelette modeles/modele.html avec un contexte id_modele=N. Ce squelette pourra inclure une balise correspondante, par exemple.

Cf. ecrire/inc/lien.php:traiter_modeles(...). Exemples: prive/modeles/img.html, plugins/forms_et_tables_1_9_1/modeles/form.html.

Boucles

On peut introduire des nouvelles boucles en déclarant des fonctions boucle_MABOUCLE_dist ou critere_MABOUCLE_moncritere_dist. Le plus simple est d'inclure ces déclarations dans un fichier <fonction> de plugin.xml (chargé à chaque recalcul).

Cf. ecrire/public/compiler.php:public_compiler_dist(...) et ecrire/public/criteres.php:calculter_criteres(...).

Exemples: ecrire/public/boucles.php, ecrire/public/criteres.php, forms_et_tables_1_9_1/public/forms_boucles.php, spip-bonux/public/spip_bonux_criteres.php.

Paramètre 'action'

Le fichier action/monprefixe_monaction.php sera exécuté; cependant ce n'est pas prévu pour afficher du contenu, seulement pour du traitement.

Squelette dédié

Utiliser le paramètre page= pour afficher un squelette de votre plugin, qui pourra contenir du PHP. L'inconvénient est le manque d'intégration dans le site public, puisque ce ne sera pas intégré dans les squelettes du webmestre.

Pipeline

Les points d’entrée (pipelines): les hooks, quoi; une description partielle

La listes des hooks SPIP est dans ecrire/inc_version.php. D'autres plugins peuvent en rajouter pour leurs besoins propres (ex: Forms&Tables).

Le plugin d'exemple, même s'il n'a pas été mis à jour pour la version 2, présente quelques points d'entrée importants, classés par catégorie (admin/cron/public/typo).

TODO