L’objectif ici est de montrer progressivement la mise en place de certaines nouveautés du plugin CFG et de SPIP 2.
Pour cela nous allons détailler la construction d’un petit plugin SPIP qui va utiliser les choses suivantes :
- Le plugin CFG
- Les formulaires CVT de spip couplés avec les formulaires CFG
- Une feuille de style dynamique (feuille de style en squelette)
Ce plugin a été construit en utilisant le plugin aa, proposé par cy_altern.
C’est une excellente base pour commencer un plugin utilisant CFG.
Prétexte : un plugin de personnalisation de la css
Imaginons un plugin permettant un paramètrage simple de la feuille de style du site (couleurs et images de fond).
Il permettrait au « codeur de squelettes » de proposer simplement une personnalisation du site à l’administrateur du site (qui ne maitrise pas forcement HTML/CSS ni l’écriture de squelettes SPIP).
- Il ajouterait un nouveau bouton dans l’interface d’administration du site.
- Il définirait 5 couleurs et 5 images de fond (à uploader), qui seront accessible au codeur de squelettes via une feuille de style squelettisée (voir ici, sinon plus bas).
- Il proposerait 2 formulaires accessibles depuis l’interface publique et l’interface privée du site.
Avant de passer à la réalisation proprement dite, nous allons d’abord passer en revue l’ensemble des éléments utilisés pour chaque fonctionnalité.
Modification de l’espace privé (ajout d’un bouton)
Avant spip 2, l’ajout d’un nouveau bouton dans l’interface privée se faisait par la définition d’un nouveau pipeline.
Les pipelines sont des fonctions qui permettent de se brancher sur des endroit précis du fonctionnement de SPIP et d’y ajouter nos propres éléments ou traitements.
Désormais, avec spip 2, l’ajout d’un bouton à l’interface privée peut se faire directement via le fichier plugin.xml
.
Voir aussi :
- Ajouter des boutons, sur programmer.spip.org : http://programmer.spip.org/Definir-...
- Les pipelines sur doc.spip.org : http://doc.spip.org/@Les-points-d-entree-pipelines (doc.spip.org)
Stockage des données
Nous avons donc besoin de stocker dans spip 10 informations : 5 couleurs (sous la forme de code couleur du type #fafafa
) et 5 chemins de fichiers.
- Les données que nous souhaitons stocker ne feront pas l’objet de boucles (leur nombre restera relativement limité et elles ne serviront pas de critères de sélection).
- Elles sont associées au squelette et non à un objet éditorial de spip.
Pour ces raisons, stocker ces informations dans une table spécifique de la base de données avec un champ par paramètre ne serait pas pertinent.
Ces informations seront donc stockées dans « une case » (un champ) de la table « meta » de la base de donnée de spip. Ce champ aura pour titre le nom de notre plugin.
Les données seront stockées sous la forme d’un tableau sérialisé. C’est à dire une longue chaine de caractères composée de couples nom:valeur
entrecoupés de séparateurs.
C’est une façon de stocker plusieurs informations « à usage simple » dans la base de données, tout en restant économe (sans multiplier les tables dans la base de donnée, ni surcharger inutilement la table « meta » existante).
La bonne nouvelle est que le plugin CFG va nous permettre de complètement automatiser cette partie (sérialisation et stockage).
Voir aussi :
- Les paramètres des formulaires CFG (dépots) sur spip-contrib : http://www.spip-contrib.net/API-CFG-Parametres-des-formulaires
- Les dépots et la balise #CONFIG sur spip-contrib : http://www.spip-contrib.net/API-CFG-CONFIG-lire_config
Édition des données : Formulaires CVT
Les deux formulaires (couleurs et images de fond) bénéficieront des avantages introduits par spip2 avec CVT.
Désormais, dans spip2, l’écriture de formulaires est simplifiée avec le formalisme CVT (Charger Vérifier, Traiter).
« L’ajaxisation » des formulaires est automatique :
Intégrer un formulaire CVT en ajax au sein d’un squelette est aussi simple qu’écrire :
<div class="ajax">
#FORMULAIRE_NOMFORMULAIRE
</div>
Concrètement, un formulaire CVT est composé de deux fichiers situés dans le répertoire /formulaires/ du plugin :
- un fichier
nom_formulaire.html
, contenant le squelette du formulaire. - un fichier
nom_formulaire.php
, contenant 3 fonctions php : charger(), verifier() et traiter().
La fonction charger() fournit la liste des champs saisis dans le formulaire, avec des valeurs par défaut éventuelles.
La fonction verifier(), comme son nom l’indique, vérifie les données entrées par l’utilisateur.
La fonction traiter() se charge des actions à effectuer (stockage des données saisies, envoi de mail, etc...) si la fonction verifier() n’a renvoyé aucune erreur.
Voir aussi :
- Les formulaire CVT dans spip2.0, sur spip.net : http://www.spip.net/fr_article3800.html
- Les formulaires CVT par l’exemple : http://www.spip.net/fr_article3796.html
Se passer du php avec CFG :
CFG est un plugin développé par toggg et marcimat.
Au début, simple moteur de configuration pour les autres plugins,
on peut le considérer comme le « moteur de configuration » du « framework » qu’est devenu spip.
On peut traduire « configuration » par « paramètres spécifiques présents une fois dans un SPIP ».
Cela peut concerner un spip, un plugin ou un jeu de squelettes ; ce qui correspond bien à notre cas.
Il permet de prendre en charge de manière standardisée la construction de formulaires, leur traitement et le stockage des données collectées.
CFG part du principe qu’un formulaire « bien écrit » contient suffisamment d’informations pour générer automatiquement l’équivalent des fonction charger / vérifier / traiter (cf plus haut).
- Le principe des formulaires CVT va nous permettre de générer simplement des formulaires ajax, appelables dans l’interface publique du site, si besoin.
- Le plugin CFG va nous permettre d’automatiser la vérification de la saisie des données et leur stockage dans la base de données.
- Le tout, sans écrire une ligne de PHP !
Voir aussi :
- Les formulaire CFG/CVT, sur spip-contrib : http://www.spip-contrib.net/Evolutions-de-CFG-1-10
- Utilisation des formulaires CVT dans CFG, sur spip-contrib : http://www.spip-contrib.net/API-CFG-FORMULAIRE_XX
Étape 1 - écriture du fichier plugin.xml
La première étape de construction d’un plugin SPIP est la création d’un répertoire du nom de notre plugin, dans le répertoire plugins
sur votre SPIP de travail.
Ici, nous créons donc un répertoire style_config
dans le répertoire plugins
Ensuite, nous devons créer un fichier plugin.xml
au sein de ce nouveau répertoire. Ce fichier décrit notre plugin, sa version, déclare les fonctions et pipelines personnalisés utilisés et éventuellement les autres plugins qu’il utilise .
<plugin>
<nom> <!-- Nom du plugin -->
<multi>
[fr]style_config : couleurs et images des squelettes modifiables
[en]style_config : custom colors and images for templates
</multi>
</nom>
<auteur> <!-- Auteur du plugin -->
<multi>
[fr] ashaszin - 2008 - Distribué sous licence GNU/GPL
[en]ashaszin - 2008 - Distributed under GNU/GPL licence
</multi>
</auteur>
<version>
0.1
</version>
<etat>
dev
</etat>
<install>style_config_install.php</install>
<description>
<multi>
[fr]Des couleurs et images personnalisables utilisables dans une css "squelettisée"
[en]Custom colors and backgrounds for public interface (in templated css)
</multi>
</description>
<lien>
[Configuration->.?exec=cfg&cfg=style_config]
</lien>
<prefix>style_config</prefix>
<bouton id="style_config" parent="naviguer">
<icone>images/plugin-24.gif</icone>
<titre>Modifier les styles perso</titre>
<url>.?exec=cfg&cfg=style_config_couleurs</url>
<args>arguments transmis</args>
</bouton>
<necessite id="cfg" version="[1.10;]" />
<utilise id="palette" version="[1.0.1;]" />
</plugin>
La ligne suivante :<utilise id="palette" version="[1.0.1;]" />
indique que notre plugin bénéficiera de la présence éventuelle du plugin palette. Si celui ci est présent, lors de l’édition des couleurs, un sélecteur de couleur apparaîtra.
Voir aussi :
- Le fichier plugin.xml et ses balises, sur doc.spip.org : http://doc.spip.org/@Plugin-xml
- Ajouter des boutons, sur programmer.spip.org : http://programmer.spip.org/Definir-...
Etape 2 - Construction des formulaires
Pour construire nos formulaires, on peut prendre comme base, le formulaire minimal pour CFG, tel qu’expliqué par marcimat dans son article CFG-FORMULAIRE_XX.
Ces squelettes de formulaires sont à placer dans le répertoire (à créer) /formulaires
de notre plugin.
Formulaire des couleurs
Un fichier /formulaires/config_couleurs.html
:
<!-- titre=Configuration des couleurs -->
<!-- autoriser=configurer -->
<!-- depot=metapack -->
<!-- nom=style_config-->
<!-- casier=couleurs-->
#CACHE{0}
[(#ENV{editable}|oui)
<div class="formulaire_spip formulaire_cfg formulaire_config_couleurs">
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[<p class="formulaire_message">(#ENV*{message_ok})</p>]
<form method="post" action="#SELF">
<div> #ACTION_FORMULAIRE{#SELF}
<fieldset>
<ul>
<li>
<label for="couleur1">couleur1 :</label>
<input type="text" name="couleur1" class="palette" value="[(#ENV{couleur1}|?{[(#ENV{couleur1})],#dfdfdf})]" />
</li>
<li>
<label for="couleur2">couleur2 :</label>
<input type="text" name="couleur2" class="palette" value="[(#ENV{couleur2}|?{[(#ENV{couleur2})],#dfdfdf})]" />
</li>
<li>
<label for="couleur3">couleur3 :</label>
<input type="text" name="couleur3" class="palette" value="[(#ENV{couleur3}|?{[(#ENV{couleur3})],#dfdfdf})]" />
</li>
<li>
<label for="couleur4">couleur4 :</label>
<input type="text" name="couleur4" class="palette" value="[(#ENV{couleur4}|?{[(#ENV{couleur4})],#dfdfdf})]" />
</li>
<li>
<label for="couleur5">couleur5 :</label>
<input type="text" name="couleur5" class="palette" value="[(#ENV{couleur5}|?{[(#ENV{couleur5})],#dfdfdf})]" />
</li>
</ul>
</fieldset>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{description})</span>]
<input type="submit" name="_cfg_ok" value="<:cfg:OK:>" />
</div>
</form>
</div>
]
[(#ENV{editable}|non)
Vous devez être connecté en administrateur pour pouvoir utiliser ce formulaire.
]
Formulaire des images
Un fichier /formulaires/config_images.html
:
<!-- titre=configuration des images -->
<!-- autoriser=configurer -->
<!-- depot=metapack -->
<!-- nom=style_config-->
<!-- casier=images-->
#CACHE{0}
[(#ENV{editable}|oui)
<div class="formulaire_spip formulaire_cfg formulaire_config_couleurs">
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[<p class="formulaire_message">(#ENV*{message_ok})</p>]
<form method="post" enctype="multipart/form-data" action="#SELF">
<div> #ACTION_FORMULAIRE{#SELF}
<fieldset>
<ul>
<li>
<label for="image1">image1 :</label>
<input type="file" name="image1" value="" size="30" />
[(#CFG_CHEMIN{style_config/images/image1}|image_reduire{350})]
</li>
<li>
<label for="image2">image2 :</label>
<input type="file" name="image2" value="" size="30" />
[(#CFG_CHEMIN{style_config/images/image2}|image_reduire{350})]
</li>
<li>
<label for="image3">image3 :</label>
<input type="file" name="image3" value="" size="30" />
[(#CFG_CHEMIN{style_config/images/image3}|image_reduire{350})]
</li>
<li>
<label for="image4">image4 :</label>
<input type="file" name="image4" value="" size="30" />
[(#CFG_CHEMIN{style_config/images/image4}|image_reduire{350})]
</li>
<li>
<label for="image5">image5 :</label>
<input type="file" name="image5" value="" size="30" />
[(#CFG_CHEMIN{style_config/images/image5}|image_reduire{350})]
</li>
</ul>
</fieldset>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{description})</span>]
<input type="submit" name="_cfg_ok" value="<:cfg:OK:>" />
<input type="reset" value="<:cfg:Reset:>" />
</div>
</form>
</div>
]
[(#ENV{editable}|non)
Vous devez être connecté en administrateur pour pouvoir utiliser ce formulaire.]
Affichage des formulaires dans l’interface publique
A cette étape, nos formulaires sont d’ors et déjà utilisables dans nos squelettes, au sein de l’interface publique.
On peut les appeler en écrivant tout simplement cela :
[<div class="ajax">(#AUTORISER{configurer})
#FORMULAIRE_CONFIG_COULEURS
</div>]
[<div class="ajax">(#AUTORISER{configurer})
#FORMULAIRE_CONFIG_IMAGES
</div>]
On utilise ici la balise #AUTORISER
pour vérifier que la personne sur la page est bien autorisée à modifier les données.
Notez bien, que j’ai ici « ajaxisé » ces formulaires, pour démontrer la simplicité de le chose sous SPIP2. Néanmoins, dans notre cas un rechargement de la page est nécessaire pour un affichage correct après le choix d’une couleur ou l’upload d’une image.
Voir aussi :
- La balise
#AUTORISER
sur programmer.spip.org :
http://programmer.spip.org/La-balis...
Restons propres : nettoyer les données en cas de suppression du plugin
Autre chose à prendre en compte : si l’on désinstalle le plugin, les valeurs que nous avons stocké dans le champ « style_config » de la table meta persistent.
Si l’on veut faire les choses proprement, il faut les effacer lors de la désinstallation du plugin.
Pour cela, on créé dans le dossier de notre plugin un fichier style_config_install.php, qui va s’occuper de « nettoyer » les données du plugin lors de l’installation ou de la désinstallation.
style_config_install.php
<?php
function style_config_install($action){
effacer_meta('style_config');
}
?>
Par contre, à ce stade, les formulaires ne sont pas encore utilisables dans l’espace privé. Il faut encore les « cabler » sur la page de CFG, dans l’espace privé.
Etape 3 - Affichage des formulaires dans l’interface du plugin CFG - lien avec notre bouton personnalisé
Pour cela on crée un répertoire /fonds
dans le répertoire de notre plugin, et y ajoute deux petits fichiers : cfg_style_config_couleurs.html
et cfg_style_config_images.html
.
Ces fichiers appelleront simplement les deux formulaires vu plus haut.
Il est important que le nom de ces « fonds CFG » commencent par « cfg_ » et que leur nom soit différent de celui des deux formulaires que nous avons écrit plus haut.
cfg_style_config_couleurs.html
<!-- interpreter=non -->
<!-- descriptif=Choisissez ici les couleurs et les images de l'interface publique-->
<!-- titre= style_config -->
<!-- boite= Couleurs personnalisées -->
<!-- liens*=style_config:style_config_couleurs -->
<!-- liens*=style_config:style_config_images -->
#CACHE{0}
#FORMULAIRE_CONFIG_COULEURS
#CFG_ARBO{style_config}
cfg_style_config_images.html
<!-- interpreter=non -->
<!-- descriptif=Choisissez ici les images -->
<!-- titre= style_config : Choix des images -->
<!-- boite= Images personnalisées -->
<!-- onglet=style_config -->
<!-- liens*=style_config:style_config_couleurs -->
<!-- liens*=style_config:style_config_images -->
#CACHE{0}
#FORMULAIRE_CONFIG_IMAGES
#CFG_ARBO{style_config}
C’est fini ? non pas tout à fait...
Notre plugin, à proprement parler, est désormais terminé.
Maintenant, nous avons accès aux couleurs et images choisies au sein des squelettes SPIP, via la balise #CONFIG.
Désormais, il faut mettre en place une feuille de style dynamique (sous forme de squelette), qui utilisera ces nouvelles informations que nous avons défini.
Etape 5 - Mise en place d’une CSS dynamique (CSS sous la forme d’un squelette)
Nous nous plaçons ici au niveau de notre squelette : dans le répertoire /squelettes
de notre installation de SPIP.
Notre feuille de style va donc comporter maintenant des balises SPIP (enfin, des balises CFG, plus précisement). Pour que SPIP soit capable de les comprendre, il faut que cette feuille de style soit sous forme d’un squelette.
Et comme tous les squelettes SPIP, elle aura l’extension .html
Imaginons que ce squelette s’appelle stylecss.html
(à vous de trouver un nom plus original ou parlant ...)
Le fichier CSS en lui même :
#CACHE{0}
#HTTP_HEADER{Content-Type: text/css; charset=iso-8859-15}
#HTTP_HEADER{Vary: Accept-Encoding}
/******plugin style_config*********************/
#SET{couleur1, #CONFIG{style_config/couleurs/couleur1}|ltrim{"#"} }
#SET{couleur2, #CONFIG{style_config/couleurs/couleur2}|ltrim{"#"} }
#SET{couleur3, #CONFIG{style_config/couleurs/couleur3}|ltrim{"#"} }
#SET{couleur4, #CONFIG{style_config/couleurs/couleur4}|ltrim{"#"} }
#SET{couleur5, #CONFIG{style_config/couleurs/couleur5}|ltrim{"#"} }
/*Couleur1 : #GET{couleur1}*/
/*Couleur2 : #GET{couleur2}*/
/*Couleur3 : #GET{couleur3}*/
/*Couleur4 : #GET{couleur4}*/
/*Couleur5 : #GET{couleur5}*/
#SET{image1, #CFG_CHEMIN{style_config/images/image1} }
#SET{image2, #CFG_CHEMIN{style_config/images/image2} }
#SET{image3, #CFG_CHEMIN{style_config/images/image3} }
#SET{image4, #CFG_CHEMIN{style_config/images/image4} }
#SET{image5, #CFG_CHEMIN{style_config/images/image5} }
/*image fond1 : #GET{image1}*/
/*image fond2 : #GET{image2}*/
/*image fond3 : #GET{image3}*/
/*image fond4 : #GET{image4}*/
/*image fond5 : #GET{image5}*/
/*Exemple de règles CSS pour les couleurs*/
/*.ma_classe_css {
color:##GET{couleur1} ;}*/
/*.mon_autre_classe_css {
color:#[(#GET{couleur1}|couleur_eclaircir)] ; font-family: "sans-serif"; font-variant:small-caps;}*/
/*Exemple de règle CSS pour les images*/
/*#mon_id_css{
background:url(#GET{image1}) top left;
}*/
/*Le reste de votre feuille CSS**************************/
Petites explications :
#SET{couleur1, #CONFIG{style_config/couleurs/couleur1}|ltrim{"#"} }
Cette ligne permet de :
- recupérer la valeur stockée dans
#CONFIG{style_config/couleurs/couleur1}
- supprimer le « # » devant la valeur de la couleur (via « |ltrim »#"). En effet, les nouveaux filtres de couleur de SPIP travaillent sur des valeurs sans « # »)
- enfin, stocker la valeur résultante dans la variable « couleur1 », récupérable par
#GET{couleur1}
(pour améliorer la lisibilité de notre feuille de style).
Appel de la CSS :
Enfin, nous ferons appel à notre feuille de style squelettisée de la façon suivante :
(dans le fichier inc_head.html, si vous avez basé vos squelettes sur ceux par défaut (squelettes-dist))
[<link rel="stylesheet" href="(#URL_PAGE{stylecss}|direction_css)" type="text/css" media="projection, screen, tv" />]
Voir aussi :
Le petit topo d’Alexandra sur les feuilles de style en squelettes
Discussions par date d’activité
6 discussions
J’ai réalisé le plugin selon vos indications ; il semble fonctionner convenablement
SAUF
si je mets das la feuille de style stylecss.html :
#SET{color, blue}
et dans mon squelette :
#GET{color}
je n’obtient aucun résultat.En quoi ma procédure est-elle défaillante ?
Merci de votre réponse
Je me réponds à moi-même.
Dans la feuille se style on peut créer un cadre qui utilise :
#GET{color}
ou encore##GET{couleurN}
[N = 1 à 5]Il faut ajouter en plus à couleurN le # qui a été ôté à la création de couleurN
Le cadre est à utiliser dans la rédaction d’un article de l’espace privé.
Répondre à ce message
Salut, j’essaye de faire mon 1er plugin très simple (sélection d’un article).
J’ai un souci au niveau de l’icone associée au plugin dans CFG. J’ai fait un 1er test avec une image un peu grande (60px) dans le xml, du coup ensuite j’ai changé d’image (24px) dans la config, mais ca m’affiche toujours la grosse image. J’ai beau désactiver / réactiver le plugin ca ne change rien.
J’ai ajouté la petite fonction _install, mais toujours aucun changement...
Une idée ?
Edit :
En fait bon la honte, j’ai juste oublié de changer l’icone dans cfg-xxx.html ...
Répondre à ce message
Bonjour,
tutoriel super utile, bien fait... j’ai pris cette base pour écrire un premier plugin moins compliqué, sans récupération de données dans une feuille de style... mais j’ai une question bête quand même (des fois c’est utile, des questions bêtes...), concernant le fichier style_config_install.php :
- pourquoi une fonction qui vide le champ de la table meta à l’installation du plugin ?
enfin mon script ne fonctionne pas (l’installation déclare un « échec »), il me semble qu’il manque une fonction d’installation avant de désinstaller, mais j’ai peut-être pas tout compri...
merci de votre aide,
je me reprends : pour l’écriture dans la base de données CFG s’occupe de tout, très bien... mais à l’installation pourquoi vider le champ de la table meta ?
(quand je retire la déclaration du fichier plugin.xml, tout fonctionne bien... sauf que c’est pas propre à la désinstallation, ça non...)
Salut chankalan,
Ça devait être pour effacer toute configuration précédente du plugin (dans les versions qui ne géraient pas l’installation/désinstallation). Histoire d’avoir des variables propres pour les tests.
En gros, l’installation comme la désinstallation du plugin vident le champ « style_config » de la table « meta » de la BDD. Mais ce n’est qu’un exemple, tu fais ce que tu veux.
Tu trouveras plus d’infos (et des exemples) dans l’article sur plugin.xml sur doc.spip.org (la partie sur la balise <install>)
Répondre à ce message
Bonjour ashaszin,
serait-il possible d’avoir un exemple d’utilisation ou les données sont enregistrée dans une nouvelle table et non pas dans spip_meta,
je n’ai d’ailleurs pas trouver d’exemples d’utilisation de depot de type « table »
Il y a bien quelques explications pour tablepack :
et même s’il est mentionné que cfg_id doit impérativement être utilisé, cela ne dit pas de quelle façon...
aurais tu une idée à ce sujet ?
Merci par avance
Salut klelugi,
Je crois que je n’ai jamais réussi à faire marcher le depot « table »... mais je n’ai pas du essayer assez fort.
Rapproche toi de marcimat, il saura surement te donner plus d’infos (la réponse m’intéresse aussi... ^^ ).
Je crois qu’il m’avait dit que ça avait marché, mais qu’il fallait retester.
Pour ceux qui lisent, les articles dont parle klelugi :
Répondre à ce message
Voila un article absolument fantastique, encore merci !
Répondre à ce message
Merci pour cet article très utile.
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 :
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.
Suivre les commentaires : |