SPIP-Contrib

SPIP-Contrib

عربي | Deutsch | English | Español | français | italiano | Nederlands

286 Plugins, 197 contribs sur SPIP-Zone, 222 visiteurs en ce moment

Home > Strumenti per i Plugin > Config (CFG) > Configurare un semplice plugin con cfg

Configurare un semplice plugin con cfg

Tutorial: fare un plugin semplice configurato con cfg: aa

24 novembre 2007 – di mmmx – commentaire

Tutte le versioni di questo articolo: [français] [italiano]

1 vote

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:

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

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:

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

Download;

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

Il BOUCLE per creare la select :

Download;

- fine del file : fine del form di cfg :

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:

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 :

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

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:

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() :

Download;

o una struttura di controllo più sofisticata:

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:

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:

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

  • aggiungere un test sulla configurazione della visualizzazione degli elementi (logo, titolo...) nel modello:

    Download

diviene:

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:

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,

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

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

Vedi on line : cfg references

P.S.

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

Dernière modification de cette page le 24 novembre 2007

Retour en haut de la page

Tuoi commenti

Rispondere all’articolo

Chi sei?
  • [Connettersi]

Per mostrare qui il tuo avatar, registralo prima su gravatar.com (gratis e indolore). Non dimenticare di fornire il tuo indirizzo email.

Inserisci qui il tuo commento Les choses à faire avant de poser une question (Prolégomènes aux rapports de bugs. )
Aggiungi un documento

Retour en haut de la page

Ça discute par ici

  • (fr) Adaptive Images

    15 novembre 2013 – 66 commentaires

    Un plugin pour permettre aux sites responsive d’adapter automatiquement les images de la page à l’écran de consultation. Adaptive Images, que l’on pourrait traduire par Images adaptatives, désigne la pratique qui vise à adapter les taille, (...)

  • (fr) Métas

    8 août 2009 – 50 commentaires

    Ce petit plugin permet l’ajout, depuis l’espace privé, de metatags aux articles et rubriques de SPIP, ainsi que la mise en exergue de mots importants.

  • (fr) Brownie

    6 juillet 2012 – 43 commentaires

    Brownie est une adaptation pour Zpip du thème du même nom initialement développé par Egrappler.com. Présentation Brownie est un thème Responsive à deux colonnes. La démonstration ci-dessous utilise la version 2.0.0 de Brownie, la dist de SPIP3 (...)

  • (fr) Métas +

    3 décembre – 13 commentaires

    Améliorez l’indexation de vos articles dans les moteurs et leur affichage sur les réseaux sociaux grâce aux métadonnées Dublin Core, Open Graph et Twitter Card. Installation Activer le plugin dans le menu dédié. Dans le panel de configuration, (...)

  • (fr) Acces Restreint 3.0

    11 décembre 2008 – 785 commentaires

    Le plugin accès restreint permet de définir et de gérer des zones de l’espace public en accès restreint. Cette version du plugin a été redévelopée et optimisée tout spécialement pour SPIP 2.0. Il en découle une amélioration des performances sur les gros (...)

Ça spipe par là