imported>SylvainBeucler |
imported>Pierre |
| Ligne 1 : |
Ligne 1 : |
| − | = Introduction =
| |
| | | | |
| − | * [http://www.spip.net/rubrique205.html Le développement de SPIP et ses outils]: documentation officielle
| |
| − | * [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.
| |
| − | * [http://doc.spip.org/@Plugin-xml Plugin.xml]: référence de la syntaxe
| |
| − | * [http://www.spip.us/@ 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>
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | = 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.
| |
| − |
| |
| − | = 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;
| |
| − |
| |
| − | 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>:
| |
| − | 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".
| |
| − |
| |
| − | = 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->param[]</code>: TODO - les paramètres passés à la balise? (<code>#BALISE{param1, param2, ...}</code>)
| |
| − | * <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->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>.
| |
| − |
| |
| − | 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 .= " . ' ' . strftime('%T')";
| |
| − | return $p;
| |
| − | }
| |
| − | </pre>
| |
| − |
| |
| − | 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é.
| |
| − |
| |
| − | 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>.
| |
| − |
| |
| − | == 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>.
| |
| − |
| |
| − | == 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 introduire des nouvelles boucles en déclarant des fonctions <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).
| |
| − |
| |
| − | 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>ecrire/public/criteres.php</code>, <code>forms_et_tables_1_9_1/public/forms_boucles.php</code>, <code>spip-bonux/public/spip_bonux_criteres.php</code>.
| |
| − |
| |
| − | == 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.
| |
| − |
| |
| − | == 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 statiques, un par squelette (pas prévu pour la génération dynamique):
| |
| − | * [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]
| |
| − |
| |
| − | Note: balise <code>[(#ENV{xxxx,zzzz})]</code>:
| |
| − | * #ENV* = pour ne pas filtrer par htmlspecialchars (chercher <code>$etoile</code> 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, <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>.
| |
| − |
| |
| − | TODO
| |
| − |
| |
| − | == Pipeline ==
| |
| − |
| |
| − | [http://doc.spip.org/@Les-points-d-entree-pipelines Les points d’entrée (pipelines)]: les ''hooks'', quoi; une description partielle
| |
| − |
| |
| − | 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).
| |
| − |
| |
| − | TODO
| |
