Formulaire de configuration avec le plugin Saisies

Cet article explique comment créer avec le plugin Saisies 3.51.0 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

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' => '<: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'

Le plugin s’occupe d’interpréter la chaîne de langue.
Et c’est tout ! Nous obtenons notre formulaire de configuration.

Formulaire de configuration, au départ
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 !

Discussion

One discussion

  • 4

    Bonjour,
    Dans le cas d’un formulaire de configuration de couleurs dans l’espace privé,
    On affiche les codes couleurs inscrits dans la base grâce à lire_config() et on affiche un aperçu mais si on change le code couleur, est-il possible de modifier l’aperçu sans valider le formulaire ?
    Cordialement.
    Didier.

    • Bah c’est pas directement lié à saisies, mais oui ca devrait être possible moyennant un peu de javascript... faut coder quoi :)

    • Merci pour ta réponse.
      Je ne suis pas spécialiste de js donc ça va être compliqué.
      Sinon, comment utiliser la transparence avec “Palette” sur une entrée ’couleur’ ?
      Didier.

    • je ne sais pas...

    • Tant pis. Merci.

    Reply to this message

Add a comment

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite / PostgreSQL
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparait.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

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