Formulaire de configuration avec le plugin Saisies

Cet article explique comment créer avec le plugin Saisies 3.37.1 ou ultérieur un formulaire de configuration pour un plugin.

But

Le but est de proposer un formulaire de configuration simple pour un plugin mon super plugin contenant une unique option sous forme de case à cocher “ma super option”.

Intérêt d’utiliser Saisies pour créer un formulaire de configuration

L’intérêt d’utiliser Saisies plutôt que d’écrire directement en squelette est :
-  de pouvoir décrire ses options selon une syntaxe claire, uniforme, tout en s’assurant que le formulaire respectera automatiquement la structure des formulaires SPIP ;
-  de gérer automatiquement les messages d’erreurs et de retours en définissant des vérifications saisie par saisie. Nous ne documenterons pas ici cet aspect.

Pré requis

Le présent tutoriel nécessite au minimum la version 3.37.1 du plugin Saisies.

Étape 1 : le paquet.xml

Il s’agit d’un paquet.xml minimum, qui se contente d’indiquer la version minimum du plugin Saisies.

<paquet
	prefix="mon_super_plugin"
	categorie="communication"
	version="1.0.0"
	etat="stable"
	compatibilite="[3.2.0;3.2.*]"
>
	<nom>Mon super plugin</nom>
 
 
	<necessite nom="saisies" compatibilite="[3.37.1;[" />
</paquet>

Étape 2 : la page de configuration

Elle sera automatiquement liée depuis la page de gestion des plugins.

Liens vers le formulaire de configuration
Liens vers le formulaire de configuration

Il s’agit là du mécanisme standard de SPIP, cf. la documentation de SPIP.

Voici à quoi cela ressemble dans notre cas.

Créer un squelette prive/squelettes/contenu/configurer_mon_super_plugin.html :

[(#AUTORISER{configurer,mon_super_plugin}|sinon_interdire_acces)]
<h1 class="grostitre"><:mon_super_plugin:configurer:></h1>
<div class="ajax">
#FORMULAIRE_CONFIGURER_MON_SUPER_PLUGIN
</div>

Comme on le voit, cette page se contente :
-  de vérifier l’autorisation de configurer et d’interdire l’accès en l’absence d’autorisation ;
-  de mettre un titre grâce à une chaîne de langue ;
-  d’appeler le formulaire de configuration.

La chaîne de langue est définie dans le fichier lang/mon_super_plugin_fr.php :

<?php
if (!defined('_ECRIRE_INC_VERSION')) {
	return;
}
 
$GLOBALS[$GLOBALS['idx_lang']] = array(
	'configurer' => 'Configurer mon super plugin',
);

Étape 3 : création du formulaire

Il s’agit de l’étape qui tire profit des fonctionnalités du plugin Saisies (dans sa version 3.37.1 ou ultérieur). Il faut créer :
-  un fichier formulaires/configurer_mon_super_plugin.html, entièrement vide, sans même une espace;
-  un fichier formulaires/configurer_mon_super_plugin.php contenant une unique fonction configurer_mon_super_plugin_saisies_dist() renvoyant un tableau de saisies.

<?php
if (!defined('_ECRIRE_INC_VERSION')) return;
 
 
/**
 * Un simple formulaire de config,
 * on a juste à déclarer les saisies
 **/
function formulaires_configurer_mon_super_plugin_saisies_dist(){
	// $saisies est un tableau décrivant les saisies à afficher dans le formulaire de configuration
	$saisies = array(
		array(
			'saisie' => 'case',
			'options' => array(
				'nom' => 'ma_super_option',
				'label_case' => _T('mon_super_plugin:configurer_ma_super_option_label_case'),
				'conteneur_class' => 'pleine_largeur'
			)
		)
	);
	return $saisies;
}

Le tableau est décrit selon la norme de déclaration en PHP. On se référera à l’article “Référence des saisies” pour les détails.

À noter que pour cet exemple :
-  nous n’avons pas mis de label, mais uniquement un label_case qui, pour le cas des saisies case correspond au label HTML stricto_sensu;
-  nous avons dit que cette saisie case est en pleine largeur;
-  nous avons une chaîne de langue configurer_ma_super_option_label_case, ainsi déclarée dans lang/mon_super_plugin_fr.php.

	'configurer_ma_super_option_label_case' => 'Ma super option'

Et c’est tout ! Nous obtenons notre formulaire de configuration.

Formulaire de configuration, au départ
Formulaire de configuration, au départ
Formulaire de configuration, après modification d'une option
Formulaire de configuration, après modification d’une option

Étape 4 : profiter!

Il est désormais possible d’accéder à la valeur de la configuration :

  • en squelette : #CONFIG{mon_super_plugin/ma_super_option};
  • en PHP : lire_config('mon_super_plugin/ma_super_option').

En pièce jointe, le zip du plugin de démonstration.

Un super plugin avec une super option !

updated on 12 May 2020

Discussion

Aucune discussion

Ajouter un commentaire

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