style_config : (encore) un plugin tutoriel pour 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&#233; 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&amp;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&amp;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&eacute;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&eacute;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