Version du 17 avril 2009 à 18:58

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

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 dynamique

Ajoutez une balise dynamique à votre plugin. La balise affichera un formulaire 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.

Noter 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(...).

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

$p->code: le code PHP qui sera substitué à la balise; il peut s'agit uniquement de HTML
$p->param[]: 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 '*'</cod> (MABALISE*) ou '**' (MABALISE**). On peut le rédéfinir dans la balise. 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 le résultat de la balise (même si $p->interdire_scripts est à true). Cf. <script>ecrire/public/references.php:applique_filtres(...).

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.

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 statiques, un par squelette (pas prévu pour la génération dynamique):

Note: balise [(#ENV{xxxx,zzzz})]:

#ENV* = pour ne pas filtrer par htmlspecialchars (chercher $etoile dans le code source de SPIP)
#ENV** une histoire de php ou du javascript dans la chaîne? (pas trouvé dans le code)

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.

TODO

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).