Bookmark and Share
Document Actions

Costruire le diverse parti

Note: Return to reference manual view.

Lo scopo del manuale è quello di fornire gli strumenti utili a personalizzare lo stile di Plone o creare il proprio theme.

1. Panoramica generale

Una panoramica generale sulle diverse parti che compongono un theme e sul modo in cui interagiscono l'una con l'altra.

1.1. Panoramica generale

Una panoramica generale sulle diverse parti che compongono un theme e sul modo in cui interagiscono l'una con l'altra.

Un theme Plone è composto da tre parti principali. La figura seguente semplifica attraverso un diagramma la sua struttura:

diagram of the building blocks used to create a theme

Skin

  • riguarda la costruzione generale di una pagina e della presentazione del contenuto
  • comprende page templates, macros, e script Python, ed è anche il luogo in cui mettere fogli di stile e JavaScript
  • per aiutarti a orientarti, vedremo dove trovare guide e approfondimenti online sul linguaggio per template TAL e introdurremo gli skin layers e il loro ordine di precedenza
  • per trovare gli elementi che compongono una skin, guarda in:
    • portal_skins nella Zope Management Interface
    • la directory dedicata alle skins in un prodotto sul file system

Componenti

  • la parte dei componenti riguarda principalmente l'arredamento della pagina (sic);
    sono elementi della pagina che devono mantenere una certa coerenza tra le diverse pagine insieme a quegli elementi che implicano una certa elaborazione dei dati, per esempio l'albero di navigazione, i feed RSS ecc.
  • rendono disponibili un insieme di classi Python e di page template che cooperano nella creazione di viewlet, portlet e visualizzazioni dei contenuti
  • per aiutarti ad orientarti, faremo una panoramica su come le componenti sono collegate tra di loro attraverso ZCML (Zope Configuration Markup Language) e affronteremo anche una prima infarinatura per quanto riguarda le classi Python
  • per trovare gli elementi che costituiscono una componente, guarda in
    • portal_view_customizations nella Zope Management Interface
    • la directory browser in un prodotto sul file system

Configurazione

  • la parte Configurazione gestisce l'ordine di alcuni elementi della pagina (o singoli elementi) e di alcune impostazioni automatiche che altrimenti dovresti configurare manualmente attraverso il pannello di controllo di Plone
  • per aiutarti a capire la configurazione, vedremo assieme quali sono gli strumenti principali per la configurazione manuale e faremo una veloce panoramica su Generic Setup e sull'XML usato per questo scopo
  • gli strumenti di configurazione si trovano in diversi posti all'interno del sito, ma i file richiesi per eseguire una configurazione automaticamente si trovano nella directory profiles in un un prodotto sul file system

2. Skin

Iniziamo con la prima parte, la skin: template, fogli di stile, file Javascript; come customizzarli, dove trovarli.

2.1. I template e TAL (Template Attribute Language)

I principali elementi che compongono una skin sono: page template, immagini, script Python, file CSS e file JavaScript.

(Zope) Page Templates

I page templates (file .pt o ZPT) sono una parte essenziale di un Plone theme e sono probabilmente l'aspetto più semplice da controllare. Sono scritti in un elegante linguaggio per il templating basato su XML, chiamato TAL, che a volte fa uso di macro (METAL), e che a volte incorpora espressioni Python (piccoli operazioni su una singola linea) o script Python veri e propri.

Ci sono varie valide introduzioni a ZPT, e non ci vuole molto per imparare TAL. Ad esempio puoi consultare:

TAL è una linguaggio che consigliamo vivamente di imparare bene. Tutto il resto si può apprendere man mano che si sperimenta e si acquisisce esperienza.

Una pagina web Plone viene composta attraverso un insieme di template, piuttosto che uno, e ci sono un paio di aspetti di ZPT che devi avere ben presenti.

1. Slot

Uno slot è una sezione predefinita di un template. Questo può essere lasciato vuoto oppure ci si può mettere del contenuto di default, ma è sempre possibile modificarlo quando necessario. Uno slot è definito in un template come questo:

<metal:bodytext metal:define-slot="main" tal:content="nothing">
    .....
</metal:bodytext>

e riempito attraverso l'inclusione in un altro template di questo codice:

<metal:main fill-slot="main"> 
    <h1 class="documentFirstHeading"> 
        ...... 
    </h1>
</metal:main>

Il tutorial di ZPT su plone.org affronta l'argomento in modo più dettagliato e la sezione Templates e Components to Page (presto disponibile anche in italiano) fornisce un esempio.

2. Content view templates (_view)

Nota: il termine "vista" (view) ha anche un'applicazione più tecnica, quindi parlando di componenti (più avanti in questo manuale) avrà un significato diverso.

(nella traduzione in italiano il termine nell'accezione più tecnica non verrà tradotto n.d.t.)

Dal punto di vista dell'utente, dell'editor o del visitatore, una vista è il modo in cui un dato contenuto viene presentato sulla pagina. Esiste un'utile introduzione a questo argomento nel Manuale Utenti Plone 3.

Il nome dei template usati per visualizzare un dato contenuto attraverso una vista, per convenzione, ha il suffisso _view (ad esempio, document_view.pt) e possono avere come titolo "Standard View."  Questi template sono di fatto un insieme di informazioni pronto per essere inseriti negli slot.

Script

Esistono alcuni piccoli moduli a sé stanti creati apposta quando si ha la necessità di svolgere operazioni con alcune linee di codice. Nel file system questi hanno estensione .py e vengono visualizzati nella Zope Management Interface sotto forma di Script (Python).

Ecco qui di seguito un frammento preso da event_view (la vista di default per il content type Event) che utilizza uno script di Python per formattare un campo tipo data/ora secondo le convenzioni di default del sito. Se si guarda in CMFPlone/skins/plone_scripts si troverà toLocalizedTime.py - uno script di poche linee.

<span metal:define-slot="inside" 
            class="explain" 
            tal:attributes="title python:here.end()" 
            tal:content="python:here.toLocalizedTime(here.end(),
                                   long_format=1)">End Date Time</span>

2.2. Dove trovare ciò che ti serve

Dove si trova la skin nel tuo sito Plone e in un prodotto che fornisce un theme personalizzato che puoi aver realizzato tu stesso.

Attraverso il Web

Personalizzare i page template, le skin e i CSS attraverso il web è davvero molto semplice.

  • Site Setup > Zope Management Interface > portal_skins

Una volta individuato l'oggetto che vuoi modificare, clicca sul pulsante di modifica; verrà creata una copia dello stesso nel custom layer (solitamente Zope Management Interface > portal_skins > custom n.d.r.).

Nel custom layer è inoltre possibile aggiungere nuovi page template, script di Python e alltri file (come CSS e JavaScript) usando l'elenco a tendina presente in alto a destra. Nella maggior parte dei casi è più semplice individuare un template su cui basare la costruzione di uno nuovo, personalizzandolo e rinominandolo tramite i pulsanti presenti nella ZMI.

Non dimenticate che la linguetta find presente nella ZMI può rivelarsi molto utile se cercate qualcosa in particolare.

Plone Default Skin nel File System

Potete trovare tutte i page template, i fogli di stile, gli script e i Javascript per la skin Plone Default nel prodotto CMFPlone:

[la tua cartella dei prodottti plone]/CMFPlone/skins
Come si può notare, in questa cartella sono presenti un certo numero di directory che corrispondono a specifici skin layer. La maggior parte di esse si spiegano da sole, ma vale la pena ricordare che in plone_templates si trovano solo template generici. Se si desidera rintracciare una vista specifica (ad esempio document_view) la si troverà in plone_content.

Nel proprio Theme Product

The skins folder in your theme product

 

/skins/[namespace del proprio theme].[nome del proprio theme]_custom_templates | custom_images | styles

 

Queste directory diventerranno i vostri skin layer. I template, immagini, e fogli di stile possono essere immagazzinati qui. Se lo si desidera, utilizzando il template di paster chiamato plone3_theme verranno forniti dei fogli di stile vuoti per annullare quelli di Plone Default.

 

/skins.zcml

 

Quando si avvia la propria istanza Zope questo file si occupa della trasformazione delle varie directory in skin layer.

 

Subsidiary files used for installing and setting up the Skin

 

/profiles/default/skins.xml | cssregistry.xml | jsregistry.xml

Quando si installa il proprio theme in Plone questi XML impostano la gerarchia degli skin layer e registrano i fogli di stile e i JavaScript negli appositi registri.

 

2.3. Fogli di stile

In Plone puoi effettuare consistenti modifiche anche solo sovrascrivendo i fogli di stile già esistenti. Esiste un foglio di stile appositamente creato per questo proposito.

Puoi trovare questo foglio di stile chiamato ploneCustom.css in

  • [la tua cartella dei prodottti plone]/CMFPlone/skins/plone_styles
  • Site Setup > Zope Management Interface > portal_skins > plone_styles

Questo foglio di stile viene sempre caricato per ultimo su una pagina, e può quindi essere usato per sovrascrivere qualsiasi altro stile precedentemente definito. Un tutorial completo e molto ben fatto è disponibile alla pagina:

DTML

Come si può notare il ploneCustom.css ha una estensione .dtml e il CSS al suo interno si trova in

/* <dtml-with base_properties> */
 .......
/* </dtml-with> */

DTML è un altro linguaggio utilizzato nei template di Zope; in questo caso viene impiegato affinché certe variabili possano essere prese da un foglio di proprietà (base_properties.props) - ad esempio:

#portal-column-one {
    vertical-align: top;
    width: <dtml-var columnOneWidth missing="16em">;
border-collapse: collapse; padding: 0; }

Non ci sentiamo di raccomandare l'uso di questa tecnica in quanto sta scomparendo gradualmente, ma è giusto sapere che esiste. Attenzione: se si personalizza il ploneCustom.css e si cancella accidentalmente l'inizio o la fine di "dmtl-with", o ci si dimentica di aggiungere l'estensione .dtml, allora potrebbero presentarsi dei problemi.

2.4. Skin Layers

Template, scripts, immagini, CSS e file JavaScript sono organizzati in skin layers. Importante è la priorità tra gli skin layer.

1. Skin Layers

Nell'ottica dell'architettura a componenti 'layer' assume un significato differente.

Una skin comprende vari "strati", chiamati skin layer. Nel file system ogni layer rappresenta una directory. Nella Zope Management Interface (ZMI) ogni layer appare in portal_skins come una cartella a sé stante, contenente page templates, style sheets o script Python.

Portal_skins in ZMI

 

Gli skin layer vengono usati principalmente per due scopi:

  • Innanzitutto permettono di tenere ordinate le cose. Se si dà un'occhiata alla skin di default di Plone (di cui sopra è mostrata una parte della sezione portal_skin), si noterà che templates, scripts, stili e immagini sono divisi in skin layer differenti.
  • L'aspetto più importante è il fatto che essi seguono un ordine di priorità. Questo significa che un oggetto denominato main_template che si trova in un layer superiore sarà trovato e usato prima di un altro oggetto denominato sempre main_template posizionato in un layer che si trova in una posizione inferiore. Questo aspetto sarà maggiormente approfondito nella prossima pagina.

Per creare una skin layer via web, basta semplicemente aggiungere una nuova cartella (in portal_skin n.d.r). Su file system invece si deve aggiungere una directory alla directory delle skin. Si dovrà anche provvedere all'aggiunta di alcune configurazioni al fine di assicurare che la nuova directory possa essere trovata e registrata come skin layer nell'installazione.

Prima di tutto, in [nome del proprio prodotto o pacchetto theme]/skins.zcml

<cmf:registerDirectory
       name="[Your Skin Directory Name]"/>

Poi, in [nome del proprio prodotto o pacchetto theme]/profiles/default/skins.xml

<object name="[Your Skin Directory Name]"
    meta_type="Filesystem Directory View"
    directory="[your namespace].[your theme name]:skins/[Your Skin Directory Name]"/>

e

<skin-path name="[your skin name]" based-on="Plone Default">
  <layer name="[Your Skin Directory Name]"
     insert-after="custom"/>
 </skin-path>

2. Personalizzare tramite l'ordine di priorità

Se hai già lavorato con Plone 2 questo tipo di personalizzazione ti sarà familiare. Come annunciato in precedenza, l'ordine di un layer in una skin determina quale template, file CSS e script Python sarà utilizzato per primo.

Per visionare l'ordine di priorità:

  • Sito > Zope Management Interface > portal _skins
  • Cliccare sulla linguetta Properties

Dovresti ora vedere la lista degli skin layers utilizzati dallo skin di default di Plone, "Plone Default". Layer come plone_templates fanno parte del theme principale di Plone, ma esistono anche altri skin layer che forniscono template derivanti da specifici prodotti aggiuntivi (ad esempio l'editor Kupu).

Ordine di precedenza degli skin layer

In seguito alla richiesta di un template specifico, Plone provvederà alla sua ricerca partendo dalla cima della lista suddetta e, procedendo verso il fondo, cercando di volta in volta il template richiesto in ogni layer.

In cima alla lista si trova un layer personalizzato, custom; ogni template in questa posizione verrà trovato per primo e quindi usato. Per creare quindi la propria versione di un template Plone o di un file CSS è necessario dargli lo stesso nome della versione Plone ma posizionarlo nel layer custom.

Questo è senz'altro l'approccio più semplice. Basterà assicurarsi che la propria personalizzazione sia contenuta in un layer collocato più in alto nella nella pila di skin layer utilizzati; questo è sufficiente per fare in modo che Plone trovi per primo il nostro template personalizzato ed ne ignori la versione originale.

Questa tecnica può quindi essere usata in due modi:

  • Usando la cartella custom

    Tramite Zope Management Interface è possibile aggiungere alla cartella custom la propria versione di template, fogli CSS e così via. Questa verrà a trovarsi sempre in cima, si può star quindi certi che verrà utilizzata la propria versione personalizzata; 
  • Aggiungendo i propri skin layers

    Creare uno o due skin layer nel proprio theme all'interno del file system e assicurarsi che questi skin layer vengano installati appena al di sotto della cartella custom nell'ordine di priorità. Ulteriori informazioni riguardo questo modus operandi verranno fornite nella prossima sezione.

3. Creare una propria skin

Attraverso la ZMI

  • Andare in Site Setup > Zope Management Interface > portal_skins
  • Cliccare sulla linguetta Properties
  • Scegliere Aggiungi Nuovo e dare un nome alla skin
  • È ora possibile inserire la lista degli skin layer che si vuole usare, specificando l'ordine in cui devono essere usati.
  • Infine, a fondo pagina, impostare la nuova skin come default.

Su File System

Se si usa il template di paster plone3_theme, la creazione degli skin layer utilizzati dal nostro theme avverrà all'installazione del pacchetto in Plone.

Paster offre la possibilità di basare la propria skin sullo skin Plone Default. Questo vuol dire che quando si installa il theme nel proprio sito gli skin layer di Plone verranno aggiunti ai propri - ma la priorità verrà data comunque a questi ultimi. Tutto ciò è una buona idea, in quanto permette di riutilizzare dei pezzi di Plone Default senza doverli duplicare, e di sovrascrivere quelli indesiderati.

I passi fondamentali del procedimento sono:

  1. La registrazione delle proprie skin directory come Filesystem Directory Views così che possano diventare skin layer. Tutto ciò avviene in due luoghi: [nome del proprio prodotto o pacchetto theme]/skins.zcml e [nome del proprio prodotto o pacchetto theme]/profiles/default/skins.xml
     <cmf:registerDirectory
          name="[Your Skin Directory Name]"/> 
    
     <object name="[Your Skin Directory Name]"
         meta_type="Filesystem Directory View"     
         directory="[your namespace].[your theme name]:skins/[Your Skin Directory Name]"/>
  2. Aggiungere ed organizzare i propri skin layer in una skin unica in [nome del proprio prodotto o pacchetto theme]/profiles/default/skins.xml
    <skin-path name="[your skin name" based-on="Plone Default">   
           <layer name="[Your Skin Directory Name]"      
                  insert-after="custom"/>  
    </skin-path>
  3. Impostare la propria skin come skin di default in [nome del proprio prodotto o pacchetto theme]/profiles/default/skins.xml
    Questo codice deve includere i nodi dei due esempi precedenti.
    <object name="portal_skins" allow_any="False" cookie_persistence="False"
        default_skin="[your skin name]">
           ......... 
    </object>

Riguardo il nome della Skin

Il nome della propria skin viene richiesto in alcuni posti nel proprio theme product. È bene sapere dove e perché viene utilizzato, per questo riportiamo i casi qui di seguito.

Dove

Attributi/Direttive usati

Uso

profiles/default/skins.xml

<skin_path name="[your skin name]"

Si usa per dare un nome al proprio set di skin layer.

profiles/default/skins.xml

<object name="portal_skins"

default_skin="[your skin name]">

Si usa per impostare il proprio set di skin layer come skin di default.

browser/configure.zcml

<interface …

name="[your skin name]"

/>

Si usa per dare un nome all'interfaccia specifica del theme (vedi la sezione Componenti)

profiles/default/viewlets.xml

<order manager="plone.portalfooter" skinname="[your skin name]"

>

Si usa per precisare il theme quando si riordinano le viewlets nei viewlet managers

(vedi la sezione Componenti)

3. Componenti

La strutturazione della pagina, viewlet, portlet, e i loro manager. Come creare i propri e dove trovare i pezzi di cui abbiamo bisogno.

3.1. Collegare componenti e ZCML

Cose da sapere riguardo i component e come essi siano collegati tra di loro

I component sono strumenti di Plone 3 potenti e flessibili, ma leggermente più astratti dei page templates e degli script Python. Essi sono generalmente combinazioni di classi di Python e page templates collegati insieme in Zope Configuration Language (ZCML) a cui è stato dato un nome.

E' importante ricordare due cose riguardo i components
I componenti sono combinazioni di classi, templates, interfacce, permessi ecc.
Per riuscire a trovare i componenti è necessario prima di tutto guardare nei file .zcml e poi localizzare i loro nomi; questo procedimento permetterà di accedere a classi e templates che fanno parte dei componenti.
I componenti diventano operativi all'avvio di Zope Instance
Una volta che Zope ha letto il file .zcml sarà possibile avere accesso ad un componente. Dato che non è possibile sovrascrivere componenti già esistenti, si consiglia di crearne uno proprio riutilizzando alcune parti.

Parti di un Componente
Un componente diventa operativo tramite un'istruzione di ZCML (vedi esempio sotto). L'istruzione avrà una serie di “attributi” atti a indicare le varie sezioni facenti parte della sua creazione. Queste parti presentano quattro funzioni principali.

  1. Identificare il componente (nel caso di una viewlet questo avviene di solito con un attributo “nome”).
  2. Elaborare le informazioni che il componente dovrebbe mostrare (solitamente questo avviene con una classe Python e indicato con un attributo “classe”). Ad esempio, nel caso di una struttura di navigazione ad albero, questo processo ha il compito di determinare quale parte della struttura debba essere visualizzata per ogni pagina.
  3. Visualizzare le informazioni elaborate dalla classe del componente (questa operazione viene di solito svolta con un page template).
  4. Limitare la visione del componente; nel caso di una viewlet, la sua visione dovrebbe risultare limitata solo ad alcuni utenti registrati (tramite l'ausilio di un attributo “accesso”), oppure limitare la visione ad alcuni contenuti specifici (usando un attributo “per”).

Per ulteriori informazioni su questo argomento fare riferimento alla sezione parti di componente.

Linguaggio di Configurazione di Zope (ZCML)

Il Five Tutorial on WorldCookery.com fornisce un valido aiuto nella comprensione dello ZCML; esistono inoltre molti esempi e tutorial nella sezione documentazione del sito di Plone.

Ecco un esempio di direttiva ZCML che richiama la presentation viewlet (cioè che fornisce semplicemente un link alla versione presentazione di una pagina):

<configure    xmlns="http://namespaces.zope.org/zope"
xmlns:browser="http://namespaces.zope.org/browser">
<browser:viewlet
name="plone.presentation"
for="Products.ATContentTypes.interface.IATDocument"
manager="plone.app.layout.viewlets.interfaces.IAboveContentBody"
class=".presentation.PresentationViewlet"
permission="zope2.View"
/>
</configure>

Si possono notare tre cose:

  • Come ogni tipo di XML, ZCML usa namespaces - prestare attenzione ad essi se si sta scrivendo un file ZCML. Per i componenti dei theme la maggior parte delle volte si utilizza il browser namespace.
  • Gli attributi ZCML spesso si riferiscono a interfacce piuttosto che veri content types, classi o componenti (vedi gli attributi for e manager nell'esempio sopra). Le interfacce saranno discusse più approfonditamente nella prossima sezione.
  • Se si guarda con attenzione l'attributo class si noterà che inizia con un punto. Ciò significa che esso si trova nella stessa directory del file ZCML. Se invece non si trova nella stessa directory sarà necessario corredarlo di un nome completo.

Informazioni dettagliate sulle direttive ZCML sono disponibili nella sezione ZCML Reference dello Zope 3 API - http://apidoc.zope.org/++apidoc++/. Se si desidera acquisire uno stile pulito e disciplinato si consiglia di consultare la ZCML StyleGuide http://wiki.zope.org/zope3/ZCMLStyleGuide.

3.2. Viewlets, Portlets e Altri Componenti

Tipi di componenti: vediamo ora in maniera più approfondita cosa sono le viewlet, le portlet e gli altri componenti.

Viewlet

E' una novità introdotta in Plone 3 ed il suo scopo è quello di fornire rappresentazioni di tutti quegli elementi di una pagina che in genere non subiscono variazioni all'interno del sito. Questi sono organizzati da un altro tipo di componente, un cosiddetto Viewlet Manager.

Per maggiori informazioni si rimanda a:


Portlet

In Plone i portlet sono riquadri informativi, di solito posti nella colonna di sinistra o di destra, contenenti argomenti correlati o approfondimenti direttamente attinenti o meno al soggetto principale della pagina. Il metodo più diffuso per la loro creazione è quello di originarli da page templates ordinarie; oggi però con Plone 3 essi vengono collegati tra di loro come componenti e vengono gestiti da un altro componente, un Portlet Manager.

Per maggiori informazioni fare riferimento a:


View (Browser View)

Per una definizione del termine “view” fare riferimento alla sezione sulle skin. In ogni caso, quando si parla di componenti, il termine View assume un significato più tecnico. Si riferisce infatti ad un componente derivante da una classe Python, da un template o da entrambi. In poche parole la view elabora i dati prima che questi raggiungano la pagina. All'interno del Manuale di Sviluppo di Plone è presente una spiegazione tecnica.

Potrà capitare talvolta che il termine usato sia BrowserView o anche <browser:page> e nei templates il nome di un browser view preceduto da @@. Ci occuperemo nuovamente dei browser view nella sezione Mettere insieme una pagina.

Resource (Browser Resource) & ResourceDirectory

Sebbene abbiamo precedentemente detto che le skin e i layers sono la locazione abituale di page template, immagini e style sheets, è altresì possibile trasformarli in componenti salvandoli in ZCML. In tal caso ci si potrà riferire a loro con un espressione simile: ++resorce++[nome della risorsa]. Lo stesso si può fare per una directory contenente templates e stylesheets.

A questo punto è lecito che sorga la domanda: “Ma allora cosa mi conviene usare, i componenti o le skin?”. Per una discussione sui pro e i contro circa i due modi fare riferimento alla sezione Skin o Component?. Per il momento si suggerisce di mantenere i propri templates, immagini e style sheets nella propria skin. La menzione sui browser resources ha in questo momento il solo scopo di informare su cosa essi siano nel caso in cui ci si imbatta in essi

Da notare che i termini browser e il browser namespace sono usati per delimitare componenti di presentazione; vale a dire, quei bit di codice che vanno a comporre elementi che ad un certo punto si andranno a trovare sul web.

3.3. Personalizzazione o creazione da zero

Possiamo creare personalizzazioni attraverso il web, o costruendole su filesystem, così da collegare componenti esistenti con componenti creati ex novo.

Attraverso il Web

Esattamente come per le skin e i layers, è possibile personalizzare i templates usati dai component attraverso la Zope Management Interface.

  • Site Setup > Zope Management Interface > portal_view_customizations

A tal fine è necessario conoscere il nome del proprio component (ad esempio plone.presentation). La sezione Elementi di questo manuale sarà utile nel caso in cui si ignori tale nome. E' concessa la sola riscrittura del template, il che potrebbe risultare limitante.

Sul File Sistem

Si possono ottenere molti più risultati costruendo il proprio theme product sul file system, con un approccio leggermente diverso.

Piuttosto che sovrascrivere un componente (come per le skin), è molto più semplice crearne una versione tutta propria. Pere fare questo bisognerà modificare collegamenti esistenti o crearne di nuovi nel file .zcml, ma è più semplice di quanto possa sembrare.

Ecco qui riportato un esempio del presentation viewlet così come usato da Plone:                                            

<browser:viewlet
      name="plone.presentation"
      for="Products.ATContentTypes.interface.IATDocument"
      manager="plone.app.layout.viewlets.interfaces.IAboveContentBody"
      class=".presentation.PresentationViewlet"
      permission="zope2.View"
      />

Immaginiamo di voler utilizzare una nuova classe per modificare questa viewlet secondo i nostri gusti. All'interno del file configure.zcml si dovrà fornire di un nome la viewlet e quindi collegarla alla propria classe.

<browser:viewlet
      name="[your namespace].[your presentation viewlet]"
for="Products.ATContentTypes.interface.IATDocument" manager="plone.app.layout.viewlets.interfaces.IAboveContentBody" class=".[your viewlet module].[your viewlet class]"
permission="zope2.View" />
  • Si ricorda che il punto davanti al namespace della propria classe indica che essa sarà rintracciabile nella stessa directory del file configure.zcml.
  • Se non si è sicuri della localizzazione del file configure.zcml, consultare la pagina Dove trovare il necessario di questa sezione.

3.4. Parti dei componenti

Maggiori informazioni su come funzionano i componenti: interfacce, classi Python, permessi, dove e come agire.

3.4.1. Le interfacce e la loro importanza

Le interfacce sono cose da sviluppatori e rappresentano una fetta importante per collegare differenti componenti. È bene capire cosa fanno e come funzionano.

Interfacce come Marcatori

Gli attributi ZCML spesso si riferiscono ad interfacce piuttosto che a vere e proprie classi – l'esempio riportato qui sotto mostra come collegare la presentation viewlet per content types aventi un'interfaccia IATDocument.

<browser:viewlet
name="plone.presentation"
for="Products.ATContentTypes.interface.IATDocument"
manager="plone.app.layout.viewlets.interfaces.IAboveContentBody"
class=".presentation.PresentationViewlet"
permission="zope2.View"
/>

In questo esempio si nota appunto che la presentation viewlet è disponibile per ogni content type che assomigli ad un documento AT o che si comporti come tale (ovvero è disponibile per tutti quelle classi che implementano l'interfaccia IATDocument n.d.r.). Di conseguenza in questo caso l'interfaccia svolge la funzione di marcatore.

Il vantaggio di tutto ciò è che un content type ha la possibilità di avere una o più interfacce, e che più content types possono condividere una stessa interfaccia. Se si sviluppa un nuovo content type e lo si marca con l'interfaccia IATDocument sarà possibile far uso di questa presentation viewlet con l'interfaccia, senza bisogno di ulteriori collegamenti.

Componenti e Interfacce

È possibile marcare i componenti stessi con un'interfaccia – il termine tecnico è “provides”. Da notare che nell'esempio della presentation viewlet ci si riferisce al viewlet manager tramite la sua interfaccia, non il suo nome.

 manager="plone.app.layout.viewlets.interfaces.IAboveContentBody"

Per rintracciare il componente esatto, controllare nel file configure.zcml nella stessa directory delle interfacce. Ad esempio, in plone/app/layout/viewlets/configure.zcml è possibile vedere che l'interfaccia è stata collegata ad una classe Python così da creare un componente viewlet manager:

Come riconoscere un'interfaccia

In genere è abbastanza semplice riconoscere un riferimento ad un'interfaccia, in quanto i loro nomi sono per convenzione preceduti da una “I” e si trovano in un'interfaccia o in namespace di interfacce. Se si ricercano i file interfaces.py o interface.py in ogni egg o prodotto non si troverà all'interno dei file molto codice, ma ci si imbatterà spesso in utili informazioni – di fatto si tratta di una documentazione su cosa un componente, marcato da tale interfaccia è in grado di fare.

Ad esempio:

class IAboveContentBody(IViewletManager):
"""A viewlet manager that sits above the content body in view templates """

Usando il template  di paster plone3_theme ci si accorgerà che c'è un file interfaces.py già pronto a cui si possono aggiungere le proprie interfacce qualora lo si desiderasse.

3.4.2. Classi Python

Le classi Python sono spesso coinvolte nel collegamento di differenti componenti; è utile conoscere almeno un po' il loro funzionamento, specialmente se desideri creare viewlets.

Che cos'è una Classe?

Il modo migliore per comprendere una classe (in python viene definita con class) è pensarla come un distinto pezzo di codice contenente una serie di metodi ('azioni' di qualche tipo) e attributi ('proprietà' aventi un dato valore).

Nel caso dei componenti, lo scopo principale di una classe è quello di elaborare i pezzi di informazione che un componente necessita visualizzare. Un buon esempio è la class del logo viewlet. La si può trovare in:

  • [your egg location]/plone/app/layout/viewlets/common.py – cercare LogoViewlet

Dopo qualche azione preliminare la classe LogoViewlet ricerca il nome dell'immagine che si desidera usare per il logo (è definita nel property sheet di base_properties) e lo assegna a una variabile:

logoName = portal.restrictedTraverse('base_properties').logoName

Dopodiché la classe imposterà un ulteriore proprietà contentente il tag in html del logo, correttamente compilato con tutti i valori necessari quali: dimensione e testo alternativo:

self.logo_tag = portal.restrictedTraverse(logoName).tag()

Infine, nel caso si riveli necessario, imposterà un ulteriore proprietà ricercando il titolo del sito:

self.portal_title = self.portal_state.portal_title()

Nel page template associato con questa viewlet è possibile appigliarsi a queste informazioni (self.logo_tag, self.portal_title) usando la variabile “view”:

<img src="/it/labs/documentazione/manual/usare-i-theme-in-plone-3/costruire-le-diverse-parti/components/s-1/logo.jpg" alt="" tal:replace="structure view/logo_tag" />

Devo per forza usare le Classi?

Le viewlets tendono ad essere collegate con una classe Python che indica il template. Quindi, anche se si desidera solamente creare un nuovo template, sarà necessario scrivere una classe che indichi il nuovo template. La sezione Elementi di questo manuale dovrebbe fornire un sostegno in quanto fornisce un frammento di codice per ogni elemento in modo da copiare e incollare nel proprio prodotto.

Riportiamo un esempio qui di seguito. Il template standard che visualizza il logo del portale in realtà non fa uso di view/portal_title. Se si desidera quindi incorporarlo in qualche modo nel proprio logo bisognerà scrivere il proprio template e anche la propria classe:

from plone.app.layout.viewlets.common import LogoViewlet
from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile

class [nome-della-vostra-classe](LogoViewlet): 
    render = ViewPageTemplateFile('[nome-del-vostro-template]')
  • Per prima cosa importare tutti i moduli necessari per costruire la classe usando la sintassi di Python "from ... import ...".
  • Successivamente si deve definire la classe. In questo caso è importante basarla su una classe preesistente così da poter sovrascrivere solo le cose necessarie e non tutta la classe. Inserire quindi il nome della classe preesistente tra parentesi dopo il nome della propria classe (assicurarsi prima di averla già importata). Non dimenticare i due punti!
  • Riscrivere infine tutti i metodi e gli attributi che si vuole sovrascrivere (di cui si vuole cambiare il comportamento n.d.r.). Nel nostro caso si è scelto di riscrivere solo il metodo render per visualizzare il nostro template.

Nota bene: il rientro del margine è molto importante in Python; per convenzione si usano quattro spazi (invece che il tasto tab). In caso di difficoltà prima di tutto controllare molto bene l'indentazione.

Se si vuole provare con qualcosa di più impegnativo o semplicemente saperne di più, si rimanda ad un'introduzione a Python semplice e diretta:

3.4.3. Permessi

Per limitare la visibilità di un componente è possibile utilizzare l'attributo "permission".

Quando un utente accede ad un sito gli viene assegnato un ruolo (ad esempio 'manager' o 'possessore'). Questo ruolo consiste di fatto in una serie di permessi che forniscono all'utente particolari diritti su particolari aspetti del sito.

Per saperne di più sulle autorizzazioni si consultino le sezioni Understanding Permissions e Security Tutorial su:

Nel caso dei componenti, l'attributo permission consente a plone di discriminare se un dato utente ha diritto o meno di vedere o interagire con un componente. La maggior parte delle viewlet possiedono l'autorizzazione Zope2.View o Zope2.Public, autorizzazioni che vengono assegnate a chiunque, anche visitatori anonimi. Ecco come appare la viewlet Lock Info:

<browser:viewlet 
      name="plone.lockinfo" 
      manager=".interfaces.IAboveContent" 
      class="plone.locking.browser.info.LockInfoViewlet" 
      permission="cmf.ModifyPortalContent" 
      for="plone.locking.interfaces.ITTWLockable" />

Usando cmf.ModifyPortalContent la visualizzazione di questa viewlet viene limitata solo agli autorizzati alla modifica del contenuto (tutti gli altri utenti non hanno necessità di accedere a queste informazioni).

La lista dei permessi o autorizzazioni disponibili è sepolta abbastanza in profondità nel prodotto Five presente nell''installazione base di Zope. Per conoscere la lista più aggiornata cercare in permissions.zcml.

zope2.Public Pubblico, accessibile a chiunque
zope2.Private Privato, accessibile solo tramite password
zope2.AccessContentsInformation Accesso a informazioni di contenuto
zope2.ChangeConfig Permette di cambiare le impostazioni
zope2.ChangePermissions Permette di cambiare le autorizzazioni
zope2.CopyOrMove Per copiare o spostare
zope2.DefinePermissions Definisce le autorizzazioni
zope2.DeleteObjects Per cancellare gli oggetti
zope2.FTPAccess Accesso FTP
zope2.ImportExport Importa/esporta gli oggetti
zope2.ManageProperties Proprietà di gestione
zope2.ManageUsers Proprietà degli utenti
zope2.Undo Annullamento
zope2.View Vista
zope2.ViewHistory Visualizzazione cronologia
zope2.ViewManagementScreens Visualizza gli screen di gestione
zope2.WebDAVLock Blocca gli oggetti WebDAV
zope2.WebDAVUnlock Sblocca gli oggetti WebDAV
zope2.WebDAVAccess Accesso al WebDAV
cmf.ListFolderContents Lista dei contenuti delle cartelle
cmf.ListUndoableChanges Lista dei cambiamenti annullabili
cmf.AccessInactivePortalContent Accesso a contenuti del portale non attivi
cmf.ManagePortal Gestione del portale
cmf.ModifyPortalContent Modifica il contenuto del portale
cmf.ManageProperties Proprietà di gestione
cmf.ListPortalMembers Lista dei membri del portale
cmf.AddPortalFolders Aggiungi cartelle al portale
cmf.AddPortalContent Aggiungi contenuto al portale
cmf.AddPortalMember Aggiungi membro al portale
cmf.SetOwnPassword Impostare la propria password
cmf.SetOwnProperties Impostare le proprie proprietà
cmf.MailForgottenPassword Password per le mail dimenticate
cmf.RequestReview Richiedere una revisione
cmf.ReviewPortalContent Revisionare il contenuto del portale
cmf.AccessFuturePortalContent Accesso al futuro contenuto del portale

 

3.5. Rendere i componenti specifici per un theme

Potresti avere bisogno di creare componenti specifici solo per un particolare theme. Per fare ciò è necessaria un'interfaccia.

Non appena i componenti si attivano con l'avvio di Zope e la conseguente lettura dei file .zcml da parte del programma, essi diventano disponibili per ogni sito Plone che sulla medesima istanza Zope e spesso questo non è il comportamento desiderato.

Un'interfaccia di theme

È possibile specificare che i propri componenti siano disponibili solo per il proprio theme con un'interfaccia marker e un attributo layer in ZCML. Qui di seguito è riportata una versione ricollegata della presentation viewlet:

<browser:viewlet 
      name="[your namespace].[your presentation viewlet]"
for="Products.ATContentTypes.interface.IATDocument" manager="plone.app.layout.viewlets.interfaces.IAboveContentBody" class=".[your viewlet module].[your viewlet class]"
layer=".interfaces.IThemeSpecific"
permission="zope2.View" />
Nota: non confondere un attributo di layer con una skin layer. In questo caso per layer si intende l'intero theme, non una parte di esso.

Esistono due modi di creare un'interfaccia di theme:

Con plone.theme

In Plone 3.0 plone.theme è usato in questo modo:

  • si definisce un'interfaccia marker in [your theme package]/browse/intrefaces.py:
from plone.theme.interfaces import IDefaultPloneLayer
 
class IThemeSpecific(IDefaultPloneLayer):
    """Marker interface that defines a Zope 3 browser layer. """
  • essa viene registrata in ZCML in [your theme package]/browser/configure.zcml
<interface 
    interface=".interfaces.IThemeSpecific" 
    type="zope.publisher.interfaces.browser.IBrowserSkinType" 
    name="[your skin name]" />

Nota: [your skin name] si presenta qui; fare riferimento alla sezione sulle skin per chiarimenti a riguardo.

Con plone.browserlayer

In Plone 3.1 è disponibile il plone.browserlayer.

  • Si crea la propria interfaccia (ad esempio in [your theme package]/browser/interfaces.py)
from zope.interface import Interface

class IThemeSpecific(Interface): 
   """A layer specific to my product """
  • Si registra il tutto nella configurazione (in [your theme package]/profiles/default/browserlayer.xml):
<layers>
   <layer name="[your skin name]" 
          interface="[your namespace].[your theme name].browser.interfaces.IThemeSpecific" />
</layers>

Se si genera il proprio prodotto o egg su filesystem usando il template paster plone3_theme allora il sistema provvederà a questa configurazione da sé (usando il metodo plone.theme), e per trovare il suo nome basterà semplicemente rintracciare l'interfaccia.

Se si guarda in

  • [your theme package]/browser/interfaces.py o configure.zcml

dovrebbe essere possibile trovarla con il nome IThemeSpecific.

Per fare riferimento al layer è possibile scrivere

 layer=".interfaces.IThemeSpecific"

3.6. Skin o componente?

È possibile trasformare in componente qualunque template, file css o directory contenente skin. Quindi perché occuparsi della costruzione tramite skin?

Il prodotto creato con il template di paster plone3_theme si comporta in questo modo:

  • riscrive e/o sovrascrive i template standard dello skin Plone Default nonché i file CSS che andranno nella sezione Skin, cioè la directory delle skin.

  • inserisce i nuovi stylesheets e le nuove immagini nella sezione componenti, cioè la directory browser.

Questo manuale suggerisce di mettere tutti i propri template, gli stylesheet e le immagini nella sezione Skin, così da lasciare nei componenti i template relativi alle viewlet ed alle portlet. Ecco alcune ragioni per farlo:

  • è un'operazione che risulta più facile se si è al primo utilizzo
  • segue i principi di costruzione di Plone
  • fa in modo che perfezionare il proprio theme dopo la sua installazione risulti più facile e veloce. In questo modo si potranno effettuare ulteriori personalizzazioni della Skin all'interno della Zope Management Interface.

Al momento della stesura di questo testo è in corso un'ampia discussione su questo argomento.

Se si desidera eliminare le risorse del browser dal prodotto creato con il template paster plone3_theme:

  • rimuovere le directory immagini e stylesheet in [your theme package]/browser
  • rimuovere la sezione <browser:resourceDirectory ... /> in [your theme package]/browser/configure.zcml
  • rimuovere l'inserimento nel registro degli stylesheet relativo a main.css in [your theme package]/profiles/default/cssregistry.xml
  • se il proprio prodotto è già stato installato è possibile che si debba controllare il registro CSS nella Zope Management Interface (portal_css) e cancellare anche la main_css entry.

3.7. Dove trovare ciò che ti serve

Dove mettere i componenti nel proprio prodotto e come ritrovarli nella Zope Management Interface e nel file system.

Attraverso il Web

I template per la maggior parte dei component possono essere personalizzati attraverso il web:

  • Site Setup > Zope Management Interface > portal_view_customizations

La sezione Elementi potrà essere d'aiuto per indentificare i componenti necessari (portal_view_customization è un tool da usare con estrema cautela n.d.r.).

Plone Default Components nel File System

Se si sta progettando di collegare i propri componenti bisognerà probabilmente rintracciare tutti i file che hanno a che fare con i componenti esistenti da copiare.

Questo potrebbe essere un problema, poiché essi sono raggruppati in differenti egg, quindi bisogna prima trovare la locazione dei vari egg e poi capire quale di questi contiene gli elementi necessari.

  • Per sapere dove trovare gli egg fare riferimento alla sezione Where is What del theme reference.
  • La sezione Elementi sarà utile per rintracciare l'egg contenente il componente necessario.

Nel proprio Theme Product

The browser folder in your theme product

/browser/viewlet.py | viewlet.pt

Un esempio di component viewlet

/browser/interfaces.py                     

Questo si usa per creare la propria interfacia theme

/profiles/default/viewlets.xml                      

Questo file si usa per ordinare le viewlet all'interno del viewlet manager

/browser/configure..zcml                              

Questo file si usa per collegare i component

/browser/templates | styles                         

Queste directory possono essere usate per template, stylesheet e immagini. Esse devono essere registrate come risorse in configure.zcml

4. Configurazione

Come scrivere un file di configurazione e dove posizionarlo.

4.1. Profili

Configurazione e profili.

Per configurazione si intende il normale comportamento di un sito (ad esempio, se permette ad altri di entrare a far parte del proprio sito, o il modo in cui vengono visualizzate le date). Si vorrà probabilmente incorporare alcuni di questi comportamenti nel proprio theme.

Esistono alcuni punti in comune tra componenti, skin e configurazione. Per esempio l'ordine di skin layers e l'ordine in cui compaiono le viewlet all'interno di un viewlet manager sono considerati aspetti di configurazione.

Profilo

Un profilo è un insieme di file di configurazione. Ogni file è scritto in un XML relativamente semplice e si riferisce a un particolare gruppo di componenti o a una pagina di elementi. Esistono due diversi tipi di profili, il profilo base e quello estensione. Se l'obiettivo è il theme sarà sufficiente usare un profilo estensione, cioè un profilo che estenda la configurazione di un sito esistente.

Un profilo viene creato quando viene colegato da ZCML. Qui sotto è riportata la versione creata dal plone3_theme paster template:

<genericsetup:registerProfile
name="default"
title="[your skin name]"
directory="profiles/default"
description='Extension profile for the "[your skin name]" Plone theme.'
provides="Products.GenericSetup.interfaces.EXTENSION"
/>

Si noterà che esso punta ad una precisa directory per l'ubicazione dei file XML e che indica essere un profilo estensione usando un'interfaccia.

4.2. Setup XML Generico

Il linguaggio usato per definire i profili.

L'XML usato per i file profilo è semplice e diretto. Non è disponibile alcun DTD, ma ci sono tantissimi esempi per riutilizzare o adattare il tutto ai propri fini. Se tutto ciò può sembrare troppo, la buona notizia è che ci si può avvalere di un Setup Generico per scrivere i propri file esportando la configurazione da un sito esistente. Ulteriori informazioni a riguardo sono riportate nella documentazione di Generic Setup.

Solitamente il  root node di un profilo XML è un oggetto:

<object name="portal_javascripts" meta_type="JavaScripts Registry">
     .......
</object>

questo corrisponde ad un particolare site tool (in questo caso il registro JavaScripts). I sub-node rappresentano sub-oggetti, mentre gli attributi XML corrispondono agli attributi di quelle classi.

<javascript cacheable="True" compression="none" cookable="True"
            enabled="True" expression="" id="jquery.js" inline="False"/>

In questo caso perciò il sub-node rappresenta una voce nel registro JavaScripts e nelle sue caselle.

screenshot of the javascripts registry in the ZMI

Nel rarissimo caso in cui ci si trovi costretti a capire da soli quali attributi dover usare, sarà necessario esaminare l'API (oppure le interfaccie o le class) del tool in questione. Fare riferimento a http://api.plone.org oppure scavare nel codice sorgente.

4.3. Lo strumento Generic Setup

Lo strumento Generic Setup si trova in portal_setup nella ZMI e si usa per applicare il profilo al proprio sito.

Lo strumento Generic Setup si trova in:

  • Site Setup > Zope Management Interface > portal_setup

E' possibile attivare questa funzione manualmente, ma ai fini del theme, se si è creato un prodotto usando il template di paster plone3_theme, il Generic Setup verrà fatto scattare automaticamente all'installazione del theme sul sito

Per avere ulteriori e più approfondite informazioni sulla funzione Generic Setup fare riferimento al tutorial:

Tuttavia è bene sapere due cose a riguardo.

Nessuna funzione "Annulla"

Sebbene sia possibile disinstallare il proprio theme usando portal_quickinstaller, al momento non è consentito annullare i profili Setup Generico applicati durante l'installazione. La maggior parte delle volte tutto ciò non è un problema, ma ci si può confondere. Per esempio, se si sta facendo un esperimento con l'ordine delle proprie viewlet e si sono provate varie versioni di viewlets.xml in installazioni successive. In questo caso potrebbe essere utile esportare un profilo (i passaggi son spiegati qui sotto) per avere un'idea di quello che si è appena fatto.

Esportare i Profili

È possibile esportare la corrente configurazione del proprio sito sotto forma di un set di file XML. Questo metodo può essere d'aiuto se non si ha un'idea chiara di cosa è stato appena fatto, se si sta cercando un profilo su cui basare la propria configurazione o se si desidera semplicemente che il Generic Setup scriva una configurazione da sè.

  • Site Setup > Zope Management Interface > portal_setup
  • Cliccare su Esporta
  • Selezionare gli step che si desidera esportare
  • Cliccare su Esporta Step Selezionati
  • Apparirà un file zip con i file XML pertinenti

Non è sempre cosa ovvia sapere di quale export step si ha bisogno per ottenere l'esatta configurazione desiderata, potrebbe essere necessario dover sperimentare.

4.4. Dove trovare ciò che ti serve

Come funziona la configurazione attraverso il web e come rintracciare i file nel filesystem.

Attraverso il Web

Esistono diversi modi per configurare il proprio sito attraverso il web. La sezione Elements (presto disponibile anche in italiano) della versione originale di questo manuale fornisce indicazioni su dove guardare per configurare particolari elementi della pagina. In generale:

  • Site Setup conduce alle differenti configurazioni generali per le impostazioni del sito (Generic Setup n.d.r.)
  • Site Setup > Zope Management Interface porta al registro degli stylesheet e dei JavaScript (portal_css e portal_javascripts)
  • Aggiungere /@@viewlet_manager all'URL permetterà di ordinare, nascondere e visualizzare le differenti viewlets registrate nel sito

Configurazione Default di Plone nel File System

La maggior parte dei file di configurazione necessari si trovano in:

  • [your products location]/CMFPlone/profiles/default

Prestare comunque attenzione al fatto che alcuni file di configurazione potrebbero trovarsi in prodotti sviluppati da terzi. Ad esempio, se si desidera aggiungere degli stili a Kupu, l'editor di testo visuale di Plone, come parte del proprio theme, si dovrà allora recuperare il file kupu.xml che si trova in [your products location]/kupu/plone/profiles/default

Esiste un'alternativa alla ricerca a tappeto per tutto il file system, e cioé utilizzare la funzione Setup Generico per esportare il profilo.

Nel proprio Theme Product

/profiles/default/
Questa directory contiene i file XML per Generic Setup. Alcuni file già pronti all'uso saranno forniti dal template paster plone3_theme, così da poter impostare le proprie skin layers, salvare i propri style shetts e Javascipt, nonché ordinare le proprie viewlets.

/profiles/default/import_steps.xml
Questa file è essenziale ai fini dell'installazione, non dovrebbe esserci bisogno di toccarla.

/profiles/default/cssregistry.xml | jssregistry.xml
Questi file registreranno gli stylesheet e i JavaScript presenti nella vostra skin. Per aggiungere ogni altro CSS o JavaScript sarà necessario editare direttamente il file secondo l'esigenza.

/profiles/default/skins.xml
Questa posizionerà i vostri skin layer nel giusto ordine di priorità. Non sarà necessario apportarvi modifiche a meno che non siano state rinominate, rimosse o aggiunte directory nella directory skins del proprio theme.

/profiles/default/viewlets.xml
Stabilisce in quale ordine appariranno le viewlet nel rispettivo viewlet manager. Da modificare nel caso si vogliano aggiungere nuove viewlet

/profiles.zcml
Questo file solitamente viene utilizzato per registrare il nostro profilo e renderlo disponibile all'uso da parte di Generic Setup all'avvio di Zope (questo file dovrà inoltre essere incluso nel file configure.zcml affinché sia utilizzato da Zope n.d.r.)

 

Supporto

Ottieni un
aiuto veloce e mirato sul forum, gratis!

partecipa al forum

 

Segui le icone

 

Livelli di difficoltà

livello guruSolo per i "guru"!
livello avanzatoPer configuratori e sviluppatori
livello medioPer chi ha già familiarità
livello basePer tutti!

 

I video

video

Il documento è supportato da un video!