Migrer un plugin vers spip 3

Version 13 — Janvier 2012 — 78.221.xx.xx

- 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 : " class="spip_url spip_out auto" rel="nofollow external">https://spreadsheets.google.com/spreadsheet/ccc?key=0Aq-LDsZ2YhzydDBvMjRSamQ5aWtfNWpKcnFESjQwU3c&hl=fr&authkey=CMmWhpEC
- [migrer un plugin vers spip2->2947]
- [Créer un nouvel objet dans le futur SPIP 3->http://marcimat.magraine.net/Chats-2-SPIP-3]
- [Doc Spip 3 en cours de rédaction->http://www.spip.net/ecrire/?exec=articles&id_article=5427]
- [Configurer une fonctionnalité de votre site, ou un plugin->http://www.spip.net/fr_article5414.html]
- [CFG : comment s’en passer !->http://www.spip-contrib.net/CFG-comment-s-en-passer]
- [Rédaction du paquet.xml->http://plugins.spip.net/redaction-du-paquet-xml.html]
- Ça peut servir de respecter la charte typographique : /?exec=charte

</blockquote>

- migrer un plugin vers spip2

- Créer un nouvel objet dans le futur SPIP 3

- Doc Spip 3 en cours de rédaction

- Configurer une fonctionnalité de votre site, ou un plugin

- CFG : comment s’en passer !

- Rédaction du paquet.xml

--------------------------

Détecter et comparer - Ça peut servir de respecter la version de spip pour s’adapter

charte : < code >/ ? exec=charte

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

----------------------------- </quote >

_ spip_log("ACTION ACTUALISER DEPOT (manuel) : id_depot = ". $id_depot, 'svp'); 
_ devient
_ spip_log("ACTION ACTUALISER DEPOT (manuel) : id_depot = ". $id_depot, 'svp_actions.' . _LOG_INFO);


spip_log("Categorie absente dans le paquet issu de <". $insert_paquet['src_archive'] ."> du depot <" . $insert_paquet['id_depot'] . ">\n", 'svp_paquets'); 
_ devient
_ spip_log("Categorie absente dans le paquet issu de <". $insert_paquet['src_archive'] .  "> du depot <" . $insert_paquet['id_depot'] . ">\n", 'svp_paquets.' . _LOG_INFO_IMPORTANTE);

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

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>

et la fonction function spip2spip_ajouterBoutons($boutons_admin) est supprimée.

Logs avec niveaux

Le niveau de log doit apparaître en 2^e argument ou être concaténé au nom du fichier de log s’il y en a un en 2^e argument .

Les différents Il y a d’autres niveaux de logs , par ordre de notabilité décroissante , sont log :
- _LOG_HS , _LOG_ALERTE_ROUGE , _LOG_CRITIQUE , _LOG_ERREUR , _LOG_AVERTISSEMENT , _LOG_INFO_IMPORTANTE , _LOG_INFO , _ LOG_INFO LOG_ERREUR

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 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';

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

Retour à la version courante

Migrer un plugin vers spip 3

Détecter et comparer - Ça peut servir de respecter la version de spip pour s’adapter

Motclés

Auteurs

Associer un auteur à un article

Procédure d’upgrade des plugins

Filtre icone pour la partie privée

Configurations

insert_head et insert_head_css

Un exemple de migration

Toutes les versions