CFG multi : didacticiel

Avant-Propos

Bonjour à tous :-)

Pour des besoins personnels, j’ai récemment entrepris d’explorer quelque peu le plugin CFG, conçu et réalisé par notre regretté ami Toggg [1].

Suite à quelques échanges sur la liste de discussion de Spip-Zone, il s’avère que certaines fonctionnalités du plugin CFG restent encore méconnues, surtout par manque de documentation. "L’ailleurs" l’ayant appelé hélas trop tôt, Toggg n’a pas eu le temps de la compléter.

Répondant donc à plusieurs demandes, j’ai accepté de faire un petit article afin de partager ici quelque unes de mes découvertes, notamment en ce qui concerne la méthode "multi" de CFG.

Ce didacticiel n’est donc qu’un complément aux autres excellents articles déjà parus sur SPIP-Contrib à propos de CFG :

 Coder un plugin simple avec cfg ;
 Cfg : références.

Introduction

CFG est l’un des plugins les plus populaires aujourd’hui, il suffit d’apprécier la liste des autres contributions qui l’utilisent pour s’en convaincre.

Il est né de la nécessité de disposer d’un système de configurations souple et simple d’emploi pour les plugins et squelettes.

Qui dit "configuration", dit besoin de mémoriser un certain nombre d’informations pour pouvoir les utiliser par la suite, pour, par exemple, régler le comportement d’un plugin, conditionner l’affichage d’une partie de squelette, ou, pourquoi pas, sauvegarder puis afficher des données non traitées par défaut par SPIP [2]. C’est à partir de cette dernière utilisation que nous allons explorer quelques particuliarités de CFG.

En règle générale, une seule page de configuration suffit pour régler les options nécessaires au fonctionnement d’un plugin, mais qu’en est-il si nous souhaitons mémoriser la configuration de plusieurs éléments de même nature ?

Parmi ses nombreuses fonctionnalités, CFG en propose une particulièrement adaptée à la configuration de plusieurs éléments ayant tous les mêmes types de données à mémoriser. Il s’agit de la méthode "multi" [3].

C’est donc cette méthode "multi" que nous tenterons d’étudier dans cet article.

Important !

Ce didacticiel ou tutoriel ne doit en aucun cas être considéré comme une source documentaire de référence, mais plutôt comme un simple exercice pratique d’utilisation d’une des fonctionnalités méconnues de CFG.

Avertissement !

Cet article est relativement long, car il tente d’aborder le sujet de manière à être le plus accéssible possible à la plupart des utilisateurs de SPIP. L’approche progressive retenue et l’effort d’explication des différentes notions abordées, parfois de manière un peu redondante, cherchent à rendre le sujet le plus clair possible, même si on peut déplorer fatalement quelques lourdeurs et longueurs.

Cependant, pour ne pas vous imposer une lecture fastidieuse, si vous êtes déjà familier avec les langages Web comme le Html, le JavaScript et que vous êtes à l’aise avec la syntaxe des boucles de SPIP, vous n’aurez certainement pas besoin de lire l’article in extenso, surtout la partie de conception et réalisation du formulaire de configuration, je vous propose donc deux possibilités pour optimiser votre lécture :

• Si vous n’avez jamais utilisé CFG, ou très peu, je vous invite à commencer votre lecture par le chapitre "Utilisation du Formulaire CFG" ;

• Si vous connaissez déjà CFG, je vous propose de vous rendre directement aux chapitres "CFG multi : Fonctionnement" et suivants.

Bonne lecture...

Le Scénario

Pour mieux illustrer dans quel type de situations cette méthode "multi" de CFG peut s’avérer utile, et surtout fort pratique, plantons un décor quelque peu imaginaire mais tout-à-fait plausible :

• Supposons que nous participons, en tant que responsables et auteurs, à l’animation d’un site spécialisé dans la publication d’articles de vulgarisation de différentes technologies Web ;

• Supposons aussi que ce site compte déjà avec la participation de plusieurs autres auteurs ;

• Supposons maintenant que, pour des besoins d’information auprès des lecteurs, afin de répondre à des nombreuses demandes, on souhaite afficher, sur la page d’infos de chaque auteur (fichier "auteur.html" de SPIP), leurs niveaux de compétence ou qualification dans les différentes technologies Web traitées sur le site ;

• Supposons enfin que, pour des raisons d’impartialité et d’un minimum d’objectivité, ces infos ne puissent être gérées que par les responsables du site.

Voilà pour le contexte.

Bien-sûr, une manière simple de résoudre cette situation, serait d’utiliser le champ "Biographie" de la page "Informations personnelles" de chaque auteur, a priori tout-à-fait indiquée à recevoir de telles infos.

Mais, ce champ restant accessible et modifiable par chaque auteur, les responsables du site ne pourraient pas garantir l’impartialité et objectivité nécessaires pour répondre aux attentes des lecteurs.

Alors, aurait-il une autre solution ?

Peut-être que la plus simple des solutions alternatives c’est CFG qui la propose, grâce à sa méthode "multi".

En effet, étant donnée que nous souhaitons mémoriser le même type d’informations, et le même nombre en l’occurrence, pour chacun des auteurs du site, cette méthode permet d’utiliser un seul et unique fichier de configuration pour tous les auteurs.

Nous allons donc réaliser, dans les chapitres suivants, une page de configuration (formulaire CFG) afin de pouvoir mémoriser ces informations, puis nous allons voir comment fonctionne la méthode "multi", enfin, nous verrons comment récupérer les données sauvegardées pour les afficher sur la page "Auteur" de l’espace publique.

Note !

La réalisation de la page de configuration sera décomposée en plusieurs étapes, ceci afin d’avancer de manière progressive et de ne pas risquer de vous décourager avec des codes complexes dès le début. Le revers de la médaille avec cette formule, est que l’article devient fatalement plus long, mais je pense que cette façon de procéder, par étapes successives, permettra une meilleur clarté des notions abordées.

Important !

Nous n’allons pas réaliser un plugin ici, ceci a été largement expliqué dans l’article Coder un plugin simple avec cfg, nous allons juste nous contenter de placer notre fichier Html de configuration dans le squelette actif de notre site.

Le Fichier Html de Configuration

Nous allons donc créer, dans ce chapitre, un fichier Html de configuration, qui contiendra le formulaire CFG qui servira à mémoriser les infos de qualifications techniques de chaque auteur.

Important !

Avant tout, assurez-vous d’avoir, installée et active, la dernière version en date du plugin CFG. Pour récupérer la dernière version, rendez-vous à l’espace de téléchargement de la Spip-Zone. Ce didacticiel à été réalisé avec la version 1.0.10 de CFG, datant du 30 septembre 2007, puis testée sous Spip 1.9.2c.

Pour créer notre fichier de configuration, commençons donc par créer un répertoire nommé "fonds" (en minuscules et au pluriel) à la racine de notre dossier "squelettes" (ou dans le dossier "dist" si vous utilisez le squelette par défaut distribué avec Spip).

Ensuite, dans ce dossier "fonds", créons un fichier Html nommé "cfg_qualif.html".

Le nom de ce fichier est donc composé d’un préfixe "cfg_", absolument nécessaire pour que le plugin puisse le reconnaître comme étant un fichier de configuration, suivi du terme "qualif", abréviation courante de "qualifications", puis l’extension ".html" usuelle.

Nous verrons plus loin que le nom du fichier, c’est-à-dire "qualif" en l’occurrence, aura un rôle important pour bénéficier de certaines fonctionnalités avancées de CFG et de la méthode "multi".

Éditons donc ce fichier "cfg_qualif.html" et concentrons-nous sur la conception et la réalisation du formulaire CFG.

Le Formulaire CFG : 1. Structure

La première étape dans la réalisation du formulaire consiste à imaginer sa structure.

Le formulaire sera divisé en 5 parties aux rôles bien distincts :

• Partie 1 : Paramètres CFG.
  Contiendra les différentes balises "#REM" de paramétrage de CFG ;

• Partie 2 : Auteurs.
  Contiendra la liste des auteurs enregistrés sur le site ;

• Partie 3 : Configuration.
  Contiendra l’identifiant unique de la configuration affichée ou à mémoriser, ainsi qu’une option permettant de créer une nouvelle configuration à partir d’un identifiant modifié ;

• Partie 4 : Niveaux de qualification.
  Contiendra les différents champs pour noter le niveau de qualification Web de l’auteur affiché ou à mémoriser ;

• Partie 5 : Boutons de validation.
  Contiendra les boutons d’enregistrement et suppression de la configuration affichée, ainsi que le bouton d’annulation du formulaire.

Voici à quoi ressemble cette structure :

Et voici le code de cette première étape (qui n’a pas grande utilité pour l’instant, si ce n’est que de visualiser le "squelette" de notre formulaire) :

Petite explication :

• Le code [(#REM) titre=Qualification Auteurs] est un paramétre CFG, il correspond au titre qui sera affiché sur la fenêtre du navigateur et le titre de l’onglet qui sera affiché sur la page "Configuration des modules" de CFG, dans l’espace privé, c’est à dire :

• Ensuite le code #CACHE{0} est nécessaire pour que Spip ne sauvegarde pas ce fichier en cache, ce qui permet de calculer le formulaire et son contenu à chaque rechargement de la page.

• Le code <form method="post">[(#ENV{_cfg_}|form_hidden)] est la méthode "standard" de création de formulaires de CFG, il se charge, notamment, d’insérer automatiquement les champs invisibles nécessaires à l’enregistrement des données.

Enfin, la reste est relativement classique, puisqu’il ne s’agit après-tout que d’un simple formulaire Html, dont nous verrons quelques particularités concernant CFG dans la prochaine étape.

Le Formulaire CFG : 2. Construction

Nous avons donc la structure de base de notre formulaire, attachons-nous maintenant à le construire, en plaçant l’ensemble des champs et boutons nécessaires à l’enregistrement des données.

 Partie 1 : Paramètres CFG

Commençons par ajouter deux paramètres supplémentaires dans la première partie de notre formulaire :

Petite explication :

• La balise [(#REM) descriptif=<h4>Utilisation de la méthode Multi de Cfg</h4>] se charge d’afficher un petit descriptif [4] sur la colonne de gauche du formulaire, ce qui donne :

• La balise [(#REM) liens*=qualif] est un lien direct vers le fichier de configuration lui-même, et qui a la particularité d’activer une option fort intéressante et utile, uniquement disponible avec cette méthode "multi".

Nous verrons plus loin, dans le chapitre concernant l’utilisation du formulaire, ces particularités de CFG.

 Partie 2 : Auteurs

Ensuite, dans la 2e partie de notre formulaire, nous allons afficher un menu déroulant de type <select>...</select> avec la liste des auteurs du site.

Pour ce faire, rien de plus simple (du moins pour les habitués du langage des boucles de Spip), il suffit de faire une petite boucle de type "AUTEURS", puis de récupérer les infos nécessaires.

Voici une première version de ce code :

Donc, rien de bien sorcier, seuls points qui ne sont pas très explicites pour l’instant, c’est sont le code JavaScript onMouseUp et le code #ENV{id}, nous verrons plus loin leur utilité.

 Partie 3 : Configuration

Passons à la 3e partie du formulaire, où nous allons placer un champ de type "text" qui recevra l’identifiant de la configuration, puis un bouton permettant d’afficher la configuration correspondante à l’identifiant utilisé, enfin, une case à cocher permettant de mémoriser une nouvelle configuration si la valeur de l’identifiant a été modifiée.

Ce champ "Id" est peut-être l’un des plus importants de ce type de formulaires, puisque l’ensemble de la méthode "multi" repose sur lui.

En effet, CFG va utiliser la valeur entrée dans ce champ pour créer un "casier" spécialement dédié à contenir les infos de la configuration de l’auteur sélectionné.

En fait, CFG mémorise toutes les informations dans une entrée spécifique de la table "spip_meta" de la base de données de Spip. Cette entrée porte le nom, par défaut, du fichier de configuration (sans le préfixe ni l’extension), "qualif" dans notre cas.

Pour pouvoir hiérachiser les données et ainsi sauvegarder plusieurs configurations dans la même entrée "spip_meta", CFG utilise un sytème de "casiers" [5] mémorisés avec une clé d’identification, et c’est justement cette clé qui est renseignée dans ce champ "Id".

Pour présenter les choses autrement, nous pouvons illustrer la manière dont CFG va enregistrer les configurations dans la base de données, par une structure hiérarchique à deux niveau :

• qualif
  • auteur 1
    • info 1
    • info 2
    • info 3
  • auteur 2
    • info 1
    • info 2
    • info 3
  • etc.

Explication :

• L’élément "qualif" est le nom de l’entrée "spip_meta" crée par CFG dans la base de données, et dans laquelle les configuration seront mémorisées.

• Les différents "auteur N" sont les fameux "casiers" qui vont contenir chacun les infos de chaque auteur, la configuration en somme. Ces "casiers" seront crées automatiquement par CFG avec la valeur entrée dans le champ "Id" grâce à la présence d’un attribut spécial class="cfg_id" (voir les explications plus bas).

• Enfin, les "info N" ce sont les informations mémorisées et c’est en définitive ces données qui seront ensuite récupérées et affichées sur la page "auteur.html".

Voici donc le code de cette partie :

Quelques points importants à retenir de ce code :

• Le bouton "Afficher", qui sert donc à afficher la configuration de l’auteur choisi, dispose d’un attribut "id" qui est surtout utile pour recevoir les données issues du menu déroulant de la liste des auteurs (2e partie), c’est d’ailleurs le rôle du JavaScript onMouseUp attaché à ce menu.

• Le code #ENV{id} du menu auteurs, comme celui de ce bouton "Afficher", sert à récupérer dynamiquement, grâce aux variables d’environnement, la valeur correspondante issue la base de données (tout ce mécanisme est géré par CFG).

• L’attribut class="cfg_id" est l’élément principal de ce formulaire, puisque c’est lui le déclencheur de la méthode "multi". En effet, c’est sa présence qui signale à CFG la manière de mémoriser les données dans la base de données, et c’est justement la valeur contenue par l’objet où il se trouve, qui sera utilisée par CFG comme identifiant lors de la création des différents "casiers" d’enregistrement des configurations.

• L’attribut name="_cfg_affiche" placé dans un objet "input", de type "submit", indique à CFG de lancer une réactualisation de la page avec passage, dans les variables d’environnement, de la valeur du champ ayant l’attribut class="cfg_id", ce qui permet de récupérer les valeurs mémorisées dans la base correspondants à cet identifiant.

Important !

L’attribut name="_cfg_affiche" ne doit pas être modifié, sous peine d’annuler cette fonctionnalité.

 Partie 4 : Niveaux de qualification

La 4e partie du formulaire concerne les différents champs de configuration avec les informations à mémoriser, c’est-à-dire, les valeurs de "qualification technique" de chaque auteur.

Pour ce projet, nous allons utiliser 7 champs correspondants aux langages suivants :
 html ;
 css = Cascading Style Sheets ;
 js = JavaScript ;
 ajax = Asynchronous JavaScript and XML ;
 asp = Active Server Pages ;
 php
 spip = Système de publication pour l’internet p ? [6]

Évidemment, vous pouvez adapter cette partie du formulaire avec d’autres champs, suivant les informations que vous souhaitez mémoriser pour chaque auteur, ici, continuant avec notre exemple, nous avons choisi quelques technologies Web parmi les plus connues et utilisées.

Voici donc le code :

Pas grand chose à signaler sur ce code, sinon que la valeur de chaque objet "input", value="#ENV{xxx}", est dynamiquement récupérée depuis les variables d’environnement, afin d’afficher les bonnes valeurs issues de la base de données, suivant l’identifiant indiqué ou l’auteur choisi.

 Partie 5 : Boutons de validation

Enfin, la 5e et dernière partie de notre formulaire :

Ce sont les boutons par défaut fournis par CFG dans tous ses exemples (voir dans le répertoire "plugins/cfg/fonds/").

Seules petites différences ici, leur positionnement relatif et leurs valeurs, modifiés pour obtenir quelque chose d’un peu plus clair et, à mon avis, ergonomique.

Important !

Les attributs name="_cfg_delete" et name="_cfg_ok" sont absolument nécessaires à CFG, et ne doivent en aucun cas être modifiés, sous peine de dysfonctionnements du plugin.

Après toutes ces modifications, voici à quoi ressemble désormais notre formulaire :

Et voici son code complet :

Le Formulaire CFG : 3. Mise en Forme

Voilà, notre formulaire est bien avancé, si nous le souhaitons, nous pouvons d’ors et déjà l’utiliser pour mémoriser des configurations et utiliser les valeurs enregistrées dans la page "auteur.html" du squelette. Le mécanisme de base nécessaire à CFG est déjà en place, mais, avant de commencer à l’utiliser, je vous propose d’améliorer un peu la mise en forme du formulaire, car, avouons-le, son aspect actuel n’est pas bien zoli-zoli ;-)

 Partie 1 : Paramètres CFG

Dans cette étape nous n’allons rien changer à cette première partie du code.

 Partie 2 : Auteurs

Passons donc directement à la 2e partie.

Jusqu’à là nous utilisions uniquement le "#ID_AUTEUR" comme valeur de sauvegarde des "casiers" de la méthode "multi".

Ceci fonctionne bien, mais dans un souci de plus de clarté, nous verrons plus loin l’utilité, nous allons ajouter le "#LOGIN" de l’auteur, afin d’avoir des "casiers" avec des noms plus parlants, ce qui va nous donner : "#ID_AUTEUR-#LOGIN".

Côté mise en page, nous allons utiliser des tableaux pour assurer une présentation un peu plus "propre" et claire de l’interface, avec quelques styles "en ligne" pour formater précisément la taille de certains éléments. Nous utiliserons ensuite ces mêmes styles sur les tableaux des autres parties du code, afin d’avoir une présentation plus cohérente de l’ensemble du formulaire.

Voici donc le code un peu amélioré de cette 2e partie :

 Partie 3 : Configuration

La 3e partie du code n’aura pas de changements majeurs, juste quelques modifications afin d’adopter une présentation avec des tableaux suivant ce que nous avons fait dans la 2e partie.

On en profite aussi pour donner un "label" plus parlant à la case à cocher qui crée une nouvelle configuration si l’identifiant a été modifié.

Donc, voici le code :

 Partie 4 : Niveaux de qualification

Dans cette 4e partie du code, nous allons aussi, bien-sûr, améliorer la présentation des champs avec toujours des tableaux.

De plus, nous allons définir le type de notation que nous voulons utiliser, pour éviter ou limiter que chacun inscrive des valeurs trop différentes dans chaque champ de qualificaton.

Nous allons donc ajouter une petite note en bas de cette partie en indiquant clairement quelles sont les valeurs permises et/ou souhaitées.

Pour simplifier la notation, puis l’affichage de qualifications, nous allons utiliser un système d’appréciation avec des étoiles (astérisques), sur seulement 4 niveaux de compétences :

• Vide = aucune qualification ;
• * = Pratiquant ;
• ** = Confirmé ;
• *** = Expert.

Voici donc le code amélioré de cette 4e partie :

 Partie 5 : Boutons de validation

Enfin, la 5e partie ne bénéficie que de petites modifications de taille et de positionnement, surtout pour améliorer un peu l’accès au bouton "Enregistrer" et éviter ainsi les "fausses maneuvres" avec les boutons "Annuler" et "Supprimer". Voici le code :

Voyons donc à quoi ressemble maintenant notre formulaire :

Et voci le code complet :

Le Formulaire CFG : 4. Fignolages

Notre formulaire est fin-près, nous pouvons commencer à l’utiliser en l’état.

Seulement, puisque nous sommes dans le chapitre des "fingnolages", profitons pour imaginer une solution qui limite les valeurs à entrer dans les champs de saisie des qualifications. En effet, malgré notre petite note en bas de la 4e partie, rien n’interdit qu’on entre d’autres valeurs dans les champs des qualifications.

Nous pourrions utiliser une fonction JavaScript pour vérifier le contenu de ces champs avant de mémoriser la configuration, mais avant de sortir la grosse artillérie, je pense que dans notre exemple le plus simple serait de remplacer les champs de saisie par des menus déroulants avec les valeurs prédéfinies que nous souhaitons proposer.

Voici un exemple de code de ce menu déroulant :

D’autre part, puisque nous sommes à l’étape des petites retouches de dernière minute, profitons-en pour ajouter quelques info-bulles aux éléments importants, afin d’apporter quelques précisions à l’utilisateur.

Dernier détail, CFG propose, depuis peu, la possibilité de visualiser la structure et les données enregistrées dans la base de données, grâce à l’utilisation d’une nouvelle balise "#CFG_ARBO" (assurez-vous d’avoir la dernière version du plugin), nous allons en profiter pour la placer à la fin du formulaire.

Cette balise nous sera utile pendant le temps de développement et de mise au point du fichier de configuration, il n’est pas nécessaire de la laisser dans la version finale du formulaire.

Pour ne pas alourdir inutilement cet article déjà bien long, et qui n’est pas encore fini (loin s’en faut), le code de cette étape ne sera pas publié ici, puisqu’il n’apporte pas de changement essentiel par rapport à l’étpe précédente.

Je vous propose en revanche de trouver cette dernière version du formulaire dans les sources à télécharger en fin d’article.

En attendant, voici à quoi ressemble maintenant notre formulaire :

Utilisation du Formulaire CFG

Voilà, notre formulaire CFG est finalisé, voyons maintenant comment l’utiliser afin de sauvegarder des configurations de "qualification technique" pour chaque auteur du site.

C’est bien à cette étape, lors de l’utilisation du formulaire, que nous allons découvrir tout l’intérêt et la puissance de la méthode "multi" de CFG.

Commençons donc par afficher notre formulaire CFG, suivez le guide :

• Dans l’espace privé du site, affichons la page principale de configuration en cliquant sur le bouton "Configuration" ;
• Dans la page qui s’affiche, nous allons découvrir un onglet portant le nom évocateur de "CFG" (si jamais vous le ne voyez pas, vérifiez la bonne installation et activation du plugin) ;
• En cliquant sur cet onglet "CFG", nous allons afficher l’ensemble des modules gérés par le plugin :
• Nous devrions donc voir un onglet portant le titre de "Qualification Auteurs", comme ceci :
• Enfin, cliquons sur cet onglet pour afficher notre formulaire.

Ceux qui ont déjà une expérience d’utilisation du plugin CFG, remarqueront dans la colonne de gauche, un bloc-menu particulier, juste en dessous du cadre affichant le descriptif de notre formulaire.

Ce bloc-menu affiche le nom de notre fichier de configuration (voir chapitre "CFG multi : Fonctionnement" pour plus de détails), à savoir "qualif", puis, juste après, nous trouvons un bouton nommé "nouveau +", qui permet de créer des nouveaux "casiers" de sauvegarde :

Pour le faire apparaître, nous devons insérer la balise de paramètrage [(#REM) liens*=qualif] en tête du formulaire, tel que nous l’avons vu à l’étape 2 de sa construction, cette balise crée un lien direct vers le fichier de configuration lui-même [7].

En plus du bouton "nouveau +", ce bloc-menu propose d’autres fonctionnalités intéressantes. En effet, comme nous l’avons vu plus haut, la méthode "multi" sert essentiellement à mémoriser des configurations multiples utilisant le même formulaire, mais comment savoir quelles sont les configurations déjà mémorisées ?

C’est justement ce bloc-menu qu’est utilisé par CFG pour apporter une solution très pratique... mais pour pouvoir l’apprécier, nous devons commencer par sauvegarder quelques configurations.

Rien de plus simple, supposons que nous avons 3 auteurs sur notre site : Pierre, Paul et Jacques (quelle imagination ! ;-), voici la marche à suivre :

• Commençons donc par choisir un de ces auteur dans la liste des auteurs du site, admettons qu’on choisi "3-pierre" en premier [8] ;

• Dès que notre choix est fait, il vient s’inscrire dans le champ "Id" de la zone "Configuration" de notre formulaire, c’est-à-dire "3-pierre" dans notre cas. C’est cette valeur qui sera utilisée pour créer le "casier" d’enregistrement de la configuration ;

• Choisissons maintenant les différentes "qualifications techniques" de cet auteur avec les menus déroulants de chaque technologie Web listée ;

• Enfin, cliquons sur le bouton "Enregistrer" pour sauvegarder cette configuration dans la table "spip_meta" correspondante ;

• Dès la sauvegarde faite, CFG va réactualiser l’affichage de la page et nous pourrons alors découvrir, dans le bloc-menu de la colonne de gauche, un lien avec le nom de notre configuration, à savoir "3-pierre", suivi d’une petite