Voir la source de Plugin SPIP

= Introduction =

* [http://www.spip.net/rubrique205.html Le développement de SPIP et ses outils]: introduction officielle mais limitée
* [http://programmer.spip.org/ Programmer avec SPIP 2.0]: la documentation la plus complète, on y retrouve les concepts de cette page; description de quelques pipelines et fonctions importants; pénible à lire dû à un découpage trop fréquent.
* [http://www.spip-contrib.net/Developper-avec-SPIP 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; d'autres liens sont dépassés
* [http://doc.spip.org/@Plugin-xml Plugin.xml]: référence de la syntaxe de plugin.xml
* [http://www.spip.net/@ 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 <code>$mes_squelettes</code> (chemins séparés par ':'), puis <code>squelettes, plugins/mon_plugin-1, plugins/mon_plugin-2, ..., (racine), squelettes-dist, prive, ecrire</code>

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

Références:
* <code>ecrire/inc/utils.php:_chemin()</code>
* [http://www.spip.us/fr_article3347.html 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.

== SQL ==

Mémento pour conversion PHP/MySQL -> SPIP (cf. <code>ecrire/base/abstract_sql.php</code> et <code>ecrire/req/mysql.php</code>):

* $res = mysql_query ->
** sql_select($champs, $from, $where, ...)
** sql_insertq($table, $couples, ...) => return mysql_insert_id()
** sql_insertq_multi($table, $tab_couples, ...)
** sql_updateq($table, $couples, $where, ...)
** sql_delete($table, $where, ...)
** sql_replace($table, $couples, ...)
** ...
* qqchose IN (...) -> sql_in($val, $valeurs, $not)
* mysql_real_escape_string -> sql_quote($val) ou _q($val) (même si c'est fait de manière sale avec addslashes)
* mysql_fetch_assoc ->
** sql_fetch($res) - la prochaine ligne
** sql_fetsel($select, $from, $where, ...) - une seule ligne
** sql_allfetsel($select, $from, $where, ...) - toutes les lignes
** sql_getfetsel($select, $from, $where, ...) - une seule ligne et un seul champ
* mysql_num_rows ->
** sql_count($req)
** sql_countsel($from, $where)
* mysql_error -> sql_error

Note: si le nom des tables commence par <code>spip</code>, il sera remplacé par le préfixe configuré à l'installation de SPIP (il n'y a pas besoin de spécifier le préfixe à la main).

= Passer de 1.9 à 2.0 =

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

= Partie admin =

== Insérer une nouvelle page admin ==

* Définir le préfixe de votre plugin (convention de nommage) dans <code>plugin.xml</code>:
 <prefix>monprefixe</prefix>
* Créer <code>plugins/mon_plugin-0.1/exec/monprefixe_mapage.php</code>
* Y définir <code>exec_monprefixe_mapage()</code> (ou <code>exec_monprefixe_mapage_dist()</code>)
* On y accède via http://www.monsite.tld/ecrire/?exec=prefixe_index

Contenu du fichier:
<pre>
<?php
if (!defined('_ECRIRE_INC_VERSION')) return; // sécurité

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();
}
</pre>

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

Pour le contenu, on peut soit l'écrire avec des <code>echo</code>, soit faire appel à un squelette dans <code>plugins/mon_plugin-0.1/prive/mon_squelette.html</code>:
 echo 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: <code>ecrire/exec/sites_tous.php</code>, et <code>acces_restreint_3_0/exec/acces_restreint</code> dans le plugin "Accès restreint".

== Ajouter un bouton ==

Le menu du haut est un ensemble de "boutons", organisés en une structure arborescente (parent, enfants).

Pour ajouter un bouton:
* [http://programmer.spip.org/Definir-des-boutons Définir des boutons]: déclaration dans plugin.xml, et des fonctions <code>autoriser_monbouton_dist(...)</code> pour les autorisations.
* Pipeline <code>monprefixe_ajouter_boutons($boutons_admin)</code> qui ajouter des éléments <code>new Bouton($icone, $titre) dans le tableau <code>$boutons_admin["exec_parent"]->sousmenu["exec_enfant"]</code> ou directement <code>$boutons_admin["exec_enfant"]</code>et gère les autorisations en même temps.

La syntaxe plugin.xml (url et args sont facultatif, auquel cas exec=identifiant):
 <bouton id="identifiant" parent="identifiant_parent">
   <icone>chemin/vers/icone.png</icone>
   <titre>titre ou identifiant de traduction</titre>   
   <url>nom_exec</url>
   <args>arguments pour exec</args>
 </bouton>

Les parents existants: accueil, naviguer, forum, auteurs, configuration, aide_index, visite

Pour afficher l'arborescence courante, on peut utiliser le pipeline suivant:
<pre>
<pipeline>
  <nom>ajouter_boutons</nom>
  <inclure>monprefixe_pipelines.php</inclure>
</pipeline>

function monprefixe_ajouter_boutons($boutons_admin)
{
  print '<pre>';
  print_r($boutons_admin);
  print '</'.'pre>'; // mediawiki work-around
  return $boutons_admin;
}
</pre>

== Ajouter un onglet ==

Un onglet, c'est un sous-menu de page, par exemple "Intéractivité" dans la partie "Configuration".
* Soit on déclare une nouvelle barre d'onglets dans son exec (<code>barre_onglet("menu", "sous_menu_courant")</code>)
* Soit on s'insère dans une barre existante:
** [http://programmer.spip.org/Definir-des-onglets Définir des onglets]: déclaration dans plugin.xml, et des fonctions <code>autoriser_mononglet_dist(...)</code> pour les autorisations.
** Pipeline <code>monprefixe_ajouter_onglets($flux)</code>: <code>$flux['args']</code> contient le nom de la barre d'onglets, <code>$flux['data']</code> contient une barre similaire à la barre de boutons dans <code>ajouter_boutons</code>.

Les barres existantes sont principalement: configuration, administration (elle-même dans configuration), stats_depuis, stats_referers, calendrier, config_lang.

== Ajouter une information objet ==

... c'est à dire un bloc comme "Article numéro X" pour les articles, avec un bel encadré et tout.

La manière propre pour un objet machin: http://programmer.spip.org/Boite-d-information
* passe par le pipeline <code>boite_infos</code>
* créer un squelette <code>prive/infos/machin.html</code> (ouvrir les bons <code>div</code> à la main)
* appeler <code>debut_boite_info</code>/<code>fin_boite_info</code>

Sinon à la main ça donne quelque chose comme:
<pre>
echo debut_boite_info(true);
echo "<div class='infos'>";
echo "<div class='numero'>MACHIN NUMÉRO&nbsp;:<p>" . $id_machin . "</p></div>";
echo "</div>";
echo fin_boite_info(true);
</pre>

Ensuite il y a un tas d'autres informations qu'on peut y insérer; pour les changements de statut, voir les fonctions "instituer_*" dans le code source, il y a des styles CSS déjà prêts.

= 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 <code>balise_MABALISE($p)</code> ou <code>balise_MABALISE_dist($p)</code>, et charge automatiquement le fichier <code>balise/mabalise.php</code> s'il existe (vous pouvez donc définir la balise soit dans ce fichier, soit dans un fichier <code>*_fonctions</code>).

La fonction qui fournit la balise modifie et renvoie un paramètre <code>$p</code> qui a les attributs suivants:
* <code>$p->code</code>: l'expression PHP qui sera substituée à la balise
* <code>$p->interdire_scripts</code>: booléen, indique si le résultat de la balise doit être filtré avec la fonction <code>interdire_scripts(...)</code>
* <code>$p->param[][]</code>: les paramètres passés à la balise (<code>#BALISE{param1, param2, ...}</code>); pour y accéder, on utilise <code>interprete_argument_balise($n, $p)</code> où <code>$n</code> est le numéro du paramètre (en comptant à partir de 1). Attention, la valeur obtenue est du code PHP à insérer dans $p->code, pas une valeur directement exploitable. Techniquement, <code>$p->param[0][]</code> contient les paramètres entre <code>{}</code>, et les éléments suivants contiennent les pseudo-filtres dépréciés (<code>[(#BALISE|oldparam1|oldparam2|...)]</code>).
* <code>$p->etoile</code>: booléen, détermine si la balise est de type <code>'*'</code> (<code>MABALISE*</code>) ou <code>'**'</code> (<code>MABALISE**</code>). On peut le rédéfinir. Au final, <code>'*'</code> signifie de ne pas appliquer divers post-traitements (cf. <code>$table_des_traitements</code>), et <code>'**'</code> signifie de, en plus, ne pas lancer <code>interdire_scripts(...)</code> sur <code>$p->code</code> (même si <code>$p->interdire_scripts</code> est à <code>true</code>). Cf. <code>ecrire/public/references.php:applique_filtres(...)</code>.
* <code>$p->descr['session']</code>: si positionné à <code>true</code>, un cache différent est créé par utilisateur authentifié, ainsi qu'un cache pour les visiteurs non authentifiés. Cela signifie que la balise fait référence à des informations personnelles du visiteur.

Exemple:
<pre>
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 .= " . ' Cache squelette = ' . '" . strftime('%T') . "'";
  $p->code .= " . ' Cache page = ' . strftime('%T')";
  return $p;
}
</pre>

Apparté: notez les deux types de code:
* D'une part, un traitement effectué au calcul de la balise: 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é au calcul de la page: la date. On enregistre non pas le résultat, mais le code, qui affichera l'heure courante, même si le cache squelette n'a pas changé.

En pratique, il n'est pas très utile de distinguer le cache de la page (<code>tmp/cache/a</code> - calcul) et le cache de la balise (<code>tmp/cache/skel</code> - recalcul). Le cache de la page est recalculé sans toucher celui de la balise dans le cas où l'on passe des paramètres supplémentaires dans l'URL, par exemple. Sinon préférez le cache complet (enregistrement du résultat plutôt que de l'appel de fonction).

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

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

== 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 <code><form></code> avec pour cible la page courante, et on utilisera <code>_request</code> dans le code PHP pour effectuer le traitement. Exemple: #FORMULAIRE_ABONNEMENT dans SPIP-Listes, cf. <code>spip-listes_1_9_3/balise/formulaire_abonnement.php</code>.

La balise est définie par trois fonctions: TODO
* <code>balise_MABALISE($p)</code>: déclaration de la balise et des paramètres constants. Elle va en général appeler <code>calculer_balise_dynamique($p, 'MABALISE', array('nom_arg1', 'nom_arg2', ...))</code>. Ces arguments sont des noms de champs que SPIP doit compléter avec de les passer à <code>_stat</code>.
* <code>balise_MABALISE_stat($args, $filtres)</code>: <code>$args</code> contient la listes des valeurs des arguments passés à <code>calculer_balise_dynamique</code>, suivis des valeurs de ceux passés à la balise (<code>MABALISE{val_arg3, val_arg4, ...}</code>). <code>$filtres</code> contient des "pseudos-filtres", c'est à dire des paramètres non interprétés passés avec la syntaxe des filtres SPIP <code>[(#MABALISE|filtre1|filtre2|...)]</code>; cette syntaxe est apparemment dépréciée en faveur de la précédente avec <code>$args</code>. La fonction retourne un tableau d'arguments à passer à <code>_dyn</code>, ou bien directement une valeur (qui peut être un message d'erreur ou non), auquel cas <code>_dyn</code> ne sera pas appelée.
* <code>balise_MABALISE_dyn(...)</code>: en paramètre, les arguments construits dans <code>_stat</code>. La valeur de retour est un tableau à 3 éléments: squelette, durée du cache (0 pour un traitement de formulaire par POST), environnement du squelette.

Exemple:
 TODO

Trace:
 #MABALISE{a,b,c,d}
 => balise_MABALISE_dist($p)
   => creer_balise_dynamique($p, 'MABALISE', array('id_auteur'))
 => balise_MABALISE_stat(array(18, 'a', 'b', 'c', 'd'), array())
 => balise_MABALISE_dyn(18, 4)

Pour le traitement des paramètres, voir par exemple <code>ecrire/balise/login_public.php</code> et .<code>ecrire/balise/formulaire_site.php</code>

Techniquement, la balise dynamique est une balise statique normale, mais son code est triplement exécuté par PHP:
* d'abord la balise est calculée en PHP, avec l'appel à <code>calculer_balise_dynamique(...)</code>, et renvoie une expression PHP (<code>$p->code</code>) qui est stockée dans le cache de squelette
* <code>$p->code</code>, qui contient un appel à <code>executer_balise_dynamique(...)</code>, est exécuté pour générer le contenu, qui est stocké dans le cache de page; mais ici il ne s'agit pas de HTML comme dans la balise dynamique, mais à nouveau de code PHP
* le cache de la page est exécuté au moment de la visite du site, appelant la fonction <code>_dyn</code>, dont le résultat est passé à <code>inclure_balise_dynamique(...)</code>.
* (et vu que <code>_dyn</code> peut faire appel à un squelette, on peut encore avoir du code interprété par la suite!)

== Formulaire ==

Techniquement: traitement déclenché par le paramètre <code>formulaire_action</code>

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:
* [http://www.spip.net/fr_article3796.html Formulaires CVT par l’exemple]
* [http://www.spip.net/fr_article3800.html Les formulaires CVT de SPIP 2.0]

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

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

Paramètres spéciaux pour <code>_charger</code>:
* <code>_action</code> permet d'appeler <code>securiser_action</code>
* <code>_pipeline</code> fait passer le formulaire dans un pipeline

Quand le traitement est terminé, on peut (cf. <code>traiter_formulaires_dynamiques(...)</code>):
* renvoyer un message:
 $retour['message_ok'] = 'Bien reçu';
* rediriger vers une autre page:
 $retour['redirect'] = URL;

Mémento des fichiers nécessaires:
* ./formulaires/XXX.html
* ./formulaires/XXX.php
** formulaires_xxx_charger_dist()
** formulaires_xxx_verifier_dist()
** formulaires_xxx_traiter_dist()

TODO

== Modèles ==

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

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

== Boucles ==

On peut créer ses propres boucles dans SPIP.

En l'absence de code spécifique, SPIP interprète le nom de la boucle comme le nom d'une table, et les balises comme les noms de ses champs.
Par exemple, si je crée une table <code>mammiferes</code> avec des champs <code>id_mammifere</code>, <code>nom</code> et <code>famille</code>:
<pre>
CREATE TABLE `spip_mammiferes` (
  `id_mammifere` int(11) NOT NULL auto_increment,
  `nom` varchar(255) default NULL,
  `famille` varchar(255) default NULL,
  `statut` ENUM ('prepa', 'publie', 'poubelle'),
  PRIMARY KEY  (`id_mammifere`)
);
INSERT INTO `spip_mammiferes` (nom, famille, statut) VALUES ('dauphin', 'cétacés', 'publie');
INSERT INTO `spip_mammiferes` (nom, famille, statut) VALUES ('lapin', 'lagomorphes', 'prepa');
INSERT INTO `spip_mammiferes` (nom, famille, statut) VALUES ('singe', 'primates', 'publie');
</pre>
alors je peux écrire directement le squelette suivant:
<pre>
<BOUCLE_test(SPIP_MAMMIFERES){id_mammifere=3}>
  Le #NOM appartient à la famille des #FAMILLE.
</BOUCLE_test>
</pre>

Pour pouvoir utiliser une table sans le préfixe <code>_spip</code>, on la déclare dans l'interface <code>table_des_tables</code>:
<pre>
<pipeline>
  <nom>declarer_tables_interfaces</nom>
  <inclure>monprefixe_pipelines.php</inclure>
</pipeline>
</pre>
<pre>
function &monprefixe_declarer_tables_interfaces(&$interfaces)
{
  $interfaces['table_des_tables']['mammiferes'] = 'mammiferes';
  return $interfaces;
}
</pre>
On peut alors écrire:
<pre>
<BOUCLE_test(MAMMIFERES){id_mammifere=3}>
  Le #NOM appartient à la famille des #FAMILLE.
</BOUCLE_test>
</pre>

Noter que les boucles sont prévues pour accéder à des tables SQL et à leurs champs; l'utiliser dans d'autres contextes est possible, mais relève de l'acrobatie et est donc forcément limité. Lorsque vous introduisez de nouvelles structures de données dans SPIP, il y a des chances que vous deviez les adapter à ce concept de boucles agissant sur une table, plutôt que d'essayer d'utiliser la boucle hors de son champ normal d'application.

On peut affiner le comportement de la boucle en déclarant une fonction <code>boucle_MABOUCLE_dist</code> ou <code>critere_MABOUCLE_moncritere_dist</code>. Le plus simple est d'inclure ces déclarations dans un fichier <code><fonction></code> de <code>plugin.xml</code> (chargé à chaque recalcul), par exemple:

<pre>
 <fonctions>public/monprefixe_boucles.php</fonctions>
</pre>

<pre>
function boucle_MABOUCLE_dist($id_boucle, &$boucles)
{
  $boucle = &$boucles[$id_boucle];
  // ...
  return calculer_boucle($id_boucle, $boucles); 
}
</pre>

* <code>$id_boucle</code>: identifiant de la boucle, ex: _mesarticles pour une boucle <code><BOUCLE_mesarticles></code>
* <code>&$boucles</code>: tableau de toutes les boucles de la page, indexées par leur identifiant. Ce sont des objets SPIP complexes et internes. On utilisera typiquement <code>$boucle = &$boucles[$id_boucle];</code>. Noter que les champs vont être 
** <code>$boucle->id_table</code>: le nom de la table détecté par SPIP
** <code>$boucle->primary</code>: la clef primaire, apparemment auto-détectée
** <code>$boucle->select</code>: un tableau avec le nom de champs à récupérer; SPIP le remplit par défaut avec la liste des balises trouvées dans la boucle
** <code>$boucle->from</code>:
** <code>$boucle->from_type</code>:
** <code>$boucle->where</code>:
** <code>$boucle->join</code>:
** <code>$boucle->having</code>:
** <code>$boucle->limit</code>:
** <code>$boucle->group</code>:
** <code>$boucle->order</code>:

Par exemple, pour filtrer les mammifères non-publiés:
<pre>
function boucle_MAMMIFERES_dist($id_boucle, &$boucles)
{
  $boucle = &$boucles[$id_boucle];
  
  $id_table = $boucle->id_table;
  $mstatut = $id_table .'.statut';
  $boucle->where[] = array("'='", "'$mstatut'", "'\\'publie\\''");
  
  return calculer_boucle($id_boucle, $boucles);
}
</pre>

Noter qu'un objet boucle est déjà présent au moment où l'on entre dans notre fonction. Il ne reste plus qu'à le compléter.


Étape suivante: on souhaite accéder à des champs d'autres tables dans la boucle. Imaginons que nous voulons dire qui a photographié un mammifère, et pouvoir filtrer uniquement les mammifères de cet auteur:
<pre>
CREATE TABLE `spip_auteurs_mammiferes` (
  `id_auteur` bigint(21) NOT NULL default '0',
  `id_mammifere` bigint(21) NOT NULL default '0',
  PRIMARY KEY  (`id_auteur`,`id_mammifere`)
);
INSERT INTO spip_auteurs_mammiferes (`id_auteur`, `id_mammifere`) VALUES (1,1);
</pre>

Si l'on spécifie <code>{id_auteur=1}</code> dans notre boucle, il y a une erreur, car SPIP ne sait pas où chercher <code>id_auteur</code>. Il faut le lui dire explicitement, à nouveau dans le pipeline <code>declarer_tables_interfaces</code>:
<pre>
function &monprefixe_declarer_tables_interfaces(&$interfaces)
{
  $interfaces['table_des_tables']['mammiferes'] = 'mammiferes';
  
  $interfaces['table_des_tables']['auteurs_mammiferes'] = 'auteurs_mammiferes'; // ou dans declarer_tables_auxiliaires
  $interfaces['tables_jointures']['spip_mammiferes']['id_auteur'] = 'auteurs_mammiferes';
  return $interfaces;
}
</pre>

Ce qui nous permet par exemple d'écrire dans le squelette:
<pre>
Les miens:<br />
<BOUCLE_lesmiens(MAMMIFERES){id_auteur=1}{doublons}>
  Le #NOM appartient à la famille des #FAMILLE.<br />
</BOUCLE_lesmiens>
Les autres:<br />
<BOUCLE_lesautres(MAMMIFERES){doublons}>
  Le #NOM appartient à la famille des #FAMILLE.<br />
</BOUCLE_lesautres>
</pre>

Voir la section [Jointures automatiques->article64] pour plus de détails.

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

Exemples: <code>ecrire/public/boucles.php</code>, <code>forms_et_tables_1_9_1/public/forms_boucles.php</code>.

== Critères ==

Par défaut un critère est le nom d'une colonne dans la table SQL parcourue par la boucle.

On peut également définir des critères dont le résultat est donné par une fonction PHP.
Déclaration:
 <fonctions>public/monprefixe_criteres.php</fonctions>

 critere_moncritere_dist($idb, &$boucles, $crit)
 critere_MABOUCLE_moncritere_dist($idb, &$boucles, $crit)

Noter que la boucle (ici <code>MABOUCLE</code>) n'a pas besoin d'être explicitement définie par ailleurs (on peut, mais ce n'est pas toujours le cas).

* $idb: identifiant de la boucle, ex: <code>_mesarticles</code> pour une boucle <code><BOUCLE_mesarticles></code>
* &$boucles: tableau de toutes les boucles de la page, indexées par leur identifiant. Ce sont des objets SPIP complexes et internes. On utilisera typiquement <code>$boucle = &$boucles[$idb];</code>
* $crit: objet <code>Critere</code>; on utilisera notamment:
** <code>$crit->not</code>: le critère est inversé (<code>!moncritere</code>)
** <code>$crit->param</code>: une structure complexe décrivant les paramètres du critères; il doit falloir passer par des fonctions SPIP pour les exploiter (<code>calculer_liste</code>?)
** TODO
* Résultat: aucun; la fonction doit modifier l'objet boucle, par exemple son champ <code>having[]</code>, <code>order[]</code> ou <code>where[]</code>.

Si, dans le squelette, on utilise la syntaxe <code>{moncritere == qqchose}</code>, SPIP force apparemment l'utilisation de moncritere comme champ de table (en plus de l'appel de notre fonction), ce qui cause une erreur si le critère n'en est pas un.

Exemples: <code>ecrire/public/criteres.php</code>, <code>spip-bonux/public/spip_bonux_criteres.php</code>.

Liens:
* [http://www.spip-contrib.net/NouveauCritere Nouveau Critère]: sur le wiki spip

== Paramètre 'action' ==

Le fichier <code>action/monprefixe_monaction.php</code> 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 <code>page=</code> 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 ==

* [http://doc.spip.org/@Les-points-d-entree-pipelines Les points d’entrée (pipelines)]: les ''hooks'', quoi; une description partielle

Le terme pipeline vient du fait que le processus est amorcé avec des données initiales, qui sont passés à chaque hook qui les traite puis renvoie ces données modifiées pour les passer au hook suivant, formant ainsi une chaine de traitement.

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

Le [http://trac.spip.org/trac/spip-zone/browser/_plugins_/plugin_template 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).

Déclaration dans plugin.xml:
 <pipeline>
   <nom>nom_pipeline</nom>
   <inclure>monprefixe_pipelines.php</inclure>
   <action>monprefixe_mafonction</action>
 </pipeline>

* <code>nom</code> est obligatoire est précise le nom de pipeline dans lequel on insère notre traitement
* <code>inclure</code> est facultif, par défaut cherche les fonctions existantes - cependant certains pipelines (ex: <code>declarer_tables_interfaces</code>) sont lancés avant que <code>monprefixe_options.php</code> ne soit chargé, donc c'est une bonne habitude de toujours le spécifier.
* <code>action</code> est facultatif, par défaut lance la fonction <code>monprefixe_nom_pipeline(...)</code>

La valeur initiale passée au pipeline est:
* soit un tableau à deux élement: <code>args</code> qui contient des paramètres, et <code>data</code> qui sera la valeur de retour du pipeline.
* soit une valeur quelconque, qui sera directement la valeur de retour du pipeline.

Lancement d'un pipeline perso: [http://programmer.spip.org/Declarer-un-nouveau-pipeline Déclarer un nouveau pipeline]