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

Comment on this article

Who are you?
  • [Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom

updated on 1 December 2018