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 "machin" (un plugin, un squelette ou ce qu’on veut) est basée sur l’unique fichier fonds/cfg_machin.html, le premier trouvé dans l’ordre des priorités de spip ... dans squelettes/, un des plugins actifs ou dist/.

Ce "fond" contient essentiellemnt un formulaire et optionnellement des propriétés pour l’objet cfg de contrôle.

On trouve dans l’archive de ce plugin des fonds d’exemple, dans le sous-dossier fonds/, par ailleurs, de nombreux plugins ou squelettes l’utilisent déjà pour gérer leur propre configuration. Cherchez les fonds/cfg_xxx chez crayons, csv2spip, etc.

La modification des données se fait par simple appel de l’action cfg comme ecrire/?exec=cfg&cfg=machin

Le formulaire

Il s’agit d’un formulaire HTML standard, interprété comme un squelette. Les données gérées sont reconnus d’après l’attribut "name" des balises de contrôles classiques d’un formulaire comme
 <input type="text" name="truc"...>,
 <select name="truc"...>,
 <textarea name="truc" ...>,
 .etc.

Vous ne devez pas utiliser de nom commençant par _cfg_, ils sont réservés au fonctionnement interne.

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">[(#ENV{_cfg_}|form_hidden)]

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

Un formulaire minimal serait donc :

Comme on peut le voir, les valeurs des données son passées dans le contexte, donc 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 le reste) dans les balises utilisées (textearea, select, input...).
<input type=... name=... .../>
<textearea/select name=... .../>

Les propriétés de l’objet cfg

Il est possible en plaçant des remarques 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 :
[(#REM) titre=Le titre du formulaire]
Un tel commentaire SPIP sera simplement passé dans propre(), une simple mise en forme.

On peut aussi utiliser des commentaires HTML comme :
<!-- descriptif=<multi>[fr]Descriptif français [en]In english</multi>-->
Ici, le descriptif sera complètement interprété, comme un squelette ... y compris boucles et toute la machine de guerre SPIP.

Si vous ne désirez qu’une mise au propre de base, il faut donc préférer la première méthode en commentaire spip, moins lourde.

Il existe d’autres propriétés avancées que vous pouvez trouver dans l’article Configurations avancées avec CFG

Utilisation des données

Les données stockées sont sérialisées sous le nom "machin" 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{machin/mon_area} donnera la valeur du champs mon_area produite par le formulaire fonds/cfg_machin.html

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

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

Balise #CFG_ARBO : petite aide au développement

La version 1.0.10 introduit la balise #CFG_ARBO afin de faciliter la phase de développement du plugin utilisant CFG. Sa présence dans un fond, dans la partie privée de SPIP, liste les champs stockés dans la table spip_meta ou dans le paramètre qui lui est passé, sur le même principe que #CONFIG. Ainsi, #CFG_ARBO{squelette} va lister tous les champs enregistrés dans spip_meta/squelette de l’exemple précédent.