- trucs et astuces pour le portage des plugins sous spip 3
- trucs glanés à partir de l’analyse des commits de la zone qui signalent des adaptations du code pour compatibilité avec spip3.Cette liste ouverte à tous : reportez y vos trucs et bonnes pratiques de portage des plugins vers spip3
Voir aussi :
- l’aide mémoire de la représentation en mémoire de la base de donnée (les « déclarations ») pour SPIP3, avec la comparaison avec SPIP2 : https://spreadsheets.google.com/spreadsheet/ccc?key=0Aq-LDsZ2YhzydDBvMjRSamQ5aWtfNWpKcnFESjQwU3c&hl=fr&authkey=CMmWhpEC
- migrer un plugin vers spip2
- Créer un nouvel objet dans le futur SPIP 3
- Configurer une fonctionnalité de votre site, ou un plugin
- CFG : comment s’en passer !
- Rédaction du paquet.xml
- Ça peut servir de respecter la charte typographique :ecrire/?exec=charte
(accessible grâce au plugin dev)
- Un plugin utile pour la migration de plugins pour SPIP 3 : Le plugin PlugOnet permet de transformer automatiquement un fichier plugin.xml en paquet.xml et contient une documentation détaillée de paquet.xml (dans la colonne de droite de /ecrire/ ?exec=plugonet_generer). Il permet aussi de valider les fichiers paquet.xml des plugins installés. Pour l’utiliser : Installer sur votre site le plugin à migrer sous SPIP 3, installer PlugOnet, puis aller dans /ecrire/ ?exec=plugonet_generer.
le plugin plugOnet en 3.1 est disponible via le menu de développement (à activer les options personnelles)
ou simplement via l’adresse /ecrire/ ?exec=plugonet&operation=generer
Vous pourrez utiliser ?exec=valider_xml&var_url=../plugins/auto/-nom_plugin-/paquet.xml
Détecter et comparer la version de spip pour s’adapter
include_spip('plugins/installer'); // spip_version_compare dans SPIP 3.x
include_spip('inc/plugin'); // spip_version_compare dans SPIP 2.x
if (spip_version_compare($GLOBALS['spip_version_branche'], '3.0.0alpha', '>=')) {
define('_SPIP3', true);
} else {
define('_SPIP3', false);
}
Les utilisateurs du Couteau Suisse peuvent directement utiliser le test suivant (sans inclusion) :if(defined('_SPIP30000')) ...
http://zone.spip.org/trac/spip-zone/changeset/48226 apporte son lot d’éléments migrateurs :
Paginations : Dans un fichier squelette du privé,[<p class='pagination'>(#PAGINATION)</p>]
devient [<p class='pagination'>(#PAGINATION{prive})</p>]
Nommages CSS : La classe ’liste_items’ devient ’liste-items’ !!
Boutons du menu de la partie privée
Les écritures qui suivent sont un peu dépréciées car elles utilisent le plugin.xml. En SPIP 3, mieux vaut écrire un paquet.xml (voir la doc) qui possède le tag <menu> pour définir les menus. De plus, certains boutons ont été déplacés)
Dans plugin.xml on supprime
<bouton id='corbeille' parent='configuration'>
<titre>corbeille:corbeille</titre>
<icone>img_pack/trash-full-24.png</icone>
</bouton>
et on ne laisse que
<bouton id='corbeille' parent='bando_administration'>
<titre>corbeille:corbeille</titre>
<icone>images/trash-full-16.png</icone>
<url>corbeille</url>
</bouton>
Ou bien (51393) :
<pipeline>
<nom>ajouter_boutons</nom>
<action>ajouterBoutons</action>
<inclure>spiptospip_fonctions.php</inclure>
</pipeline>
devient :
<bouton id='spip2spip1' parent='naviguer'>
<titre>spiptospip:titre</titre>
<icone>img_pack/icon.png</icone>
<url>spip2spip</url>
</bouton>
<bouton id='spip2spip2' parent='bando_activite'>
<titre>spiptospip:titre</titre>
<icone>img_pack/icon.png</icone>
<url>spip2spip</url>
</bouton>
NB : la fonction function spip2spip_ajouterBoutons($boutons_admin)
est supprimée.
Logs avec niveaux
Le niveau de log doit apparaître en 2e argument ou être concaténé au nom du fichier de log s’il y en a un en 2e argument.
Les différents niveaux de logs, par ordre de notabilité décroissante, sont : _LOG_HS, _LOG_ALERTE_ROUGE, _LOG_CRITIQUE, _LOG_ERREUR, _LOG_AVERTISSEMENT, _LOG_INFO_IMPORTANTE, _LOG_INFO , _LOG_DEBUG
spip_log($message);
spip_log ($message, $fichier);
spip_log($message, _LOG_AVERTISSEMENT);
spip_log ($message, $fichier._LOG_AVERTISSEMENT);
Les anciens appels à spip_log sont encore corrects mais doivent être précisés pour bénéficier de la définition du niveau de log globale.
Exemple avec http://zone.spip.org/trac/spip-zone/changeset/47826 :
Motclés
En spip3, les motclés sont gérés par une seule table pour tous les objets auxquels ils s’appliquent. Il faut donc transférer les contenus de toutes les tables de spécialisées vers la table générique.
exemple avec http://zone.spip.org/trac/spip-zone/changeset/48879
Lorsqu’un plugin crée un type d’objet qui bénéficie des motclés, ce transfert se traduit :
- dans les déclarations des tables (une table de jointure spécialisée en moins, 2 déclarations de jointures en moins, une déclaration de table auxiliaire en moins)
Par exemple pour spip-lettre, on supprime :
$spip_mots_lettres = array(
"id_mot" => "BIGINT (21) DEFAULT '0' NOT NULL",
"id_lettre" => "BIGINT (21) DEFAULT '0' NOT NULL"
);
$spip_mots_lettres_key = array(
"PRIMARY KEY" => "id_lettre, id_mot",
"KEY id_mot" => "id_mot"
);
ainsi que
$interface['tables_jointures']['spip_lettres'][] = 'mots_lettres';
$interface['tables_jointures']['spip_lettres'][] = 'mots';
et
$tables_auxiliaires['spip_mots_lettres'] =
array('field' => &$spip_mots_lettres, 'key' => &$spip_mots_lettres_key);
- dans la procédure d’upgrade : supprimer les anciennes tables de la nouvelle manière déclarative :
include_spip('maj/svn10000');
$maj['5.2'] = array(
array('maj_liens','mot','lettre'),
array('sql_drop_table',"spip_mots_lettres"), ...
);
Auteurs
Il en est de même pour les auteurs que pour les motclés
exemple avec http://zone.spip.org/trac/spip-zone/changeset/48879
Associer un auteur à un article
Avant on faisait
sql_insertq('spip_auteurs_articles', array('id_auteur' => $id_auteur, 'id_article' => $id_article));
Dans SPIP3 on fait
include_spip('action/editer_liens'); // si nécessaire
objet_associer(
array("auteur"=>$id_auteur),
array("article"=>$id_article));
Procédure d’upgrade des plugins
Visiblement, un format déclaratif a été créé. Il permet de s’affranchir de faire les tests de versions DANS la fonction d’upgrade : on déclare seulement ce qui doit être fait dans les différents cas. Comme indiqué ici, plus besoin de déclarer dans le fichier paquet.xml du plugin le fichier contenant les fonctions d’installation. Ces fonctions doivent ce trouver dans le fichier prefixe_du_plugin_administrations.php
à la racine du dossier du plugin.
exemple avec http://zone.spip.org/trac/spip-zone/changeset/48879
On remplit $maj avec diverses fonctions d’upgrade standard ou faites sur mesure (faire avant les include_spip des fichiers contenant les fonctions utilisées :
$maj['0.1'] = array(
array('spip_lettres_update_meta',$version_plugin,$nom_meta_base_versio,$current_version,$version_cible),
array('spip_lettres_creer_repertoire_documents'),
);
...
$maj['3.8'] = array(
array('maj_tables',array('spip_lettres')),
array('sql_alter',"TABLE spip_lettres DROP idx"),
array('sql_drop_table',"spip_documents_lettres",true),
array('spip_lettres_update_meta',$version_plugin,$nom_meta_base_versio,$current_version,$version_cible),
);
Ici la fonction ’spip_lettres_creer_repertoire_documents est définie sur mesure peu après :
function spip_lettres_creer_repertoire_documents() {
include_spip('inc/getdocument');
creer_repertoire_documents('lettres');
}
et à la fin on appelle
include_spip('base/upgrade');
maj_plugin($nom_meta_base_version, $version_cible, $maj);
Exemple complet avec le fichier sjcycle_administrations.php :
<?php
if (!defined("_ECRIRE_INC_VERSION")) return;
include_spip('inc/meta');
// Installation et mise à jour
function sjcycle_upgrade($nom_meta_version_base, $version_cible){
$maj = array();
include_spip('inc/config');
$maj = array();
$maj['create'] = array(
array('ecrire_config','sjcycle', array(
'tooltip' => '',
'tooltip_carac' => '',
'fancy' => '',
'fx' => 'fade',
'sync' => 'on',
'speed' => '2000',
'timeout' => '4000',
'pause' => '',
'random' => '',
'div_class' => 'dsjcycle',
'div_width' => '400',
'div_height' => '400',
'div_margin' => '0',
'img_bordure' => '0',
'div_background' => 'ffffff',
'img_position' => 'center',
'img_width' => '400',
'img_height' => '400',
'img_background' => 'ffffff',
'afficher_aide' => 'on'
)));
include_spip('base/upgrade');
maj_plugin($nom_meta_version_base, $version_cible, $maj);
}
// Désinstallation
function sjcycle_vider_tables($nom_meta_version_base){
effacer_meta('sjcycle');
effacer_meta($nom_meta_version_base);
}
?>
Filtre icone pour la partie privée
Le code SPIP3 de inc/filtres.php, indique que ’icone_base’ remplace ’icone’ même si icone est maintenu pour compatibilité. Attention : les arguments sont différents.
Ainsi, le commit http://zone.spip.org/trac/spip-zone/changeset/53822 remplace[(#URL_ECRIRE{gis_editer}|parametre_url{nouveau,oui}|icone{<:gis:editer_gis_nouveau:>,#CHEMIN{images/gis-24.png},#LANG_RIGHT,creer.gif})]
par [(#URL_ECRIRE{gis_editer}|parametre_url{nouveau,oui}|icone_verticale{<:gis:editer_gis_nouveau:>,#CHEMIN{images/gis-24.png},new,#LANG_RIGHT})]
Configurations
Le mode de configuration proposé pour spip2 dans spip-bonux est désormais proposé en standard dans spip3. La documentation figure sur http://spip.net/ecrire ou http://www.spip-contrib.net/CFG-comment-s-en-passer.
C’est en grande partie compatible avec la configuration via le plugin CFG mais il peut y avoir de menues modifications à faire.
En particulier le nom du formulaire doit être #FORMULAIRE_CONFIGURER_PREFIXEDUPLUGIN
, et le nom du fichier squelette, au lieu d’être dans fonds
et s’appeler cfg_prefixeduplugin.html
, doit aller dans formulaire
et s’appeler configurer_prefixeduplugin.html
Exemple : http://zone.spip.org/trac/spip-zone/changeset/54280
insert_head et insert_head_css
utiliser insert_head_css tant que c’est possible.
exemple : http://zone.spip.org/trac/spip-zone/changeset/54280
Un exemple de migration
http://zone.spip.org/trac/spip-zone/changeset/53842 suivi de http://zone.spip.org/trac/spip-zone/changeset/53844 :
- on passe du pipeline declarer_tables_principales au pipeline declarer_tables_objets_sql pour declarer la table GIS
- on rajoute les elements qui vont bien dans declarer_tables_objets_sql
- on vire la fonction generer_url_ecrire_gis qui est générée toute seule par SPIP
http://zone.spip.org/trac/spip-zone/changeset/53850 :
- Les trois pipelines supprimés vont dans le pipeline declarer_tables_objets_sql (recherche, et les deux surnoms)
Encarts et boites dans la partie privée
La page ecrire/ ?exec=charte_boites présente les possibilités des boites et de la balise #BOITE_OUVRIR
La nouvelle balise #BOITE ne gère pas les blocs dépliables. Il faudrait le faire à la main, ce qui n’est pas le cas dans http://zone.spip.org/trac/spip-zone/changeset/56986 par exemple, qui remplace :
- l’ouverture de la boite :
<div class="cadre cadre-liste">
[(#ENV{titre}|tickets_bouton_block_depliable{#GET{visible,true}|=={true}})]
[(#GET{visible,true}|=={true}|tickets_debut_block_depliable)]
par #BOITE_OUVRIR{#CHEMIN_IMAGE{ticket-24.png}|balise_img{'',cadre-icone}|concat{#ENV{titre}},'simple','titrem'}
- et la fin :
[(#VAL|tickets_fin_block)]
</div>
par #BOITE_FERMER
URLs : generer_url_public
Attention : generer_url_public
générait une url absolue dans SPIP 2,
et génère dans SPIP3 une url relative.
Si vous avez besoin d’une url absolue (par exemple pour la génération d’un mail), il faut désormais entourer ses appels par un appel à url_absolue
.
Tables annexes gérées par le plugin
Le fichier pour installer ou mettre à jour la base de
données en SPIP 2 ne sera pas pris en compte : avec SPIP 3, il faut déplacer la fonction d’installation des tables [1] (en supposant que « PLUGIN » est le préfixe du plugin) :
de /base/PLUGIN_install.php
dans /PLUGIN_administrations.php
[1] Sinon, l’activation se passe bien, mais renvoie un message d’échec à l’installation, en l’exécutant : cela peut-être gênant pour l’utilisateur.