Configuring a feature of your site or a plugin

Configuration Form

Suppose you have a ‘thing’ feature to configure.

1. Create a CVT form whose name begins with ‘configure_’, with just the HTML file and without the PHP (and therefore without defining the load, verify and process functions) [1].
2. create a page configure_thing.html in private/squelettes/contenu/, inside your plugin or your skeleton directory. Inside, call the form with simply #FORMULAIRE_CONFIGURER_THING

That’s all!

Configuring a plugin

When a plugin has a configuration page, a ‘Configure’ option leading to this page automatically appears next to this plugin in the plugin administration page.

This page is defined by the template prive/squelettes/contenu/configurer_prefixeplugin.html and most often uses a configuration form.

Example: for the “mediabox” plugin, the file prive/squelettes/contenu/configurer_mediabox.html contains:

[(#AUTORISER{configurer,mediabox}|oui)
	<h1><:mediabox:titre_page_configurer_box:></h1>
	<div class="ajax">
		#FORMULAIRE_CONFIGURER_MEDIABOX
	</div>
]

If you want an entry to also appear in the menus in the private area to give you direct access to this configuration page, add a <menu> entry in the paquet.xml file.

Example :

<menu nom="thing" titre="prefixeplugin:itemdelangue_thing" parent="bando_configuration" icone="images/thing-16.png" />

To initialise the value of a configuration (e.g. the in_the_spotlight parameter) when creating or updating the plugin, add the following to the myplugin_upgrade() pipeline:

• during creation:

  $maj['create'] = array(
  	array('ecrire_config','myplugin/in_the_spotlight', '3'),
  );
  

• during an update:

  $maj['0.1'] = array(
  	array('ecrire_config','myplugin/in_the_spotlight', '3'),
  );
  

To clear the value when uninstalling the plugin, add the following to the pipeline: myplugin_vider_tables():

effacer_config("myplugin/in_the_spotlight");

Access configured values

In a template, the value of a configuration can be accessed using the #CONFIG tag (for example #CONFIG{myplugin/in_the_spotlight})

In PHP the values can be accessed in read mode using the lire_config function with lire_config(“myplugin/in_the_spotlight”).

When writing, use the ecrire_config function:
ecrire_config('myplugin/in_the_spotlight', 3)

Autorisations

Not all users have access to the configuration page. By default, only administrators have this option, but you can redefine access rights to your configuration form. To do this, use the php authorise API, as well as the #AUTHORISE tag and the otherwise_deny_access filter for your form template.

Example : [(#AUTORISER{configurer,mediabox}|sinon_interdire_acces)]

Customise treatments

Sometimes, other specific treatments are required when configuration values are changed. In this case, the usual traiter() function from the CVT API must be added, and the common function that handles configuration processing must be called:

function formulaires_configurer_myplugin_traiter_dist() {
	include_spip('inc/cvt_configurer');
	$retours = array();
	
	// The new configuration is saved.
	$trace = cvtconf_formulaires_configurer_enregistre('configurer_myplugin', array());
	
	// Customised treatments
	// …
	
	$retours['message_ok'] = _T('config_info_enregistree') . $trace;
	$retours['editable'] = true;
	
	return $retours;
}

Use another table to store the configured values

By default, the configured values are stored in the spip_meta table, and the entire table is loaded into memory with each hit. However, it is possible to use another table to store the configured values.

For example, to use the meta_myplugin table, add the following line to the configuration form:

<input type="hidden" name="_meta_table" value="meta_myplugin" />

Then, to access the values stored in this table, specify the table name prefixed with a / at the beginning of the lire_config argument:

ecrire_config('/meta_myplugin/description', 'blah');
lire_config('/meta_myplugin/argument');

In addition to _meta_table, the name of the table where the configured values are stored, there are three other useful variables to change where or how the configuration is saved:

• _meta_casier: name of the ‘casier’ in which to serialise (by default, this is the xx from formulaire_configurer_xx)
• _meta_prefixe: prefix the meta (alternative to the casier) in the meta table (no default prefix)
• _meta_stockage: use an external storage method. None are provided by the core.