Configurer une fonctionnalité de votre site, ou un plugin

Formulaire de configuration

Supposons que vous ayez une fonctionnalité "truc" à configurer.

1. créez un formulaire CVT dont le nom commence par « configurer_ », avec juste le fichier HTML et sans le PHP (et donc sans définir les fonctions charger, verifier et traiter) [1].
2. créez une page configurer_truc.html dans prive/squelettes/contenu/ (pour SPIP 3) ou dans prive/exec/ (pour SPIP 2), à l’intérieur de votre plugin ou de votre répertoire squelettes. Dedans, appelez le formulaire avec simplement #FORMULAIRE_CONFIGURER_TRUC

C’est tout !

Configuration d’un plugin

Lorsqu’un plugin dispose d’une page de configuration, une option "Configurer" amenant à cette page apparaît automatiquement dans la ligne présentant ce plugin dans la page d’administration des plugins.

Cette page est définie par le squelette prive/squelettes/contenu/configurer_prefixeplugin.html et fait le plus souvent appel à un formulaire de configuration.

Exemple : Pour le plugin ’mediabox’, le fichier prive/squelettes/contenu/configurer_mediabox.html contient :

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

Si vous souhaitez qu’une entrée apparaisse également dans les menus de la partie privée pour vous donner un accès direct à cette page de configuration, ajoutez une entrée <menu> dans le fichier paquet.xml.

Exemple :

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

Pour initialiser la valeur d’une configuration (paramètre "a_la_une", par exemple) lors de la création ou de la mise à jour du plugin, ajouter, dans le pipeline monplugin_upgrade() :

• lors de la création :

  $maj['create'] = array(
  	array('ecrire_config','monplugin/a_la_une', '3'),
  );
  

• lors d’une mise à jour :

  $maj['0.1'] = array(
  	array('ecrire_config','monplugin/a_la_une', '3'),
  );
  

Pour effacer la valeur lors de la desinstallation du plugin, ajouter, dans le pipeline monplugin_vider_tables() :

effacer_config("monplugin/a_la_une");

Accéder aux valeurs configurées

Dans un squelette, on accède à la valeur d’une configuration au moyen de la balise #CONFIG (par exemple #CONFIG{monplugin/a_la_une})

En php on accèdera en lecture aux valeurs avec la fonction lire_config avec lire_config('monplugin/a_la_une').

En écriture, on utilisera la fonction ecrire_config :
ecrire_config('monplugin/a_la_une', 3)

Autorisations

Tous les internautes n’ont pas accès à la page de configuration. Par défaut, seuls les administrateurs ont cette possibilité, mais vous pouvez redéfinir les droits d’accès à votre formulaire de configuration. Utilisez pour cela l’API php autoriser, ainsi que la balise #AUTORISER et le filtre sinon_interdire_acces pour votre squelette de formulaire.

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

Personnaliser les traitements

Parfois, on a besoin de faire d’autres traitements précis lorsque des valeurs de configuration sont changées. Dans ce cas il faut ajouter la fonction traiter() habituelle de l’API CVT, et appeler la fonction commune qui s’occupe de traiter les configurations :

function formulaires_configurer_monplugin_traiter_dist() {
	include_spip('inc/cvt_configurer');
	$retours = array();
	
	// On enregistre la nouvelle configuration
	$trace = cvtconf_formulaires_configurer_enregistre('configurer_monplugin', array());
	
	// Traitements personnalisés
	// …
	
	$retours['message_ok'] = _T('config_info_enregistree') . $trace;
	$retours['editable'] = true;
	
	return $retours;
}

Utiliser une autre table pour stocker les valeurs configurées

Par défaut, les valeurs configurées sont stockées la table spip_meta, et l’intégralité de cette table est chargée en mémoire à chaque hit. Il est toutefois possible d’utiliser une autre table pour stocker les valeurs configurées.

Par exemple, pour utiliser la table meta_monplugin, il faut ajouter la ligne suivante dans le formulaire de configuration :

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

Puis, pour accéder aux valeurs enregistrées dans cette table, indiquer le nom de la table préfixé par un / au début de l’argument de lire_config :

ecrire_config('/meta_monplugin/descriptif', 'blah');
lire_config('/meta_monplugin/argument');

Outre _meta_table, le nom de la table où stocker les valeurs configurées, il existe 3 autres variables utiles pour varier l’endroit ou la méthode d’enregistrement de la configuration :

• _meta_casier : nom du "casier" dans lequel sérialiser (par défaut c’est le xx de formulaire_configurer_xx)
• _meta_prefixe : préfixer les meta (alternative au casier) dans la table des meta (pas de préfixe par défaut)
• _meta_stockage : utiliser une méthode externe de stockage. Aucune n’est fournie par le core.