Formulaire de configuration avec le plugin Saisies

Cet article explique comment créer avec le plugin Saisies 4.0.0 ou ultérieur un formulaire de configuration pour un plugin. Il suppose l’utilisation de PHP 7 pour les styles d’écriture.

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="[4.0.0;4.2.*]"
>
	<nom>Mon super plugin</nom>


	<necessite nom="saisies" compatibilite="[4.0.0;[" />
</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 [1] ;
-  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.
 * @return array
 **/
function formulaires_configurer_mon_super_plugin_saisies_dist(): array {
	// $saisies est un tableau décrivant les saisies à afficher dans le formulaire de configuration
	$saisies = [
		[
			'saisie' => 'case',
			'options' => [
				'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

Il est possible d’enregistrer les champs dans un autre casier de config que celui par défaut qui est le nom du formulaire après configurer (ici mon super_plugin). Pour cela, il faut une saisie cachée (hidden) de nom _meta_casier :

[
    'saisie' => 'hidden',
    'options' => [
        'nom' => '_meta_casier',
        // Les champs seront stockés tels que #CONFIG{autre/rangement/ma_super_option}
        'defaut' => 'autre/rangement',
    ],
]

É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 !

Notes

[1Le souligné devant mon_super_plugin est volontaire : cela permet de ne pas considérer le plugin comme un type d’objet SPIP.

Discussion

Une discussion

  • [    'saisie' => 'hidden',    'options' => [        'nom' => '_meta_casier',        // Les champs seront stockés tels que #CONFIG{autre/rangement/ma_super_option}        'defaut' => 'autre/rangement',    ], ]
    fonctionne très bien mais comment faire si je veux utiliser une autre table meta comment mettre : _meta_table avec cette syntaxe
    merci .

    Répondre à ce message

Ajouter un commentaire

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
  • 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 apparaît.

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.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom