Poichè questa guida vuole essere per principianti, ecco alcuni  cenni utili per chi comincia.

Installazione

Per installare Plone si può far riferimento alle prime due pagine di Usare paster e zopeskel per la generazione automatica di content type. Per altri approfondimenti si può guardare come installare Plone su linux, su windows (Plone.org), mentre su Mac si può guardare su questo sito.

Il primo passo: il buildout

Una volta installato Zope-Plone, occorre predisporre l'ambiente, facendo il "buildout". In pratica da un file di configurazione si costruisce l'ambiente  con tutti i componenti di cui si può aver bisogno. La guida a cui ci si può riferire per approfondire l'argomento è Setting up Buildout Using the Windows Installer for Plone

Si deve saper come fare un buildout, perchè uno dei  componenti da installare sarà proprio il tema che andremo a costruire.

In sostanza la prima volta occorre inizializzare il buildout con

percorso_di_installazione\python.exe bootstrap.py

Questo comando predispone l'ambiente,  crea le cartelle necessarie e anche il file buildout.cfg che è il file che dovremo modificare per aggiungere il nostro tema.

Il passo successivo è scaricare i componenti e costruire l'ambiente con

bin/buildout –v

Dove -v mostra semplicemente a schermo ciò che accade, e a cui si può aggiungere alla fine "–c develop.cfg" se si usa un proprio file di configurazione che estende il buildout.cfg.

Due cose a cui fare attenzione

Un paio di cose a cui fare attenzione, all'interno del file sono le credenziali di accesso e  la porta su cui sarà attivata l'istanza di Zope. Questo lo si può leggere nella sezione

[instance]
...
user = admin:admin
http-address = 8080

Accendere il server e creare il sito

bin/instance fg

Dove "fg"sta per foreground ossia in primo piano. Per interrompere l'istanza basta la combinazione CTRL+C.

Collegarsi a Zope

Verranno chieste le credenziali, a cui abbiamo appena detto di fare attenzione, quindi non dovreste avere problemi di accesso.

Creare il sito

Per creare il sito basterà

1. Scegli dal menù a tendina in alto a destra “Plone site”
2. Click su ADD
3. Nella finestra successiva, si devono solo definirne alcune  proprietà, basteranno
   Id: nomesito*
   Titolo: Titolo del sito;
   

NB

La ZMI può spiazzare per chi non la conosce, ma per personalizzare un tema, basta una conoscenza molto superficiale. ZMI è l'interfaccia per gestire il server e i suoi siti. A sinistra trovate la navigazione a destra i contenuti. Sopra ai contenuti esiste un menù a linguette per accedere alle varie proprietà/azioni che si possono fare sui contenuti (es. cercare).

Se dovete aggiungere un sito a Zope, e non trovate il menù a tendina basterà un click nella "Root folder" (in alto a sinistra)

Per cominciare a personalizzare il tema base di plone si devono compiere due ulteriori passi.

Una guida approfondita è How to Create a Plone 3 Theme Product on the Filesystem

Creare il tema

Nella cartella scr del sito Plone appena creato, si deve predisporre il tema:

paster create –t plone3_theme

Si avvierà paster e occorrerà impostare le varie opzioni (il nome del tema, l'autore ecc. ecc.)

Es.
nome = rer.nomesito_theme
namespace= rer
package= nomesito_theme
skin name= Nomesito
skinbase= [invio]
empty_styles= FALSE
...

L'ultima risposta, permette di partire con un tema già "pieno" e non si rischierà di dimenticare gli stili di alcune interfacce.

Per utilizzare il tema in Plone

Come annunciato, dovremo configurare Zope - Plone per usare il tema appena creato, e quindi dovremo agire sul buildout.cfg. Anche per questo esiste una guida approfondita: How to Install a 3.x Theme Using Buildout

Modificare il file buildout.cfg

Nella root del sito dovremo modificare il file  affinchè usi il tema, seguendo l'esempio:

1. Sezione "egg=" aggiungere src/rer.nomesito_theme
2. Sezione "product" aggiungere rer.nomesito_theme
   

Installare il tema da ZOPE

1. Click sul nome del sito creato al passo precedente (nell'area a sinistra sotto la Root folder)
2. Scegliere “portal quickinstaller” (a destra, piuttosto in basso)
3. Selezionare il tema dalla lista “Installable products” (sempre nel riquadro destra, in alto)
4. Click su install

Per poter personalizzare il tema, dovremo agire in diversi posti, in diversi files e cartelle, è quindi utile capire dove trovare le cose. Il riferimento più completo è ovviamente Plone Theme Reference, ma è un po' troppo esteso.

Per iniziare basta sepere che ogni cartella del tema ha questa struttura:

• Browser
  nella quale mettere i files template Plone .pt* che si potrebbe voler modificare
  • Images
  • Stylesheet
    contiene main.css, lo stile del sito su cui agire con le modifiche
• Profiles
  • Default
    contiene viewlets.xml, il file da modificare per nascondere/mostrare elementi della pagina
• Skin
  • ..._images
    contiene le immagini che si vogliono usare nel tema
  • ..._templates
    nel quale mettere i files template .pt* che si potrebbe voler aggiungere
  • ..._styles
    contiene base_properties.props il primo file su cui agire per personalizzare un tema
    

*NB

I template Plone per i vari elementi, sono dei files .pt che si trovano in eggs/plone.app.layout. Per modificarli, li si copia nel proprio tema e lì, li si modifica dove occorre. Per avere questa configurazione è utile un file di configurazione aggiuntivo al buildout, quel develop.cfg citato all'inizio. Questo il codice che contiene.

[buildout]
extends = buildout.cfg
  
parts+=
    omelette
    pydev

eggs +=
    stxnext.pdb

[zeoserver]
effective-user =

[instance]
eggs +=
    plone.reload

zcml +=
    plone.reload
    stxnext.pdb

[omelette]
recipe = collective.recipe.omelette
eggs =
    ${instance:eggs}

products =
    ${instance:products}

[pydev]
recipe = pb.recipes.pydev

eggs =
   ${instance:eggs}
extra_paths =
   ${omelette:location}
   ${zope2:location}/lib/python
pydevproject_path = ${buildout:directory}/.pydevproject

 Personalizzare le proprietà di base

Per le prime modifiche, si può agire su un solo file, basta modificare:
Skin/.._styles/base_properties.props

Per chi vuole approfondire la cosa, esiste una pagina di riferimento sulle base_properties

In base_properties.props si può agire per cambiare:

• immagine del logo (che deve esistere e va posionata in skin/..._images)
• tipo di font del sito
• dimensione dei font
• colori del testo
• colori dei link
• colori dei menù di Plone
• dimensioni delle colonne del contenuto
  

Per modificare altri aspetti della grafica

Per modificare qualsiasi altra proprietà, occorre modificare il file browser/stylesheet/main.css e il metodo più comodo è quello di utilizzare Firebug, per scoprire quali classi modificare.

In generale la documentazione utile per capire dove agire è Working with CSS e per vedere istantaneamente le modifiche, si può far riferimento a How to Make Your CSS Changes Take Effect Instantly

Gli elementi dell’interfaccia (logo, motore di ricerca, ecc.) sono mostrati tramite le viewlets. Ogni viewlet appare di norma, dentro ad uno specifico contenitore, chiamato viewletmanager.

Collegandosi all'indirizzo del proprio sito basta aggiungere /@@manage-viewlets per capire com'è organizzata l'interfaccia di Plone.

Si può capire dove si vuole spostare un oggetto, il nome del manager è scritto nel riquadro azzurro sopra le viewlet, basta individuare il nome di quale viewletmanager in cui appare l’oggetto e il nome del manager dove lo si vuole posizionare.

Un esempio di viwletmanager è il primo in alto: plone.portaltop
Un esempio di viwelet è quella in basso: plone.site_actions

Per nascondere un elemento si può agire sui vari elementi direttamente da questa pagina, esiste infatti un link hide/show per nascondere mostrare viewlets. Ma se si sta costruendo un tema, lo si vuole poter esportare o installare altrove. Quindi è  meglio lavorare in modo diverso ed agire sui files di configurazione. Per operazioni di base sulle viewlet basta agire sul file  profiles/default/viewlets.xml il cui codice è una sequenza di cose del tipo:

<object>
  <order manager="plone.portaltop" skinname="Plone Default">
    <viewlet name="plone.header" />
    <viewlet name="plone.app.i18n.locales.languageselector" />
  </order>

Nel viewlets.xml del tema appena creato,  è bene cambiare il tema di riferimento e ovunque appaia  skinname="Plone Default", scrivere skinname="nomesito_theme”

Es:

<object>
  <order manager="plone.portaltop" skinname="nomesito_theme">

Per nascondere una viewlet

E' un operazione semplice. Sono necessarie due modifiche nel file viewlets.xml

1. togliere il tag <viewlet> corrispondente nel blocco <order> del manager che contiene la viewlet stessa
2. lo stesso tag <viewlet> tolto nel punto precedente va inserito in un blocco <hidden> con gli stessi attributi del blocco <order>
   

Esempio

da:

<object>
  <order manager="plone.nomemanager" skinname="nomesito_theme">
    <viewlet name="plone.header" />
    <viewlet name="plone.nome_viewlet_da_nascondere"/>
    <viewlet name="plone.app.i18n.locales.languageselector" />
</order>

a:

<object>
  <order manager="plone.nomemanager" skinname="nomesito_theme">
    <viewlet name="plone.header" />
    <viewlet name="plone.app.i18n.locales.languageselector" />
</order>

...

<hidden manager="plone.nomemanager" skinname="nomesito_theme">
        <viewlet name="plone.nome_viewlet_da_nascondere"/>
</hidden>

Per spostare una viewlet all’interno dello stesso manager basta cambiare l’ordine delle viewlet nel file viewlet.xml.
Come spostare o nascondere elementi è anche spiegato su Reordering and Hiding viewlets.

Riprendendo il codice di esempio, per spostare una viewlet basta questo:

<object>
    <order manager="plone.portaltop" skinname="Plone Default">
          <viewlet name="plone.app.i18n.locales.languageselector" />
          <viewlet name="plone.header" />
    </order>

Per spostare una viewlet in un altro manager

Se lo sposamento è più ampio, ad esempio si vogliono mettere le site_actions in fondo alla pagina,  occorre fare qualcosa di più. Se si sposta  il codice xml della viewlet da un manager all’altro nel file viewlets.xml, la viewlet semplicemente non funzinerà. Occorre anche modificare la configurazione della viewlet.  La si deve cioè registrare nell’interfaccia del manager che la userà (per approfondire: Viewlet registration in Plone 3.0).

In parole semplici si deve:

1. aprire il file /browser/configure.zcml
2. copiare, incollare e modificarne il codice che usa plone.
   Il codice da modificare è in eggs/plone.app.layout/plone/app/layout/viewlets/configure.zcml  e va incollato nel file appena aperto.
   Esempio di codice modificato:
   

   <!-- The site actions -->
   <browser:viewlet
             name="plone.site_actions"  [la viewlet che si vuole spostare]
             manager="plone.app.layout.viewlets.interfaces.IPortalFooter" [il manager in cui la si vuole spostare]
             class="plone.app.layout.viewlets.common.SiteActionsViewlet"        
             layer=".interfaces.IThemeSpecific" permission="zope2.View"/>

3. Quindi si può registrare la viewlet nel manager giusto, ossia si sposta il codice xml nel file profiles/default/viewlets.xml.
   

 Anche per questa operazione esiste la guida ufficiale: Moving a viewlet from a viewlet manager to another one

Se oltre a spostare una viewlet la si vuole anche modificare, cambiando l’html di come deve apparire, bisogna fare un  passo in più. In sostanza aggiungeremo un nuovo pezzetto di pagina anche se per semplificarci la vita, il pezzetto che aggiungeremo non sarà però completamente nuovo. In questo modo potremo  incollare un po' di codice da Plone cambiando qualcosa qua e là.

La parte difficile da capire è che per modificare una viewlet di Plone, occorre definire una nuova classe che la deve gestire e configurarla nel nostro tema. Ecco i passi da seguire.

Individuare la viewlet

Le viewlet di Plone si trovano in eggs/plone.app.layout. Prendiamo ad esempio  documentactions.pt. Tutto ciò che va fatto è copiare il file nella cartella /browser del proprio tema

Individuare la configurazione

Ogni viewlet viene registrate nel file di configurazione di Plone. Si deve quindi trovare il codice del manager in eggs/plone.app.layout/plone/app/layout/viewlets/configure.zcml e portarlo da noi.

Nel nostro caso basta cioè cercare la parola "documentactions" in quel file. Si troverà questo codice:

<browser:viewlet
name="plone.abovecontenttitle.documentactions"
manager=".interfaces.IBelowContentBody"
class=".content.DocumentActionsViewlet” permission="zope2.View"  />

Non lo useremo subito, ma teniamo il file aperto, ci servrà dopo. Questo codice sarà quello che alla fine dovremo cambiare maggiormente (oltre a quello del template vero e proprio). Per ora ci basta  capire qual'è il nome della classe che ci serve.

Creare la classe

La parte difficile comincia ora, perchè si deve aggiungere una nuova classe ai propri files. La classe serve per gestire la viewlet, per poterla usare.

class NometemaDocumentActionsViewlet(DocumentActionsViewlet):
    index = ViewPageTemplateFile("documentactions.pt")

Configurare la viewlet

Quindi si deve registrare la viewlet nell’interfaccia. Per complicarci le cose decidiamo anche di spostarla in un manager diverso, visto che lo abbiamo imparato prima.

<!-- Render the document actions -->
    <browser:viewlet
        name="plone.abovecontenttitle.documentactions"
        manager="plone.app.layout.viewlets.interfaces.IAboveContent"
        class=".viewlets.NometemaDocumentActionsViewlet" 
        layer=".interfaces.IThemeSpecific" permission="zope2.View" />

Proviamo ad analizzarlo:

1. Il manager cambia in due punti, cambia il suo percorso perchè sto lavorando su un file del mio tema
   

   manager="plone.app.layout.viewlets

2. cambia anche il manager, visto che volevamo complicarci la vita

   da manager=" ... .IBelowContentBody" 
   a manager= ... .IAboveContent"

3. cambia la classe, perchè ora userà la nostra
   

   class=".viewlets.NometemaDocumentActionsViewlet"

Sporcarsi le mani

Approfondimenti

Per avere una panoramica più ampia di com'è strutturato Plone al di là delle poche cose dette in questa guida, si può leggere What controls what you see.

Credits

Autore: Jacopo Deyla - Regione Emilia-Romagna
Revisione: RedTurtle Technology