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

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

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

• ZPT - Zope Page Templates, un tutorial su plone.org
• Zope Page Template Reference su Zope.org

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

• ZPT - Advanced Usage,  un tutorial di livello avanzato su plone.org

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>

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

/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.

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:

• http://plone.org/documentation/tutorial/working-with-css

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.

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.

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

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

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.

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:

• sezione Anatomia di una Viewlet di questo manuale;
• http://plone.org/documentation/tutorial/customizing-main-template-viewlets;
• http://plone.org/documentation/tutorial/customization-for-developers/viewlets/.

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:

• sezione Anatomia di una Portlet di questo manuale;
• http://plone.org/documentation/how-to/override-the-portlets-in-plone-3.0/;
• http://plone.org/documentation/tutorial/customization-for-developers/portlet-renderers/ (se si desidera una spiegazione più tecnica);
• http://plone.org/documentation/how-to/adding-portlet-managers.

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.

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.

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"

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.

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

/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

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.

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.

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.

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:

• Understanding and Using Generic Setup.

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.

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