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

Si « truc » est le préfixe d’un plugin, un raccourci vers la page de config est automatiquement ajouté dans la page d’admin des plugins (avec l’icone « tournevis et clé à molette »).

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