style_config : (encore) un plugin tutoriel pour CFG

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 :

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 :

É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 :

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 :

É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 :

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 :

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

Portfolio

Merci à toggg, marcimat, b_b et alexandra, ainsi qu’à tous les contributeurs SPIP.

Viva spip 2.

Discussion

6 discussions

  • 1
    Pouliquen Jean

    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

    • Pouliquen Jean

      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

  • 2

    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 ?

    <?php
         
         function style_config_install($action){
         effacer_meta('style_config');
       
         }
    ?>

    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,

      mais à l’installation pourquoi vider le champ de la table meta ?

      Ç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

  • 1

    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

Qui êtes-vous ?

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom

Dernière modification de cette page le 8 février 2009