Carnet Wiki

Migrer un plugin vers spip3

Version 35 — Mars 2016 erational

<blockquote class="spip">

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

</blockquote>


-  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 en 3.1 est disponible via le menu de développement (à activer les options personnelles)
ou simplement via l’adresse /ecrire/ ?exec=navigation&menu=menu_developpement

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

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 '' NOT NULL", 
	     "id_lettre"             => "BIGINT (21) DEFAULT '' 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