Developers’ guide to I/E config

This post describes the whole process to declare your own plugin’s settings to I/E config.

Plugins storing their settings in MySQL data table spip_meta

A large majority of plugins are storing their settings in MySQL data table spip_meta (specially those using CFG, before SPIP 3). For those plugins, declaring the metas you’d wish to set import/export-able is quite simple, through pipeline ieconfig_metas.

I/E config will then generate a light import/export form with a checkbox for your plugin.

You’ll have to declare ieconfig_metas pipeline first in your package file :

your-plugin-prefix/plugin.xml (SPIP 1.9/2.*) :

	...
	<pipeline>
		<nom>ieconfig_metas</nom>
		<inclure>your-plugin-prefix_ieconfig_metas.php</inclure>
	</pipeline>
	...

your-plugin-prefix/paquet.xml (SPIP 3.*) :

	...
	<pipeline nom="ieconfig_metas" inclure="your-plugin-prefix_ieconfig_metas.php" />
	...

then create a your-plugin-prefix_ieconfig_metas.php file, containing :

<?php

function your-plugin-prefix_ieconfig_metas($table){
	$table['your-plugin-prefix']['titre'] = name_of_plugin;
	$table['your-plugin-prefix']['icone'] = 'path/to/image.png';
	$table['your-plugin-prefix']['metas_brutes'] = 'meta1,meta2,meta3';
	$table['your-plugin-prefix']['metas_serialize'] = 'meta4,meta5,meta6';
	return $table;
}

?>

metas_brutes indicates which metas we want to export « as is », when metas_serialize indicates metas which are stored serialized (which should be the case with CFG in a current workflow).

If there is several metas to save, you have to separate them with a comma (don’t enter any space).

Your plugin has to offer a 16px by 16px icon version, to integer I/E config’s UI.
Besides, with SPIP 3, if this icon is placed into a admin area’s skin directory — e.g. YOUR-PLUGIN/prive/themes/spip/images/ is a classic one if you don’t have any personal skin for the admin area — for I/E config, its name is sufficient, you do not need to indicate the full path.

Concrete examples :

In plugin Metas (SEO) :

function metas_ieconfig_metas($table){
	$table['metas']['titre'] = _T('metas:configuration_metas');
	$table['metas']['icone'] = 'images/metas-16.png';
	$table['metas']['metas_brutes'] = 'spip_metas_title,spip_metas_description,spip_metas_keywords,spip_metas_mots_importants';
	return $table;
}

in plugin Dublin Core (who used to work with CFG, prior to SPIP 3) :

function dublin_core_ieconfig_metas($table){
	$table['dublin_core']['titre'] = _T('dublin_core:dublin_core');
	$table['dublin_core']['icone'] = 'dublin_core-16.png';
	$table['dublin_core']['metas_serialize'] = 'dublin_core';
	return $table;
}

If you need forms to import/export your data and/or any advanced treatment, then you’ll have to go through another ieconfig pipeline.

How to set a meta prefix ?

Starting I/E config version 1.3.0, it’s now possible through ieconfig_metas pipeline to set a meta prefix, followed by an asterisk « * ».

E.g :

<?php

function your-plugin-prefix_ieconfig_metas($table){
	$table['your-plugin-prefix']['titre'] = nom_du_plugin;
	$table['your-plugin-prefix']['icone'] = 'chemin/image.png';
	$table['your-plugin-prefix']['metas_serialize'] = 'titi,toto_*';
	return $table;
}

?>

In this case, meta titi and every meta with names beginning with toto_ would be exported.

ieconfig pipeline for full custom imports/exports

Your plugin has to plug into iecfg pipeline before it can import/export any settings through I/E config.

This pipeline is called 4 times :

  • to build the export form
  • to build the array containing the settings to export
  • to build the import form
  • to save imported settings to the database

For a code example, see http://svn.spip.org/trac/spip-zone/... or http://zone.spip.org/trac/spip-zone... on SPIP Zone plugins repository.

Building the export form

To build the export form, ieconfig pipeline is called, with argument $flux['args']['action']='form_export'.

$flux['args']['data'] contains an inputs array (see Saisies) . We’ll then add our plugin’s inputs options to this array, grouped into a fieldset named after the plugin’s prefix. Inputs options names will all begin with yourprefix_ to avoid glitches with other plugins.

At least, plugin should offer to export — or not to — its settings.

You also can provide those inputs with checking criterias (see Saisies : Doc complémentaire).

Array to be exported

To build the export array, ieconfig pipeline is called, with argument $flux['args']['action']='export'.

User-selected export parameters are accessible through the _request() function.

$flux['args']['data'] contains the all-data-to-be-exported array.
The plugin will add a new item to that array, with plugin’s prefix as a key, containing the settings about to be exported.

Building the import form

To build the import form, ieconfig pipeline is called, with argument $flux['args']['action']='form_import'.
$flux['args']['action']='config' contains the data-to-be-imported array.

$flux['args']['data'] contains an inputs array (see Saisies) . We’ll then add our plugin’s inputs options to this array, if & only the data-to-be-imported array has something to import for that plugin (items having plugin’s prefix_ as their key). They’ll be grouped in a fieldset named after the plugin’s prefix. Inputs options names will all begin with yourprefix_ to avoid glitches with other plugins.

At least, plugin should offer to import — or not to — its settings.

You also can provide those inputs with checking criterias (see Saisies : Doc complémentaire).

Importing settings

To import config, ieconfig pipeline is called, with argument $flux['args']['action']='import'. $flux['args']['action']='config' the arrray about to be imported.

User-selected import parameters are accessible through the _request() function.

$flux['args']['data'] contains an error message, to be displayed in case any issue is met. The plugin will complete if an error is met during the import.

Providing config files in a plugin

A plugin — among others, templates-provider plugins — depending on several other plugins, might then come with one starter settings/config file, or more : Just place the .YAML config files in a ieconfig/ sub-directory, and you’re good to go !

We can also stipulate that this YAML config file should NOT be processed by I/E config unless some other plugins are installed & active on the website. We get this done with necessite (’needs’ in french) :

- necessite:
  - 'some_plugin'
  - 'some_other_one'

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom