cfg: références

Explications détaillées sur l’utilisation de CFG, le plugin de configuration.

CFG est un plugin pour SPIP qui facilite le paramétrage d’autres plugins ou squelettes en permettant de créer facilement des formulaires de configuration.

Cet article explique les bases de création de ces formulaires et l’utilisation des données issues de ceux-ci. Des liens sont proposés dans l’article découvrir les fonctions avancées de CFG.

Unique fichier de configuration

CFG a été motivé par le besoin récurrent de fabriquer des configurations de plugins ou squelettes.

Son leitmotiv est donc la simplicité. C’est pourquoi une configuration “quelque_chose” (un plugin, un squelette ou ce que l’on veut) est basée sur l’unique fichier fonds/cfg_quelque_chose.html [1].

Ce “fond” contient un formulaire et des propriétés/options qui sont transmises à CFG.

La modification des données (par un administrateur du site) se fait par simple appel de l’action CFG comme
ecrire/?exec=cfg&cfg=quelque_chosequelque_chose correspond au nom du fichier fonds/cfg_quelque_chose.html.

Le formulaire

Il s’agit d’un formulaire HTML standard, interprété comme un squelette. Les données gérées sont reconnues d’après l’attribut “name” des balises de formulaire comme

  • <input type="text" name="truc"...>,
  • <select name="truc"...>,
  • <textarea name="truc" ...>,
  • etc.

Notes sur le nomage des attributs “name”

  • Les noms commençant par _cfg_ sont réservés au fonctionnement interne.
  • Les noms commençant par id_ peuvent poser problème. [2]

Transmettre une action sécurisée
L’action du formulaire étant sécurisée, il faut lui adjoindre les données de contrôle, tout simplement en faisant suivre <form ...> par des “hidden” le plus simple étant:
<form method="post" action="#SELF">[(#ENV{_cfg_}|form_hidden)]

Boutons d’envoi et de suppression
Enfin, les submit de validation ou de suppression doivent être nommés respectivement _cfg_ok ou _cfg_delete (noms réservés)

Formulaire minimal

Un formulaire minimal serait donc:

<form method="post" action="#SELF"><div>[(#ENV{_cfg_}|form_hidden)]

<input type="text" name="mon_text" value="#ENV{mon_text}" />
<textarea name="mon_area">[(#ENV{mon_area})]</textarea>

<input type="submit" name="_cfg_ok" value="<:OK:>" />
<input type="submit" name="_cfg_delete" value="<:Supprimer:>" />
</div></form>

Comme on peut le voir, les valeurs des données sont récupérables par #ENV{truc}

Important : La méthode d’analyse des formulaires de CFG implique de respecter l’ordre suivant (type puis name, puis les éventuelles class css, puis le reste) dans les balises utilisées (textearea, select, input...).
<input type=... name=... class=... .../>
<textearea/select name=... class=... .../>

Les propriétés de l’objet cfg

Il est possible en plaçant des remarques au format html commençant par propriete= de spécifier des propriétés intrinsèques de l’objet CFG qui manipulera le formulaire.

Par exemple, on peut ainsi définir le titre du formulaire (notez l’espace après <!-- et le = collé au nom du paramètre) :
<!-- titre=Le titre du formulaire -->

Il est possible alors de jouer avec les balises SPIP et les fichiers de langue :
<!-- descriptif=<multi>[fr]Descriptif français [en]In english</multi>-->
<!-- descriptif=<:prefixe_plugin:description_plugin:>-->
Ici, le descriptif sera complètement interprété, comme un squelette ... y compris boucles et toute la machine de guerre SPIP.

Propriété Description
titre Un des 2 titres, fera le gros titre si boite est aussi présent
boite Le titre de la boite formulaire, défaut titre si présent, ’Configuration machin" sinon
descriptif Le descriptif affiché en haut de colonne gauche
nom Le nom du meta où sera stockée la configuration, par défaut c’est le nom du formulaire, xxx dans fonds/cfg_xxx

Il existe d’autres propriétés avancées que vous pouvez trouver dans l’article API CFG : Paramètres des formulaires

Utilisation des données

Les données stockées sont sérialisées sous le nom “quelque_chose” dans la table spip_meta.

On les récupère dans les squelettes avec la balise #CONFIG qui est étendue par cfg pour extraire les subdivisions avec le séparateur /
Par exemple #CONFIG{quelque_chose/mon_area} donnera la valeur du champs mon_area produite par le formulaire fonds/cfg_quelque_chose.html

Depuis le php, on peut utiliser similairement lire_config('quelque_chose/mon_area')

#CONFIG{} ou lire_config() admettent comme deuxième paramètre la valeur à retourner par défaut. Par exemple #CONFIG{quelque_chose/mon_area,defaut area} donnera defaut area si quelque_chose ou mon_area sont vides.

Footnotes

[1Le “fond” CFG utilisé sera le premier trouvé dans l’ordre des priorités de SPIP... En priorité dans le répertoire squelettes/, puis dans un des plugins actifs, puis dans dist/, puis dans ecrire/

[2Les variables postées commençant par “id_” vont s’inscrire dans la la chaine produite par la balise #SELF (comportement standart de SPIP). Si #SELF est utilisée dans le formulaire CFG par <form method="post" action="#SELF">, c’est sa valeur qui sera prise en compte par SPIP lors de l’envoi du formulaire, et non la nouvelle valeur choisie par l’utilisateur (en fait, 2 variables sont envoyées : une en GET (avec l’action="#SELF" et une en POST (le champ du formulaire) de même nom, et SPIP prend prioritairement GET lorsque l’on demande une variable avec sa fonction _request()

Evidemment, toute contribution est la bienvenue, vous pouvez facilement demander à devenir co-rédacteur.

Discussion

No discussion

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