Configurare un semplice plugin con cfg

Tutorial : fare un plugin semplice configurato con cfg : aa

Il plugin config (cfg) permette di gestire i parametri di configurazione d’un plugin in modo semplice. Quest’articolo propone di sviluppare un plugin (aa) extra-semplice per imparare ad utilizzare config.

Alcuni richiami su cfg

cfg è uno strumento per gestire i parametri di configurazione d’un plugin (o di altro) con il minimo sforzo :

  • La descrizione dei parametri è realizzata creando un unico file fonds/xxx.html che genera il form di gestione dei parametri, la loro descrizione/tipologia e la configurazione del salvataggio nel DB.
  • Permette di inserire i parametri di configurazione nella tabella spip_meta ma senza sporcarlo con decine di record (uno per parametro) come accade attualmente per molti plugin. Questo si realizza serializzando in un albero la tabella dei parametri.

Il principio, dunque, è che ogni plugin conserva i suoi parametri sotto forma di un solo record con 2 campi : « nome » e « valore » :

  • nome conserva l’identificativo unico del record, per ogni plugin, e sarebbe meglio che contenesse il relativo prefisso.
  • valore conserva una tabella php (array) che contiene elementi nella forma : « nome_variabile_config » = > « valore_della_variabile ». Questa tabella è registrata sotto la sua forma serializzata da spip, è recuperabile sia nello spazio pubblico che in quello privato. « valore_della_variabile » può essere una tabella costruita allo stesso modo, dando luogo a interi alberi di configurazione.

un plugin di esempio per utilizzare cfg : aa

Per comprendere meglio il funzionamento di cfg dal punbto di vista dello sviluppatore di plugin, il seguito di quest’articolo è costruito come un tutorial per realizzare un plugin che utilizza cfg. Questo plugin extra-semplice permette di definire quale articolo pubblicare nella pagina home (sommarie). In seguito si potrà aggiungere la possibilità di scegliere quali elementi dell’articolo saranno inseriti (titolo, sottotitolo, chapo, testo).
questo plugin, che chiameremo « aa » acronimo di « articolo accoglienza », dovrà dunque permettere :
- di scegliere l’articolo da utilizzare con un’interfaccia semplice che presenta l’elenco di tutti gli articoli del sito.
- di conservare in spip_meta l’id_article scelto e gli elementi da inserire
- di recuperare facilmente il valore dell’id_article nei modelli e/o nello spazio privato

Prima tappa : preparare il plugin

Prima di cominciare la parte specifica per cfg, bisogna preparare quel poco che il plugin richiede :

  • una sottocartella aa/ in plugins/
  • un file plugins/aa/plugin.xml con il codice che serve :
<plugin>
    <nom>
        <multi>
           [fr]Article accueil
           [en]Article summary
           [it]Articolo della home
        </multi>
    </nom>
    <auteur>
        <multi>
           [fr] cy_altern
_ &copy; 2007 - Distribué sous licence GNU/LGPL
           [en]cy_altern - distributed under GNU/GPL licence
        </multi>
    </auteur>
    <version>
          0.1
    </version>
    <etat>
          dev
    </etat>
    <description>
        <multi>
           [fr]Un exemple de plugin pour apprendre ß utiliser cfg
           [en]An example to learn cfg.
           [it]Un esempio per imparare a usare cfg.
        </multi>
    </description>
    <lien>
           [Documentation sur ->http://www.spip-contrib.net/?article1605],
           et si vous avez cfg: [Configuration->.?exec=cfg&cfg=aa]
    </lien>
    <icon>plugin-24.gif</icon>
    <prefix>
          aa
    </prefix>
</plugin>

Download

Notate il modo d’internazionalizzare i testi con [en] [fr], ecc..

Il link per la configurazione sarà accessibile da amministrazione plugin aprendo l’unghia aa. Questo non rinvia a un file del plugin come di solito (della forma ->sousmenu[’aa’] per chiamare ?exec=aa) ma rinvia direttamente all’interfaccia di cfg :
->sousmenu[’cfg&cfg=aa’] rinvia a ?exec=cfg&cfg=aa.

Dunque questo plugin non dovrà creare la sua interfaccia di configurazione perché beneficia di quella creata automaticamente da cfg.

Ed ora, avendo creato quest’elemento, è possibile passare all’interfaccia di configurazione/registrazione dei parametri del plugin.

Seconda tappa : « collegare » il plugin aa a cfg

  • cfg è concepito in modo tale che quando si chiama  ?exec=cfg&cfg=aa, il file exec_cfg (l’interfaccia di cfg) chiama il file fonds/cfg_aa.html ed include automaticamente il suo contenuto in un form già pronto. Questa sottocartella fonds/ può essere situata in squelettes/ o in qualsiasi altra cartella del plugin, in questo caso quindi plugins/aa/fonds/cfg_aa.html
  • la convalida di questo form permetterà di fare la serializzazione dei dati del form e il salvataggio in spip_meta senza che lo sviluppatore del plugin debba scrivere una linea di codice.
  • infine, ciliegia sulla torta, cfg funziona già squelettizzato nello spazio privato

Conseguenza di queste caratteristiche :
il file /fonds/cfg_aa.html sarà trattato come un file di modello (squelette) (e si può usare BOUCLE, SEGNAPOSTI, filtri). Questo file dovrà contenere i campi di form (<input>, <select>, <text>...) necessari a definire i parametri di configurazione da salvare : il « name » d’un elemento corrisponde al nome della variabile da salvare, il « value » permette di definire il valore di questa variabile di configurazione.

Per il nostro plugin aa, inizialmente basta un solo parametro : l’id_article dell’articolo che fungerà da pagina d’accoglienza. Occorre dunque proporre all’utilizzatore un menu a scelta unica (un < select >) tra cui scegliere l’articolo fra tutti quelli esistenti. Cioè :

      <select name="id_aa">
          <BOUCLE_articles(ARTICLES){par titre}>
              <option value="#ID_ARTICLE">#ID_ARTICLE . #TITRE</option>
          </BOUCLE_articles>
      </select>

Download.

Le strutture che ci interessano specialmente sono :
<select name=« id_aa »> che permette di definire che si desidera salvare una variabile « id_aa », attenzione name=xxx deve seguire immediatamente
<select o <input type=« ... »
<option value=« #ID_ARTICLE »> che permette di inviare id_article di
<option> scelta come valore del parametro id_aa.

Affinché la scelta dell’articolo sia più semplice, si costruisce
<select> in modo che gli articoli siano classificati per rubriche gerarchicamente.
Usando il codice di /dist/plan.html per fare la chiamata ricorsiva delle rubriche, si arriva a questo per cfg_aa.html :

- HEAD del file :

      #CACHE{0}
      <form method="post">[(#ENV{_cfg_}|form_hidden)]
    

Download ;

Facoltativamente, cfg permette anche di costruire automaticamente un quadro che contiene una descrizione del plugin e dare un titolo (< title > nella HEAD della pagina) :

      [(#REM) descriptif=
      <h4>Tutoriel utilisation de cfg</h4>
      Ici vous pouvez configurer l'article qui sera affich&eacute; en page sommaire.<br />
      <br /><a href="http://extranet-eze.dyndns.org/portail/spip_SVN/spip.php?article112" class="spip_out">Documentation provisoire (&agrave; verser sur contrib ?)</a>
      ]
      [(#REM) titre=plugin aa titre]
 

Download ;

Basta rispettare la sintassi {{[(#REM) descriptif=... o [(#REM) titre=...}} e mettere il testo/codice HTML dell’elemento.

Il BOUCLE per creare la select :

      <fieldset><legend><:article:> <:sommaire:></legend>
        <label>Choix de l'article &agrave; utiliser :</label>
        <select name="id_aa">
          <option value="">Racine</option>
          <BOUCLE_secteurs(RUBRIQUES) {racine} {par titre}>
            <option value="">&nbsp;&nbsp;<strong>rubrique : #TITRE</strong></option>
            <BOUCLE_articles_racine(ARTICLES) {id_rubrique} {par titre}>
              <option value="#ID_ARTICLE">&nbsp;&nbsp;&nbsp;&nbsp;#ID_ARTICLE . #TITRE</option>
            </BOUCLE_articles_racine>
            <BOUCLE_rubriques(RUBRIQUES) {id_parent} {par titre}>
              <option value="" style="font-weight: bold;">&nbsp;&nbsp;rubrique #ID_RUBRIQUE : #TITRE</option>
               <BOUCLE_articles(ARTICLES) {id_rubrique} {par titre}>
                 <option value="#ID_ARTICLE">&nbsp;&nbsp;&nbsp;&nbsp;#ID_ARTICLE . #TITRE</option>
               </BOUCLE_articles>
         <BOUCLE_sous_rubriques(BOUCLE_rubriques)></BOUCLE_sous_rubriques>
            </BOUCLE_rubriques>
          </BOUCLE_secteurs>
        </select>
      </fieldset>

Download ;

- fine del file : fine del form di cfg :

      <input type="submit" name="_cfg_ok" value="<:OK:>" />
      <input type="reset" value="<:Reset:>" />
      <input type="submit" name="_cfg_delete" value="<:Supprimer:>" />
      </form>

Download ;

Ed hop ! con questo semplice file, il plugin è operativo :  ?exec=cfg&cfg=aa dà accesso all’interfaccia di configurazione seguente :

Terza tappa : recuperare i dati di configurazione

Ora si tratta dunque di recuperare in un file di modello il valore di « id_aa » per passarla ad una ciclo ARTICLES che pubblicherà il contenuto dell’articolo scelto. In modo semplice cfg crea automaticamente un segnaposto #CONFIG che permette di recuperare i dati di configurazione del plugin aa. Si può dunque creare il ciclo seguente nel file di modello « sommaire.html » ad esempio :

      [(#REM) test plugin aa]
      <div class="liste-articles">           
        <BOUCLE_truc(ARTICLES){id_article=(#CONFIG{aa/id_aa})}>
            <div class="cartouche">
                #DEBUT_SURLIGNE  
              [(#LOGO_ARTICLE||image_reduire{200,200})],''})]  
              [<h1 class="#EDIT{titre} titre">(#TITRE)</h1>]  
              [<p class="#EDIT{soustitre} soustitre">(#SOUSTITRE)</p>]  
              [<p class="#EDIT{chapo} chapo">(#CHAPO)</p>]] 
              #FIN_SURLIGNE 
          </div> 
         [<div class="#EDIT{texte} texte">(#TEXTE|image_reduire{520,0})</div>]        
       </BOUCLE_truc> 
      </div>

Download ;

Alternativamente è possibile mettere BOUCLE_truc in un file di modello e chiamarlo con un’inclusione nella quale si passa l’id_article salvato da id_aa :

	[(#INCLURE{fond=aa}{id_article=[(#CONFIG{aa/id_aa})]})]

Download ;

Oltre al fatto che tutto funziona come previsto (il contenuto dell’articolo scelto è inserito nella pagina sommaire), nei 2 casi la sola parte interessata è #CONFIG{aa/id_aa} che permette di recuperare direttamente il valore di id_aa per passarla come parametro id_article : {id_article=...}.

Notate dunque la sintassi propria del segnaposto #CONFIG : #CONFIG{prefix_plugin/nom_variable_config} (con « / » come separatore) sarà sostituito dal valore trovato attraverso name=« nom_variable_config » della pagina  ?exec=cfg&cfg=prefix_plugin.
Si può anche chiamare #CONFIG{nom_plugin} se si desidera recuperare direttamente la tabella (array) dei parametri di configurazione salvati.

Quarta tappa : migliorare l’ergonomia dell’interfaccia di configurazione

Dato che il file /fonds/cfg_aa.html è un file di modello « come gli altri », si può utilizzare il segnaposto #CONFIG perché il <select name="id_aa"> possa avere come opzione scelta l’articolo di cui l’id_article è salvato in spip_meta (la configurazione in corso !)."
Il che ci dà :

 <option value="#ID_ARTICLE" [(#CONFIG{aa/id_aa}|=={#ID_ARTICLE}|?{selected="selected",''})]>&nbsp;&nbsp;&nbsp;&nbsp;#ID_ARTICLE . #TITRE</option>

Download ;

Questo codice utilizza dunque un filtro di test d’uguaglianza (|==) sul valore di ID_ARTICLE corrente nel ciclo : se questo id_article è uguale a #CONFIG{aa/id_aa}, allora questa opzione è quella selezionata al caricamento della pagina : <option value="#ID_ARTICLE" selected="selected"> ;

Quinta tappa : recuperare le variabili di configurazione nei file dello spazio privato

Nella maggioranza dei plugins (contrariamente a aa) è necessario recuperare i parametri di configurazione nei file php del plugin stesso (exec_truc.php ad esempio).
Per ciò cfg fornisce la funzione lire_config() che si utilzza nel modo seguente :

ECHO lire_config('aa/chapo');

Download ;

per recuperare il valore della variabile « chapo » del plugin « aa ». La tabella php (array) completa dei valori salvati è chiamata da lire_config(’aa’).

Si possono dunque utilizzare tutte le forme classiche d’interrogazione dell’array php ritornato da lire_config(’aa’) : Un semplice print_r() :

      echo '<strong>lire_config(aa) retourne :</strong> ';
      print_r(lire_config('aa'));

Download ;

o una struttura di controllo più sofisticata :

      foreach(lire_config('aa') as $cle => $val) {
      echo '<br />$cle = '.$cle.' $val = '.$val;

Download ;

che permette di constatare che i valori dell’array lire_config(’aa’) sono indicizzate con il nome delle variabili salvate come chiavi.

A titolo d’esempio si può dunque fare nel plugin aa un’interfaccia d’amministrazione che permetterà d’illustrare queste nozioni.
Per far ciò creare una sottocartella « exec » nella cartella di aa e lì il file aa_admin.php che sarà dunque chiamato da .../ecrire/ ?exec=aa_admin. Un codice minimo per provare lire_config() sarebbe :

  
      <?php
	function exec_aa_admin() {  
         include_spip("inc/presentation");  
      // vérifier les droits  
         global $connect_statut;  
         global $connect_toutes_rubriques;  
         if ($connect_statut != '0minirezo' OR !$connect_toutes_rubriques) {     
             debut_page(_T('titre'), "saveauto_admin", "plugin");  
             echo _T('avis_non_acces_page'); 
             fin_page(); 
             exit; 
         }
         echo debut_page(_T('aa:titre_page'));        
         echo "<br />";
         echo gros_titre(_T('aa:gros_titre_page'));
         echo debut_gauche();
         echo debut_boite_info();
         echo 'contenu de la boite info du plugin aa';
         echo fin_boite_info();
         echo debut_raccourcis();
         echo 'contenu de la boite des raccourcis du plugin aa';
         echo fin_raccourcis();
         echo debut_droite();
         echo debut_cadre_trait_couleur("plugin-24.gif", false, "", _T('titre_boite_principale'));       
         echo debut_cadre_couleur();
      // simple test de lire_config()
         echo '<strong>lire_config(aa) retourne :</strong> ';
         print_r(lire_config('aa'));
         echo '<br /><br /><strong>lire_config(aa/id_aa) =</strong> '.lire_config('aa/id_aa');
         echo '<br /><br /><strong>lire_config(aa/chapo) =</strong> '.lire_config('aa/chapo');
         echo '<br /><br /><strong>une boucle dans lire_config(aa)</strong> ';
         foreach(lire_config('aa') as $cle => $val) {
           echo '<br />$cle = '.$cle.' $val = '.$val;
         }
         echo fin_page();
      }                            
      ?>

Download

Che darebbe l’interfaccia seguente :

Sesta tappa : aggiungere la selezione degli elementi dell’articolo di accoglienza da pubblicare

Per rendere questo plugin un po’ più completo si può desiderare di poter scegliere gli elementi (logo, titolo, sottotitolo, chapo e testo) che saranno pubblicati. Per far ciò 2 modifiche :

  • aggiungere parametri di configurazione in cfg_aa.html :
        <fieldset><legend>Eléments à utiliser :</legend>
        	<label>Logo</label>
        	<input type="checkbox" name="logo" [checked="(#ENV{logo})"] />
     	<label>Titre</label>
        	<input type="checkbox" name="titre" [checked="(#ENV{titre})"] />
        	<label>Sous-titre</label>
           	<input type="checkbox" name="soustitre" [checked="(#ENV{soustitre})"] />      
           	<label>Chapeau</label>
            <input type="checkbox" name="chapo" [checked="(#ENV{chapo})"] />
            <label>Texte</label>
            <input type="checkbox" name="texte" [checked="(#ENV{texte})"] />
          </fieldset>

Download

Si crea dunque per ogni elemento che può essere scelto <input type="checkbox" name="element_a_selectionner" ...> e si recupera la configurazione corrente utilizzando una nuova caratteristica di cfg : quando si è nel modello del fond del plugin (ad esempio cfg_aa.html), allora si recuperano direttamente i valori di #CONFIG{prefix_plugin/nom_variable} in #ENV{nom_variable}. Ciò permette di semplificare rispetto al test |== utilizzato nella tappa precedente per recuperare la config corrente dei vari parametri :
... [checked="(#ENV{chapo})"] basta a fare pubblicare checked=« on » se il chapo è stato scelto nella config corrente.

Con #ENV si possono anche dare valori « di default » alle variabili di configurazione :
#ENV{nom_variable valeur_defaut}
ad esempio per creare un campo testo che gestisce la variabile « trucco » ed avente « toto » come testo di default, si scriverà :

<input type="text" name="truc" value="#ENV{truc, toto}">
  • aggiungere un test sulla configurazione della visualizzazione degli elementi (logo, titolo...) nel modello :
          [(#LOGO_ARTICLE||image_reduire{200,200})]

    Download

diviene :

[(#CONFIG{aa/logo}|=={on}|?{[(#LOGO_ARTICLE||image_reduire{200,200})],''})]

Download

che permette di pubblicare il logo soltanto se è stato selezionato nel plugin. Applicando questo tipo di test su tutto il ciclo BOUCLE_truc si ottiene allora :

<BOUCLE_truc(ARTICLES){id_article=(#CONFIG{aa/id_aa})}>
         <div class="cartouche">
          #DEBUT_SURLIGNE
[(#CONFIG{aa/logo}|=={on}|?{[(#LOGO_ARTICLE||image_reduire{200,200})],''})]
       [(#CONFIG{aa/titre}|=={on}|?{[<h1 class="#EDIT{titre} titre">(#TITRE)</h1>],''})]
      [(#CONFIG{aa/soustitre}|=={on}|?{[<p class="#EDIT{soustitre} soustitre">(#SOUSTITRE)</p>],''})]
      [(#CONFIG{aa/chapo}|=={on}|?{[<p class="#EDIT{chapo} chapo">(#CHAPO)</p>],''})]
          #FIN_SURLIGNE
          </div>
          [(#CONFIG{aa/texte}|=={on}|?{[<div class="#EDIT{texte} texte">(#TEXTE|image_reduire{520,0})</div>],''})]               
      </BOUCLE_truc>

Download

In questo modo il contenuto della pagina sommarie diventa facilmente modificabile tanto al livello del contenuto (articolo scelto) che degli elementi da pubblicare...

Settima tappa : aggiungere un bottone nello spazio privato per l’amministrazione

Questo bottone permetterà di accedere direttamente alla pagina di configurazione di aa. Inizialmente, aggiungere alla fine di plugin.xml,

<pipeline>
    	<nom>ajouter_boutons</nom>
        <inclure>aa_pipelines.php</inclure>
    </pipeline>

Questo pipeline chiede a spip di eseguire la funzione aa_ajouter_boutons() (default) del file aa_pipelines.php situato in plugins/aa/ nella gestione dello spazio privato. Si inserirà così un bottone per accedere all’interfaccia di config del plugin aa nella parte privata. Il file aa_pipelines.php che contiene il minimo per creare un bottone « articolo accoglienza » nel sotto-menù di « edizione » :

      <?php
      function aa_ajouter_boutons($boutons_admin) {
          // si on est admin
          if ($GLOBALS['connect_statut'] == "0minirezo") {
             // on voit le bouton comme  sous-menu de "naviguer"
             $boutons_admin['naviguer']->sousmenu['cfg&cfg=aa']= new Bouton("plugin-24.gif", _T('Article accueil') );
          }
          return $boutons_admin;
      }
      ?>

Download

Nota che questo bottone ($boutons_admin[’naviguer’]) non chiama un file del plugin come negli altri plugins (della forma -> sousmenu[’aa’] per chiamare  ?exec=aa) ma rinvia direttamente sull’interfaccia di cfg :
-  > sousmenu[’cfg&cfg=aa’] rinvia su  ?exec=cfg&cfg=aa.

Ciò mostra nuovamente che il plugin non dovrà creare la sua interfaccia di configurazione poiché beneficia di quella creata automaticamente da cfg

Link recuperare la totalità di aa e cfg :
-  aa en zip
-  cfg en zip
-  aa sulla zona : svn ://zone.spip.org/spip-zone/_plugins_/_dev_/aa
-  cfg sulla zona : svn ://zone.spip.org/spip-zone/_plugins_/_test_/cfg

cfg è in corso di documentazione ed è sempre in sviluppo, tuttavia, le funzionalità presentate qui sono completamente stabilizzate e possono essere utilizzate senza rischio

cfg permette molto più, abbiamo preferito qui fare un esempio semplice.

Vedi anche http://www.spip-contrib.net/Avec-CFG

Discussion

Une discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

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.

Qui êtes-vous ?
[Se connecter]

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