Manuale plone 4
1 like1,923 views
Il documento è una guida all'uso di Plone 4, un sistema di gestione dei contenuti che consente la creazione e gestione di siti web. Include sezioni su come aggiungere e gestire contenuti, utilizzare editor visivi, e creare temi, oltre a fornire informazioni sui ruoli degli utenti e sulla navigazione. È indirizzato a utenti, redattori e amministratori, evidenziando la facilità d'uso anche per chi ha poca esperienza tecnica.
![Documentazione di Plone, Release 4
Il file ‘manifesto’
E’ possibile dare ulteriori informazioni sul tema inserendo all’inizio della directory di un tema un file con nome
manifest.cfg accanto al file rules.xml.
Il file ha un aspetto di questo tipo:
[theme]
title = My theme
description = A test theme
Come si vede, il file ‘manifesto’ può essere utilizzato per fornire un titolo del tema più comprensibile ed una descrizione più lunga da usare poi nel pannello di controllo. E’ richiesta solo l’intestazione [theme] – tutte le altre chiavi
sono opzionali.
Si può anche impostare:
rules = http://example.org/myrules.xml
per usare un nome per il file delle regole diverso da rules.xml (si deve fornire un URL o un percorso relativo).
Per cambiare l prefisso per il percorso assoluto (vedi Impostazioni avanzate), si usa:
prefix = /some/prefix
Per impiegare un DOCTYPE diverso da XHTML 1.0 Transitional per il contenuto a cui viene applicato il tema,
aggiungere p. es.:
doctype = html
Per visualizzare nel pannello di controllo Theming un’anteprima user-friendly del tema, aggiungere:
preview = preview.png
preview.png è il file di un’immagine relative to the location del file manifest.cfg.
Estensioni del motore di Diazo possono aggiunger il supporto per ulteriori blocchi di parametri configurabili.
Sintassi delle regole
Nel seguito un breve sommario della sintassi delle regole di Diazo. Vedi http://diazo.org per maggiori dettagli ed altri
esempi.
Selettori
Ciascuna regola è composta da un tag XML che opera su uno o più elementi HTML nel contenuto e /o sul tema. Gli
elementi su cui operare sono indicati da attributi delle regole noti come selettori.
Il modo più semplice per selezionare gli elementi è quello di utilizzare una espressione selettore CSS, come ad esempio
css:content=”#content” o css:theme=”#main .content”. Si può utilizzare una qualsiasi espressione CSS3 valida (inclusi
pseudo-selettori quali:first-child).
I selettori standard, css:theme e css:content, operano sull’elemento/i che soddisfano la selezione. Se invece si vuole
operare sui figli degli elementi selezionati si deve usare css:theme-children=”...” o css:content-children=”...”.
Se non è possibile costruire una espressione CSS 3 adeguata, è possibile utilizzare espressioni XPath come content=”/head/link” o theme=”//div[@id=’main’]” (si noti la mancanza di un prefisso css: quando si usano le espressioni
2.1. Creare un tema con Diazo
147](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-151-320.jpg)
![Documentazione di Plone, Release 4
<merge
attributes="class"
css:content="body"
css:theme="body"
/>
<copy
attributes="class"
css:content="#content"
css:theme="#main"
/>
Queste regole operano sugli attributi. <merge /> aggiungerà i contenuti letti nel tema per gli attributi indicati, ai
valori di ogni attributo esistente nel contenuto avente lo stesso nome; i valori sono separarti da spazi bianchi. E’
principalmente usato per aggiungere classi CSS.
<copy /> copia gli attributi dagli elementi che soddisfano la regola nel contenuto, nei corrispondenti elementi nel tema;
gli attributi con lo stesso nome eventualmente già presenti nel tema, vengono completamente sostituiti.
L’attributo attributes può contenere una lista di attributi separati da spazi bianchi, oppure il valore speciale * per
operare su tutti gli attributi degli elementi che soddisfano la regola.
Modifiche avanzate
Invece di selezionare il markup da inserire nel tema dal contenuto, è possibile inserire il markup direttamente nel file
delle regole, come nodi figlio dell’elemento della relativa regola:
<after css:theme="head">
<style type="text/css">
body > h1 { color: red; }
</style>
</after>
Nello stesso modo si può operare sul contenuto. E’ così possibile modificarlo prima dell’applicazione delle regole:
<replace css:content="#portal-searchbox input.searchButton">
<button type="submit">
<img src="images/search.png" alt="Search" />
</button>
</replace>
Oltre ad aggiungere in questo modo HTML statico, si possono usare le istruzioni XSLT che operano sul contenuto. In
XSLT, si possono anche usare direttamente i selettori css:
<replace css:theme="#details">
<dl id="details">
<xsl:for-each css:select="table#details > tr">
<dt><xsl:copy-of select="td[1]/text()"/></dt>
<dd><xsl:copy-of select="td[2]/node()"/></dd>
</xsl:for-each>
</dl>
</replace>
Utilizzando l’attributo href per specificare il percorso di una risorsa relativamente alla root del sito Plone, le regole
possono operare su contenuti provenienti da sorgenti che non siano l’attuale pagina restituita da Plone:
<after
css:theme-children="#leftnav"
150
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-154-320.jpg)
![Documentazione di Plone, Release 4
portal L’oggetto radice del portale.
context_state La vista @@plone_context_state, da cui è possibile cercare altri valori come l’URL del contesto o la
vista predefinita.
portal_state La vista @@plone_portal_state, da cui è possibile cercare altri valori come la root dell’URL di
navigazione o se l’utente attuale è collegato (autenticato?) o meno.
Vedi plone.app.layout per i dettagli circa le viste @@plone_context_state e @@plone_portal_state.
I parametri del tema sono normalmente parte integrante di un temaTheme e saranno pertanto impostati in base al manifesto del tema quando il tema viene importato od abilitato. Questo è fatto utilizzando la sezione [theme:parameters]
nel file manifest.cfg. Per esempio:
[theme]
title = My theme
description = A test theme
[theme:parameters]
ajax_load = python: request.form.get(’ajax_load’)
mode = string: test
Debug del tema
Quando Zope è in modalità sviluppo (cioè esecuzione in foreground in una console con bin/instance fg), il tema sarà
ricompilato ad ogni request. Se la modalità non è di sviluppo viene compilato al primo accesso, poi ricompilato solo
se vengono cambiati i valori del pannello di controllo.
Anche nella fase di sviluppo è possibile disabilitare temporaneamente il tema aggiungendo alla request una query
string con il parametro diazo.off=1. Per esempio:
http://localhost:8080/Plone/some-page?diazo.off=1
Il parametro viene ignorato se la modalità non è di sviluppo.
Regole di uso comune
Le ricette che seguono mostrano le regole di uso comune nella costruzione di temi per Plone:
Per copiare il titolo della pagina:
<replace css:theme="title" css:content="title" />
Per copiare il tag <base /> (necessario perchè funzionino i link di Plone):
<replace css:theme="base" css:content="base" />
Se non è presente nel tema il tag <base />, si può procedere così:
<before css:theme-children="head" css:content="base" />
Per eliminare dal tema tutte le risorse relative agli stili ed a JavaScript e copiarle invece dallo strumento di Plone
portal_css:
152
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-156-320.jpg)
![Documentazione di Plone, Release 4
Memorizzare gli oggetti
Per memorizzare un oggetto nello ZODB, lo colleghiamo semplicemente a qualsiasi altro oggetto che è già presente
nel database. Quindi, l’oggetto root funziona come un punto di partenza. L’oggetto root è un dizionario e si può
iniziare a memorizzare gli oggetti direttamente da lì:
>>> root[’account-1’] = Account()
>>> root[’account-2’] = Account()
I framework come Zope creano solamente un singolo oggetto nella radice dello ZODB che rappresenta l’applicazione
stessa e poi referenziano tutti gli altri oggetti da lì. Essi scelgono nomi come ‘app’ per il primo oggetto che posizionano
nello ZODB.
Transazioni
Ora abbiamo due oggetti posizionati nel oggetto root e nel nostro database. Tuttavia, essi non sono ancora memorizzati
in modo persistente. Lo ZODB utilizza le transazioni e per rendere permanenti le modifiche, è quindi necessario il
commit della transazione:
>>> import transaction
>>> transaction.commit()
>>> root.keys()
[’account-1’, ’account-2’]
Ora possiamo stoppare e riavviare l’applicazione e guardare di nuovo all’oggetto root. Vedremo che le voci ‘account-1’
e ‘account-2’ sono ancora presenti e sono gli oggetti che abbiamo creato.
Gli oggetti che non sono ancora stati memorizzati nello ZODB non vengono rimossi da un abort.
Se l’applicazione apporta delle modifiche durante una transazione ma scopre che non vuole fare il commit di quelle
modifiche, allora si può annullare la transazione e le modifiche vengono annullate per noi:
>>> del root[’account-1’]
>>> root.keys()
[’account-2’]
>>> transaction.abort()
>>> root.keys()
[’account-1’, ’account-2’]
Oggetti persistenti
Un ultimo aspetto che dobbiamo coprire sono gli stessi oggetti persistenti. Lo ZODB sarà lieto di memorizzare quasi
qualsiasi oggetto Python che gli viene passato (ma non memorizzerà i file per esempio). Ma per capire quali oggetti
sono stati modificati, lo ZODB ha bisogno che quegli oggetti collaborino con il database. In generale, per fare ciò
basta ereditare da persistent.Persistent. Quindi la nostra classe di esempio sopra andrebbe modificata così:
import persistent
class Account(persistent.Persistent):
# ... same code as above ...
Date un’occhiata alla documentazione di riferimento per saperne di più sulle regole di persistenza e sugli oggetti
specializzati come i BTrees.
2.2. ZODB - un database nativo ad oggetti per Python
157](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-161-320.jpg)
![Documentazione di Plone, Release 4
# in the root
if not dbroot.has_key(’userdb’):
from BTrees.OOBTree import OOBTree
dbroot[’userdb’] = OOBTree()
userdb = dbroot[’userdb’]
Inserting a new user is simple: create the User object, fill it with data, insert it into the BTree instance, and commit
this transaction.
# Create new User instance
import transaction
newuser = User()
# Add whatever attributes you want to track
newuser.id = ’amk’
newuser.first_name = ’Andrew’ ; newuser.last_name = ’Kuchling’
...
# Add object to the BTree, keyed on the ID
userdb[newuser.id] = newuser
# Commit the change
transaction.commit()
The transaction module defines a few top-level functions for working with transactions. commit() writes any
modified objects to disk, making the changes permanent. abort() rolls back any changes that have been made,
restoring the original state of the objects. If you’re familiar with database transactional semantics, this is all what
you’d expect. get() returns a Transaction object that has additional methods like note(), to add a note to the
transaction metadata.
More precisely, the transaction module exposes an instance of the ThreadTransactionManager transaction manager class as transaction.manager, and the transaction functions get() and begin() redirect
to the same-named methods of transaction.manager. The commit() and abort() functions apply the methods of the same names to the Transaction object returned by transaction.manager.get(). This is for
convenience. It’s also possible to create your own transaction manager instances, and to tell DB.open() to use your
transaction manager instead.
Because the integration with Python is so complete, it’s a lot like having transactional semantics for your program’s
variables, and you can experiment with transactions at the Python interpreter’s prompt:
>>> newuser
<User instance at 81b1f40>
>>> newuser.first_name
’Andrew’
>>> newuser.first_name = ’Bob’
>>> newuser.first_name
’Bob’
>>> transaction.abort()
>>> newuser.first_name
’Andrew’
# Print initial value
# Change first name
# Verify the change
# Abort transaction
# The value has changed back
Rules for Writing Persistent Classes Practically all persistent languages impose some restrictions on programming
style, warning against constructs they can’t handle or adding subtle semantic changes, and the ZODB is no exception.
Happily, the ZODB’s restrictions are fairly simple to understand, and in practice it isn’t too painful to work around
them.
2.2. ZODB - un database nativo ad oggetti per Python
163](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-167-320.jpg)
![Documentazione di Plone, Release 4
$ ./bin/python
Questo comando fornisce un prompt Python che può essere utilizzato per eseguire il codice di questo libro.
zc.buildout
Utilizzando zc.buildout con la ricetta zc.recipe.egg, è possibile creare un interprete Python che ha a disposizione gli eggs specificati. Per prima cosa, installare zc.buildout utilizzando il comando easy_install. (è
possibile farlo anche dentro all’ambiente virtuale). Per creare un nuovo buildout per fare esperimenti con gli egg
Python, per prima cosa creare una cartella e inizializzarla utilizzando il comando buildout init :
$ mkdir mybuildout
$ cd mybuildout
$ buildout init
Ora la nuova cartella buildout è un buildout. Il file di configurazione di default per il buildout è buildout.cfg. Dopo
l’inizializzazione, avrà questo contenuto:
[buildout]
parts =
Cambiamolo così:
[buildout]
parts = py
[py]
recipe = zc.recipe.egg
interpreter = python
eggs = zope.component
Ora lanciamo il comando buildout disponibile dentro alla cartella mybuildout/bin senza argomenti. Questo crea un
nuovo interprete Python dentro alla cartella mybuildout/bin:
$ ./bin/buildout
$ ./bin/python
Questo comando farà apparire un prompt Python che può essere utilizzato per eseguire il codice di questo libro.
2.3.2 Un esempio
Introduzione
Consideriamo come esempio un’applicazione commerciale per la registrazione degli ospiti di un hotel. Python può implementare questa applicazione in vari modi. Inizieremo dando una breve occhiata ad una possibile implementazione
procedurale, e poi ci sposteremo verso un semplice approccio orientato agli oggetti. Mentre esamineremo l’approccio orientato agli oggetti, vedremo come potremo trarre beneficio dai pattern di design classici, adapter e interface.
Questo ci porterà nel mondo della Zope Component Architecture.
Approccio procedurale
In qualsiasi applicazione commerciale, una delle parti principali è la conservazione dei dati. Per semplicità, in questo
esempio utilizzeremo un dizionario Python come sistema di storage. Creeremo degli id univoci per il dizionario e il
valore associato ad ogni chiave sarà a sua volta un dizionario con i dettagli della prenotazione.
170
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-174-320.jpg)
![Documentazione di Plone, Release 4
>>> bookings_db = {} #key: unique Id, value: details in a dictionary
Un’implementazione minimale richiede una funzione che verifichi i dettagli della prenotazione e una funzione di
supporto che fornisca gli id univoci per le chiavi del dizionario di storage.
Possiamo generare un id univoco in questo modo:
>>> def get_next_id():
...
db_keys = bookings_db.keys()
...
if db_keys == []:
...
next_id = 1
...
else:
...
next_id = max(db_keys) + 1
...
return next_id
Come si può notare, l’implementazione della funzione get_next_id è molto semplice. La funzione prende una lista di
chiavi e controlla una lista vuota. Se la lista è vuota questa è la nostra prima prenotazione, quindi restituiamo 1. Se la
lista non è vuota, aggiungiamo 1 al valore massimo della lista e lo restituiamo.
Ora utilizzeremo la funzione sopra per inserire degli elementi nel dizionario bookings_db:
>>> def book_room(name, place):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: name,
...
’room’: place
...
}
Un’applicazione per la gestione delle prenotazioni di un hotel ha bisogno di dati supplementari:
• numero di telefono
• opzioni della camera
• metodo di pagamento
• ...
e ha bisogno di codice per la gestione dei dati:
• cancellare una prenotazione
• aggiornare una prenotazione
• pagare una stanza
• rendere i dati persistenti
• assicurare la sicurezza dei dati
• ...
Se dovessimo continuare con l’esempio procedurale, dovremmo creare molte funzioni e dovremmo passare i dati
avanti e indietro tra di loro. Man mano che i requisiti cambiano o aumentano, il codice diventa sempre più difficile da
manutenere e i bug diventano più difficili da correggere.
Possiamo terminare qui la nostra discussione sull’approccio procedurale poichè sarà molto più facile fornire la
persistenza dei dati, la flessibilità di design e la testabilità del codice utilizzando gli oggetti.
Approccio orientato agli oggetti
La nostra discussione sul design orientato agli oggetti ci porta a introdurre la classe. La classe serve ad incapsulare i
dati e il codice per gestirli.
2.3. La guida completa alla Zope Component Architecture
171](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-175-320.jpg)
![Documentazione di Plone, Release 4
La classe principale sarà il FrontDesk. La classe FrontDesk o verso cui delegherà la gestione, saprà come gestire i
dati dell’hotel. Andremo a creare delle istanze di FrontDesk per applicare questa conoscenza al mestiere di gestire un
hotel.
L’esperienza ha mostrato che incapsulare il codice e i dati attraverso gli oggetti porta ad un design più facile da
comprendere,testare e modificare.
Vediamo i dettagli dell’implementazione di una classe FrontDesk:
>>> class FrontDesk(object):
...
...
def book_room(self, name, place):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: name,
...
’place’: place
...
}
In questa implementazione, l’oggetto frontdesk (istanza della classe FrontDesk) è in grado di gestire le prenotazioni.
Possiamo usare questa classe così:
>>> frontdesk = FrontDesk()
>>> frontdesk.book_room("Jack", "Bangalore")
Qualsiasi progetto reale sarà soggetto a cambiamenti nei requisiti. In questo caso la gestione dell’hotel ha deciso che
ogni ospite deve fornire anche un numero di telefono, quindi siamo costretti a cambiare il codice.
Possiamo raggiungere questo requisito aggiungendo un argomento al metodo book_room che verrà aggiunto al
dizionario dei valori:
>>> class FrontDesk(object):
...
...
def book_room(self, name, place, phone):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: name,
...
’place’: place,
...
’phone’: phone
...
}
Oltre a migrare i dati verso il nuovo schema, ora dobbiamo anche cambiare le chiamate a FrontDesk. Se però noi
astraiamo i dettagli dell’ospite in un oggetto e lo usiamo per la registrazione, i cambiamenti al codice vengono minimizzati. Così possiamo applicare i cambiamenti ai dettagli dell’ospite e le chiamate a FrontDesk non avranno bisogno
di cambiamenti.
Così abbiamo:
>>> class FrontDesk(object):
...
...
def book_room(self, guest):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
Dobbiamo ancora cambiare il codice per rispondere ai cambiamenti dei requisiti. Sebbene questo sia inevitabile, il
nostro obiettivo è quello di minimizzare questi cambiamenti, in modo da aumentare la manutenibilità.
172
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-176-320.jpg)
![Documentazione di Plone, Release 4
Nota: Quando si aggiunge del codice, è importante sentirsi liberi di apportare i cambiamenti senza paura di rompere
l’applicazione. Il modo per avere i riscontri richiesti immediatamente è usare i test automatizzati. Con dei test ben
scritti (e un buon sistema di controllo di versione) è possibile fare cambiamenti piccoli o grandi senza conseguenze.
Una buona fonte di informazioni sulla filosofia della programmazione è il libro Extreme Programming Explained di
Kent Beck.
Con l’introduzione dell’oggetto ospite, abbiamo risparmiato un pò di scrittura di codice e , cosa ancora più importante,
l’astrazione fornita dall’oggetto ospite ha reso il sistema più semplice e più comprensibile. Come risultato, il codice è
più facile da ri-fattorizzare e da mantenere.
Il pattern adapter
Nelle applicazioni reali, l’oggetto frontdesk dovrebbe eseguire compiti come la cancellazione e l’aggiornamento delle
prenotazioni. Nel design attuale dobbiamo passare l’oggetto ospite al frontdesk ogni volta che chiamiamo metodi
come cancel_booking e update_booking.
Possiamo evitare facilmente questo vincolo se passiamo l’oggetto ospite al metodo FrontDesk.__init__(),
rendendolo così un attributo dell’istanza:
>>> class FrontDeskNG(object):
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def book_room(self):
...
guest = self.guest
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
In effetti la soluzione che abbiamo raggiunto è un pattern molto conosciuto, l’adapter (adattatore). In generale, un
adapter contiene un oggetto adattato:
>>> class Adapter(object):
...
...
def __init__(self, adaptee):
...
self.adaptee = adaptee
Questo pattern sarà utile quando si avrà a che fare con i dettagli implementativi che dipendono da considerazioni
riguardanti:
• il cambio dei requisiti del cliente
• requisiti di persistenza dei dati (ZODB, RDBMS, XML...)
• requisiti di output (HTML, PDF, testo semplice...)
• il linguaggio di markup usato per il rendering (ReST, Markdown, Textile...)
Grazie agli adapters e al component registry (registro dei componenti), la ZCA permette di cambiare i dettagli
implementativi del codice attraverso la configurazione.
Come vedremo in questa sezione sugli adapter della ZCA, la possibilità di configurare i dettagli implementativi
fornisce utili abilità:
• l’abilità di passare da una implementazione all’altra
2.3. La guida completa alla Zope Component Architecture
173](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-177-320.jpg)
![Documentazione di Plone, Release 4
...
...
...
...
...
...
...
...
...
...
self.guest = guest
def register(self):
guest = self.guest
next_id = get_next_id()
bookings_db[next_id] = {
’name’: guest.name,
’place’: guest.place,
’phone’: guest.phone
}
Quello che abbiamo definito qui è un adapter per IDesk, che adatta gli oggetti IGuest. L’interfaccia IDesk è
implementata dalla classe FrontDeskNG. Quindi un’istanza di questa classe fornirà l’interfaccia IDesk
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
Il FrontDeskNG è solo uno dei possibili adattatori. È possibile creare anche altri adapter che permettano di gestire le
registrazioni degli ospiti diversamente.
Registration
Per utilizzare questo componente adapter, bisogna registrarlo nel component registry anche conosciuto come site
manager. Un site manager normalmente risiede in un sito. Il sito e il suo site manager saranno più importanti
quando si svilupperanno applicazioni Zope3. Per ora ci interesseremo solo del global site e del global site manager (o
component registry). Il global site manager risiede in memoria mentre un local site manager è persistente.
Per registrare il nostro componente, per prima cosa recuperiamo il global site manager:
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk, ’ng’)
Per recuperare il global site manager, bisogna chiamare la funzione getGlobalSiteManager disponibile nel
pacchetto zope.component. In effetti, il global site manager è disponibile anche come un attributo (globalSiteManager) del pacchetto zope.component. Quindi è anche possibile utilizzare direttamente l’attributo
zope.component.globalSiteManager. Per registrare l’adapter nei componenti, come si può vedere sopra, si
utilizza il metodo registerAdapter del component registry. Il primo argomento deve essere un classe/factory adapter.
Il secondo argomento è una tupla di oggetti adattati, ad esempio l’oggetto che stiamo adattando. In questo esempio,
stiamo adattando solo l’oggetto IGuest. Il terzo argomento è l’interfaccia implementata dal componente adater. Il
quarto argomento è opzionale ed è il nome di quel particolare adapter. Dato che abbiamo dato un nome a questo
adapter, questo è un named adapter. Se non viene passato alcun nome allora questo sarà automaticamente una stringa
vuota (‘’).
2.3. La guida completa alla Zope Component Architecture
179](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-183-320.jpg)
![Documentazione di Plone, Release 4
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerSubscriptionAdapter(SingleLineSummary)
>>> gsm.registerSubscriptionAdapter(AdequateLength)
In seguito possiamo utilizzare i subscriber per validare gli oggetti:
>>> from zope.component import subscribers
>>> doc = Document("AnDocument", "blah")
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’Summary should only have one line’, ’too short’]
>>> doc = Document("AnDocument", "blah" * 1000)
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’Summary should only have one line’]
>>> doc = Document("A Document", "blah")
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’too short’]
Handler
Gli handler sono delle fabbriche di subscription adapter che non restituiscono nulla. Essi infatti eseguono tutto il loro
lavoro quando vengono chiamati. Gli handler tipicamente sono utilizzati per la gestione degli eventi e sono anche
conosciuti come event subscribers o event subscription adapter.
Gli event subscriber sono diversi dagli altri subscription adapter per il fatto che il chiamante dell’event subscriber
non si aspetta di interagire con loro in nessun modo diretto. Per esempio, un generatore di eventi non si aspetta di
ricevere alcun valore di ritorno. Poiché i subscribers non hanno bisogno di fornire alcuna API ai loro chiamanti, è più
naturale definirli con delle funzioni, piuttosto che con delle classi. Per esempio, in un sistema di gestione documentale
potremmo voler registrare le date di creazione dei documenti:
>>> import datetime
>>> def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
In questo esempio, abbiamo una funzione che prende un evento e svolge qualche operazione e in effetti non restituisce
nulla. Questo è un caso speciale di subscription adapter che adatta un evento verso nulla. Tutto il lavoro è svolto
quando la “factory” dell’adapter viene chiamata. I subscriber che non restituiscono niente sono chiamati “handler” e
per registrarli ci sono delle API specifiche:
>>> from zope.interface import Interface
>>> from zope.interface import Attribute
>>> from zope.interface import implements
>>> class IDocumentCreated(Interface):
...
...
doc = Attribute("The document that was created")
2.3. La guida completa alla Zope Component Architecture
187](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-191-320.jpg)
![Documentazione di Plone, Release 4
>>> class DocumentCreated(object):
...
...
implements(IDocumentCreated)
...
...
def __init__(self, doc):
...
self.doc = doc
Dovremo anche cambiare la definizione del nostro handler:
Questo identifica l’handler come un adapter di eventi di tipo IDocumentCreated.
Andiamo a registrare l’handler:
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerHandler(documentCreated)
Ora possiamo creare un evento e utilizzare la funzione handle per chiamare gli handler registrati per l’evento:
>>> from zope.component import handle
>>> handle(DocumentCreated(doc))
>>> doc.created.__class__.__name__
’datetime’
2.3.7 Utilizzo della ZCA in Zope
La Zope Component Architecture viene utilizzata sia in Zope3 sia in Zope2. Questo capitolo tratterà l’utilizzo della
ZCA in Zope.
ZCML
Lo Zope Configuration Markup Language (ZCML) è un sistema di configurazione basato su XML per la registrazione dei componenti. Così, invece di utilizzare le API Python per la registrazione, è possibile utilizzare lo ZCML.
Sfortunatamente però l’utilizzo dello ZCML richiederà l’installazione di più pacchetti di dipendenze.
Per installare questi pacchetti lanciare:
$ easy_install "zope.component [zcml]"
Ecco come registrare un componente:
<configure xmlns="http://namespaces.zope.org/zope">
<adapter
factory=".company.EmployeeSalary"
provides=".interfaces.ISalary"
for=".interfaces.IEmployee"
/>
Gli attributi provides e for sono opzionali, a patto che siano già stati dichiarati nell’implementazione del componente:
<configure xmlns="http://namespaces.zope.org/zope">
<adapter
factory=".company.EmployeeSalary"
/>
188
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-192-320.jpg)
![Documentazione di Plone, Release 4
from interfaces import IBook
from interfaces import ICirculation
from interfaces import IDbOperation
def initialize_rdb():
from interfaces import IRelationalDatabase
from relationaldatabase import RelationalDatabase
from member import MemberRDbOperation
from catalog import BookRDbOperation
from circulation import CirculationRDbOperation
gsm = getGlobalSiteManager()
db = RelationalDatabase()
gsm.registerUtility(db, IRelationalDatabase)
gsm.registerAdapter(MemberRDbOperation,
(IMember,),
IDbOperation)
gsm.registerAdapter(BookRDbOperation,
(IBook,),
IDbOperation)
gsm.registerAdapter(CirculationRDbOperation,
(ICirculation,),
IDbOperation)
def initialize_odb():
from interfaces import IObjectDatabase
from objectdatabase import ObjectDatabase
from member import MemberODbOperation
from catalog import BookODbOperation
from circulation import CirculationODbOperation
gsm = getGlobalSiteManager()
db = ObjectDatabase()
gsm.registerUtility(db, IObjectDatabase)
gsm.registerAdapter(MemberODbOperation,
(IMember,),
IDbOperation)
gsm.registerAdapter(BookODbOperation,
(IBook,),
IDbOperation)
gsm.registerAdapter(CirculationODbOperation,
(ICirculation,),
IDbOperation)
def check_use_relational_db():
use_rdb = False
try:
arg = sys.argv[1]
if arg == ’-r’:
return True
except IndexError:
196
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-200-320.jpg)
![Documentazione di Plone, Release 4
from zope.component import adapts
from components import Member
from
from
from
from
interfaces
interfaces
interfaces
interfaces
import
import
import
import
IRelationalDatabase
IObjectDatabase
IMember
IDbOperation
class MemberRDbOperation(object):
implements(IDbOperation)
adapts(IMember)
def __init__(self, member):
self.member = member
def get(self):
db = getUtility(IRelationalDatabase)
cr = db.cursor()
number = self.member.number
if number:
cr.execute("""SELECT
id,
number,
name
FROM members
WHERE number = ?""",
(number,))
else:
cr.execute("""SELECT
id,
number,
name
FROM members""")
rst = cr.fetchall()
cr.close()
members = []
for record in rst:
id = record[’id’]
number = record[’number’]
name = record[’name’]
member = Member()
member.id = id
member.number = number
member.name = name
members.append(member)
return members
def add(self):
db = getUtility(IRelationalDatabase)
cr = db.cursor()
next_id = db.get_next_id("members")
number = self.member.number
name = self.member.name
cr.execute("""INSERT INTO members
(id, number, name)
202
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-206-320.jpg)
![Documentazione di Plone, Release 4
VALUES (?, ?, ?)""",
(next_id, number, name))
cr.close()
db.commit()
self.member.id = next_id
def update(self):
db = getUtility(IRelationalDatabase)
cr = db.cursor()
number = self.member.number
name = self.member.name
id = self.member.id
cr.execute("""UPDATE members
SET
number = ?,
name = ?
WHERE id = ?""",
(number, name, id))
cr.close()
db.commit()
def delete(self):
db = getUtility(IRelationalDatabase)
cr = db.cursor()
id = self.member.id
cr.execute("""DELETE FROM members
WHERE id = ?""",
(id,))
cr.close()
db.commit()
class MemberODbOperation(object):
implements(IDbOperation)
adapts(IMember)
def __init__(self, member):
self.member = member
def get(self):
db = getUtility(IObjectDatabase)
zcalibdb = db.container()
members = zcalibdb[’members’]
return members.values()
def add(self):
db = getUtility(IObjectDatabase)
zcalibdb = db.container()
members = zcalibdb[’members’]
number = self.member.number
if number in [x.number for x in members.values()]:
db.rollback()
raise Exception("Duplicate key")
next_id = db.get_next_id(’members’)
self.member.id = next_id
members[next_id] = self.member
db.commit()
2.3. La guida completa alla Zope Component Architecture
203](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-207-320.jpg)
![Documentazione di Plone, Release 4
def update(self):
db = getUtility(IObjectDatabase)
zcalibdb = db.container()
members = zcalibdb[’members’]
id = self.member.id
members[id] = self.member
db.commit()
def delete(self):
db = getUtility(IObjectDatabase)
zcalibdb = db.container()
members = zcalibdb[’members’]
id = self.member.id
del members[id]
db.commit()
PySQLite
ZODB
Conclusions
2.3.9 Riferimenti
adaptedBy
Questa funzione permette di trovare le interfacce adattate.
• Posizione: zope.component
• Firma: adaptedBy(object)
Esempio:
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> from zope.component import adaptedBy
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
>>> adaptedBy(FrontDeskNG)
(<InterfaceClass __builtin__.IGuest>,)
adapter
Qualsiasi tipo di oggetto può essere un adattatore, è possibile utilizzare il decoratore adapter per dichiarare che un
oggetto chiamabile adatta qualche interfaccia (o classe)
• Posizione: zope.component
204
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-208-320.jpg)
![Documentazione di Plone, Release 4
def register(self):
next_id = get_next_id()
bookings_db[next_id] = {
’name’: guest.name,
’place’: guest.place,
’phone’: guest.phone
}
...
...
...
...
...
...
...
alsoProvides
Dichiara le interfacce fornite direttamente da un oggetto. Gli argomenti dopo l’oggetto sono una o più interfacce. Le
interfacce fornite vengono aggiunte alle interfacce già dichiarate per l’oggetto.
• Posizione: zope.interface
• Firma: alsoProvides(object, *interfaces)
Esempio:
>>>
>>>
>>>
>>>
from
from
from
from
zope.interface
zope.interface
zope.interface
zope.interface
import
import
import
import
Attribute
Interface
implements
alsoProvides
>>> class IPerson(Interface):
...
...
name = Attribute("Name of person")
>>> class IStudent(Interface):
...
...
college = Attribute("Name of college")
>>> class Person(object):
...
...
implements(IDesk)
...
name = u""
jack = Person()
jack.name = "Jack"
jack.college = "New College"
alsoProvides(jack, IStudent)
>>>
>>>
>>>
>>>
Si può testare così:
>>> from zope.interface import providedBy
>>> IStudent in providedBy(jack)
True
Attribute
Con questa classe è possibile definire i normali attributi di una interfaccia.
• Posizione: zope.interface
• Firma: Attribute(name, doc=’‘)
• Vedi anche: Interface
206
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-210-320.jpg)
![Documentazione di Plone, Release 4
>>> ISmartPerson in providedBy(jack)
False
getAdapter
Recupera un adapter per un oggetto verso una specifica interfaccia. Restituisce un adapter che può adattare l’oggetto
all’interfaccia. Se non può essere trovato alcun adapter, solleva ComponentLookupError.
• Posizione: zope.interface
• Firma: getAdapter(object, interface=Interface, name=u’‘, context=None)
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> class IDesk(Interface):
...
"""A frontdesk will register object’s details"""
...
...
def register():
...
"""Register object’s details"""
...
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
>>> from zope.component import getGlobalSiteManager
212
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-216-320.jpg)
![Documentazione di Plone, Release 4
>>> gsm = getGlobalSiteManager()
>>> gsm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk, ’ng’)
>>> getAdapter(jack, IDesk, ’ng’)
<FrontDeskNG object at ...>
getAdapterInContext
Al posto di questa funzione, utilizzare l’argomento context della funzione getAdapter.
• Posizione: zope.component
• Firma: getAdapterInContext(object, interface, context)
• Vedi anche: queryAdapterInContext
Esempio:
>>> from zope.component.globalregistry import BaseGlobalComponents
>>> from zope.component import IComponentLookup
>>> sm = BaseGlobalComponents()
>>> class Context(object):
...
def __init__(self, sm):
...
self.sm = sm
...
def __conform__(self, interface):
...
if interface.isOrExtends(IComponentLookup):
...
return self.sm
>>> context = Context(sm)
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> class IDesk(Interface):
...
"""A frontdesk will register object’s details"""
...
...
def register():
...
"""Register object’s details"""
...
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
2.3. La guida completa alla Zope Component Architecture
213](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-217-320.jpg)
![Documentazione di Plone, Release 4
’phone’: guest.phone
}
...
...
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> sm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk)
>>> from zope.component import getAdapterInContext
>>> getAdapterInContext(jack, IDesk, sm)
<FrontDeskNG object at ...>
getAdapters
Cerca tutti gli adapter corrispondenti per degli oggetti e per una interfaccia fornita. Restituisce una lista di adapter che
corrispondono. Se un adapter ha un nome, viene restituito solo l’adapter più specifico.
• Posizione: zope.component
• Firma: getAdapters(objects, provided, context=None)
Esempio:
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
>>> jack = Guest("Jack", "Bangalore")
214
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-218-320.jpg)
![Documentazione di Plone, Release 4
>>> jack_frontdesk = FrontDeskNG(jack)
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerAdapter(FrontDeskNG, name=’ng’)
>>> from zope.component import getAdapters
>>> list(getAdapters((jack,), IDesk))
[(u’ng’, <FrontDeskNG object at ...>)]
getAllUtilitiesRegisteredFor
Restituisce tutte le utility registrate per un’interfaccia. Questo include anche le utility sovrascritte. Il valore di ritorno
è un iterabile di istanze di utility.
• Posizione: zope.component
• Firma: getAllUtilitiesRegisteredFor(interface)
Esempio:
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> class IGreeter(Interface):
...
def greet(name):
...
"say hello"
>>> class Greeter(object):
...
...
implements(IGreeter)
...
...
def greet(self, name):
...
print "Hello", name
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> greet = Greeter()
>>> gsm.registerUtility(greet, IGreeter)
>>> from zope.component import getAllUtilitiesRegisteredFor
>>> getAllUtilitiesRegisteredFor(IGreeter)
[<Greeter object at ...>]
getFactoriesFor
Restituisce una tupla (nome, factory) delle factory registrate che creano oggetti che implementano l’interfaccia fornita.
• Posizione: zope.component
• Firma: getFactoriesFor(interface, context=None)
Esempio:
2.3. La guida completa alla Zope Component Architecture
215](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-219-320.jpg)
![Documentazione di Plone, Release 4
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> class IDatabase(Interface):
...
...
def getConnection():
...
"""Return connection object"""
>>> class FakeDb(object):
...
...
implements(IDatabase)
...
...
def getConnection(self):
...
return "connection"
>>> from zope.component.factory import Factory
>>> factory = Factory(FakeDb, ’FakeDb’)
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> from zope.component.interfaces import IFactory
>>> gsm.registerUtility(factory, IFactory, ’fakedb’)
>>> from zope.component import getFactoriesFor
>>> list(getFactoriesFor(IDatabase))
[(u’fakedb’, <Factory for <class ’FakeDb’>>)]
getFactoryInterfaces
Trova le interfacce implementate da una factory. Trova la factory più vicina al contesto con il nome specificato e
restituisce l’interfaccia o la tupla dell’interfaccia che gli oggetti istanza creati forniranno.
• Posizione: zope.component
• Firma: getFactoryInterfaces(name, context=None)
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> class IDatabase(Interface):
...
...
def getConnection():
...
"""Return connection object"""
>>> class FakeDb(object):
...
...
implements(IDatabase)
...
...
def getConnection(self):
...
return "connection"
216
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-220-320.jpg)
![Documentazione di Plone, Release 4
>>> context = Context(sm)
>>> from zope.component import getSiteManager
>>> lsm = getSiteManager(context)
>>> lsm is sm
True
Esempio 2:
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> sm = getSiteManager()
>>> gsm is sm
True
getUtilitiesFor
Ricerca le utility registrate che forniscono un’interfaccia. Restituisce un iterabile delle coppie nome-utility.
• Posizione: zope.component
• Firma: getUtilitiesFor(interface)
Esempio:
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> class IGreeter(Interface):
...
def greet(name):
...
"say hello"
>>> class Greeter(object):
...
...
implements(IGreeter)
...
...
def greet(self, name):
...
print "Hello", name
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> greet = Greeter()
>>> gsm.registerUtility(greet, IGreeter)
>>> from zope.component import getUtilitiesFor
>>> list(getUtilitiesFor(IGreeter))
[(u’’, <Greeter object at ...>)]
getUtility
Recupera l’utility che fornisce l’interfaccia. Restituisce l’utility più vicina al contesto e che implementa una una
specifica interfaccia. Se non nè vengono trovate, viene sollevata ComponentLookupError.
• Posizione: zope.component
2.3. La guida completa alla Zope Component Architecture
219](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-223-320.jpg)
![Documentazione di Plone, Release 4
>>> class ISpecial(Interface):
...
pass
>>> class Person(object):
...
implements(IPerson)
...
name = u""
>>> from zope.interface import classImplements
>>> classImplements(Person, ISpecial)
>>> from zope.interface import implementedBy
To get a list of all interfaces implemented by that class::
>>> [x.__name__ for x in implementedBy(Person)]
[’IPerson’, ’ISpecial’]
implementer
Crea un decoratore per dichiarare le interfacce implementate da una factory. Viene restituito un oggetto chiamabile
che fa una dichiarazione di implementazione sugli oggetti che gli vengono passati.
• Posizione: zope.interface
• Firma: implementer(*interfaces)
Esempio:
>>> from zope.interface import implementer
>>> class IFoo(Interface):
...
pass
>>> class Foo(object):
...
implements(IFoo)
>>> @implementer(IFoo)
... def foocreator():
...
foo = Foo()
...
return foo
>>> list(implementedBy(foocreator))
[<InterfaceClass __builtin__.IFoo>]
implements
Dichiara le interfacce implementate dalle istanze di una classe. Questa funzione è chiamata all’interno di una definizione di una classe. Gli argomenti sono una o più interfacce. Le interfacce fornite sono aggiunte a quelle già dichiarate
in precedenza. Le dichiarazioni precedenti, incluse le dichiarazioni delle classi base, vengono preservate, a meno che
non sia stata utilizzata implementsOnly.
• Posizione: zope.interface
• Firma: implements(*interfaces)
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> from zope.interface import implements
222
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-226-320.jpg)
![Documentazione di Plone, Release 4
>>>
>>>
>>>
>>>
classImplements(Person, ISpecial)
from zope.interface import providedBy
jack = Person()
jack.name = "Jack"
Ecco come vere la lista di tutte le interfacce fornite da questo oggetto::
>>> [x.__name__ for x in providedBy(jack)]
[’IPerson’, ’ISpecial’]
queryAdapter
Cerca e restituisce un named adapter che può adattare un oggetto ad un’interfaccia. Se non può essere trovato alcun
adapter restituisce il default.
• Posizione: zope.component
• Firma: queryAdapter(object, interface=Interface, name=u’‘, default=None, context=None)
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> class IDesk(Interface):
...
"""A frontdesk will register object’s details"""
...
...
def register():
...
"""Register object’s details"""
...
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
2.3. La guida completa alla Zope Component Architecture
227](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-231-320.jpg)
![Documentazione di Plone, Release 4
...
...
...
def register():
"""Register object’s details"""
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> sm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk)
>>> from zope.component import queryAdapterInContext
>>> queryAdapterInContext(jack, IDesk, sm)
<FrontDeskNG object at ...>
queryMultiAdapter
Cerca e restituisce un multi-adapter per adattare degli oggetti a un’interfaccia. Se non può essere trovato alcun adapter,
restituisce il default. Il nome costituito dalla stringa vuota è riservato per gli adapters senza nome. I metodi per gli
unnamed adapter spesso chiamano i metodi per i named adapter con una stringa vuota come nome.
• Posizione: zope.component
• Firma: queryMultiAdapter(objects, interface=Interface, name=u’‘, default=None, context=None)
• Vedi anche: getMultiAdapter
2.3. La guida completa alla Zope Component Architecture
229](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-233-320.jpg)
![Documentazione di Plone, Release 4
next_id = get_next_id()
bookings_db[next_id] = {
’name’: guest.name,
’place’: guest.place,
’phone’: guest.phone
}
...
...
...
...
...
...
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk, ’ng’)
Si può testare così:
>>> queryAdapter(jack, IDesk, ’ng’)
<FrontDeskNG object at ...>
registeredAdapters
Restituisce un iterabile di IAdapterRegistrations. Queste registrazioni descrivono le attuali registrazioni degli adapter
per l’oggetto.
• Posizione: zope.component - IComponentRegistry
• Firma: registeredAdapters()
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> class IDesk(Interface):
...
"""A frontdesk will register object’s details"""
...
...
def register():
...
"""Register object’s details"""
...
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
232
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-236-320.jpg)
![Documentazione di Plone, Release 4
adapts(IGuest)
...
...
...
...
...
...
...
...
...
...
...
...
def __init__(self, guest):
self.guest = guest
def register(self):
next_id = get_next_id()
bookings_db[next_id] = {
’name’: guest.name,
’place’: guest.place,
’phone’: guest.phone
}
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
>>> IDesk.providedBy(jack_frontdesk)
True
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerAdapter(FrontDeskNG,
...
(IGuest,), IDesk, ’ng2’)
>>> reg_adapter = list(gsm.registeredAdapters())
>>> ’ng2’ in [x.name for x in reg_adapter]
True
registeredHandlers
Restituisce un iterabile di IHandlerRegistrations. Queste registrazioni descrivono le attuali registrazioni degli handler
per l’oggetto.
• Posizione: zope.component - IComponentRegistry
• Firma: registeredHandlers()
Esempio:
>>> import datetime
>>> def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.interface import Interface
>>> from zope.interface import Attribute
>>> from zope.interface import implements
>>> class IDocumentCreated(Interface):
2.3. La guida completa alla Zope Component Architecture
233](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-237-320.jpg)
![Documentazione di Plone, Release 4
doc = Attribute("The document that was created")
...
>>> class DocumentCreated(object):
...
implements(IDocumentCreated)
...
...
def __init__(self, doc):
...
self.doc = doc
>>> def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.component import adapter
>>> @adapter(IDocumentCreated)
... def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerHandler(documentCreated, info=’ng3’)
>>> reg_adapter = list(gsm.registeredHandlers())
>>> ’ng3’ in [x.info for x in reg_adapter]
True
>>> gsm.registerHandler(documentCreated, name=’ng4’)
Traceback (most recent call last):
...
TypeError: Named handlers are not yet supported
registeredSubscriptionAdapters
Restituisce un iterabile di ISubscriptionAdapterRegistrations. Queste registrazioni descrivono le attuali registrazioni
dei subscription adapter per l’oggetto.
• Posizione: zope.component - IComponentRegistry
• Firma: registeredSubscriptionAdapters()
Esempio:
>>> from zope.interface import Interface
>>> from zope.interface import Attribute
>>> from zope.interface import implements
>>> class IValidate(Interface):
...
def validate(ob):
...
"""Determine whether the object is valid
...
...
Return a string describing a validation problem.
...
An empty string is returned to indicate that the
...
object is valid.
...
"""
>>> class IDocument(Interface):
234
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-238-320.jpg)
![Documentazione di Plone, Release 4
summary = Attribute("Document summary")
body = Attribute("Document text")
...
...
>>> class Document(object):
...
implements(IDocument)
...
def __init__(self, summary, body):
...
self.summary, self.body = summary, body
>>> from zope.component import adapts
>>> class AdequateLength(object):
...
...
adapts(IDocument)
...
implements(IValidate)
...
...
def __init__(self, doc):
...
self.doc = doc
...
...
def validate(self):
...
if len(self.doc.body) < 1000:
...
return ’too short’
...
else:
...
return ’’
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerSubscriptionAdapter(AdequateLength, info=’ng4’)
>>> reg_adapter = list(gsm.registeredSubscriptionAdapters())
>>> ’ng4’ in [x.info for x in reg_adapter]
True
registeredUtilities
Restituisce un iterabile di IUtilityRegistrations. Queste registrazioni descrivono le attuali registrazioni delle utility per
l’oggetto.
• Posizione: zope.component - IComponentRegistry
• Firma: registeredUtilities()
Esempio:
>>> from zope.interface import Interface
>>> from zope.interface import implements
>>> class IGreeter(Interface):
...
def greet(name):
...
"say hello"
>>> class Greeter(object):
...
...
implements(IGreeter)
...
...
def greet(self, name):
...
print "Hello", name
2.3. La guida completa alla Zope Component Architecture
235](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-239-320.jpg)
![Documentazione di Plone, Release 4
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> greet = Greeter()
>>> gsm.registerUtility(greet, info=’ng5’)
>>> reg_adapter = list(gsm.registeredUtilities())
>>> ’ng5’ in [x.info for x in reg_adapter]
True
registerHandler
Questa funzione registra un handler. Un handler è un subscriber che non calcola un adapter ma svolge qualche funzione
quando viene chiamato.
• Posizione: zope.component - IComponentRegistry
• Firma: registerHandler(handler, required=None, name=u’‘, info=’‘)
• Vedi anche: unregisterHandler
Note: In the current implementation of zope.component doesn’t support name attribute.
Esempio:
>>> import datetime
>>> def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.interface import Interface
>>> from zope.interface import Attribute
>>> from zope.interface import implements
>>> class IDocumentCreated(Interface):
...
doc = Attribute("The document that was created")
>>> class DocumentCreated(object):
...
implements(IDocumentCreated)
...
...
def __init__(self, doc):
...
self.doc = doc
>>> def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.component import adapter
>>> @adapter(IDocumentCreated)
... def documentCreated(event):
...
event.doc.created = datetime.datetime.utcnow()
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerHandler(documentCreated)
236
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-240-320.jpg)
![Documentazione di Plone, Release 4
>>> class IDocument(Interface):
...
summary = Attribute("Document summary")
...
body = Attribute("Document text")
>>> class Document(object):
...
implements(IDocument)
...
def __init__(self, summary, body):
...
self.summary, self.body = summary, body
>>> from zope.component import adapts
>>> class SingleLineSummary:
...
adapts(IDocument)
...
implements(IValidate)
...
...
def __init__(self, doc):
...
self.doc = doc
...
...
def validate(self):
...
if ’n’ in self.doc.summary:
...
return ’Summary should only have one line’
...
else:
...
return ’’
>>> class AdequateLength(object):
...
adapts(IDocument)
...
implements(IValidate)
...
...
def __init__(self, doc):
...
self.doc = doc
...
...
def validate(self):
...
if len(self.doc.body) < 1000:
...
return ’too short’
...
else:
...
return ’’
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerSubscriptionAdapter(SingleLineSummary)
>>> gsm.registerSubscriptionAdapter(AdequateLength)
>>> from zope.component import subscribers
>>> doc = Document("AnDocument", "blah")
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’Summary should only have one line’, ’too short’]
>>> doc = Document("AnDocument", "blah" * 1000)
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’Summary should only have one line’]
>>> doc = Document("A Document", "blah")
2.3. La guida completa alla Zope Component Architecture
239](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-243-320.jpg)
![Documentazione di Plone, Release 4
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’too short’]
unregisterAdapter
Questa funzione serve a de-registrare una factory di adapter. Viene restituito un booleano che indica se il registro
è stato modificato o meno. La funzione restituisce False se il componente dato è None e non ci sono componenti
registrati, o se il componente dato non è None e non è registrato, altrimenti restituisce True.
• Posizione: zope.component - IComponentRegistry
• Firma: unregisterAdapter(factory=None, required=None, provided=None, name=u’‘)
• Vedi anche: registerAdapter
Esempio:
>>> from zope.interface import Attribute
>>> from zope.interface import Interface
>>> class IDesk(Interface):
...
"""A frontdesk will register object’s details"""
...
...
def register():
...
"""Register object’s details"""
...
>>> from zope.interface import implements
>>> from zope.component import adapts
>>> class FrontDeskNG(object):
...
...
implements(IDesk)
...
adapts(IGuest)
...
...
def __init__(self, guest):
...
self.guest = guest
...
...
def register(self):
...
next_id = get_next_id()
...
bookings_db[next_id] = {
...
’name’: guest.name,
...
’place’: guest.place,
...
’phone’: guest.phone
...
}
>>> class Guest(object):
...
...
implements(IGuest)
...
...
def __init__(self, name, place):
...
self.name = name
...
self.place = place
>>> jack = Guest("Jack", "Bangalore")
>>> jack_frontdesk = FrontDeskNG(jack)
240
Capitolo 2. Altri manuali](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-244-320.jpg)
![Documentazione di Plone, Release 4
...
...
object is valid.
"""
>>> class IDocument(Interface):
...
summary = Attribute("Document summary")
...
body = Attribute("Document text")
>>> class Document(object):
...
implements(IDocument)
...
def __init__(self, summary, body):
...
self.summary, self.body = summary, body
>>> from zope.component import adapts
>>> class AdequateLength(object):
...
...
adapts(IDocument)
...
implements(IValidate)
...
...
def __init__(self, doc):
...
self.doc = doc
...
...
def validate(self):
...
if len(self.doc.body) < 1000:
...
return ’too short’
...
else:
...
return ’’
>>> from zope.component import getGlobalSiteManager
>>> gsm = getGlobalSiteManager()
>>> gsm.registerSubscriptionAdapter(AdequateLength)
>>> from zope.component import subscribers
>>> doc = Document("AnDocument", "blah")
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[’too short’]
Ora de-registriamo il componente:
>>> gsm.unregisterSubscriptionAdapter(AdequateLength)
True
Dopo la de-registrazione si ha:
>>> [adapter.validate()
... for adapter in subscribers([doc], IValidate)
... if adapter.validate()]
[]
unregisterUtility
Questa funzione serve a de-registrare una utility. Viene restituito un booleano che indica se il registro è stato modificato
o meno. La funzione restituisce False se il componente dato è None e non ci sono componenti registrati, o se il
2.3. La guida completa alla Zope Component Architecture
243](https://image.slidesharecdn.com/manualeplone4-131205021352-phpapp02/85/Manuale-plone-4-247-320.jpg)
Manuale plone 4
- 1. Documentazione di Plone Release 4 La comunità Italiana di Plone 19 May 2013
- 3. Indice 1 Plone 4: Manuale utente 1.1 Introduzione . . . . . . . . . . . . 1.2 Aggiungere contenuti . . . . . . . 1.3 Gestione dei contenuti . . . . . . . 1.4 Usare TinyMCE come visual editor 1.5 Usare Kupu come visual editor . . 1.6 Collaborazione e flusso di lavoro . 1.7 Utilizzo delle collezioni . . . . . . 1.8 Gestione delle Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . 1 . 21 . 53 . 82 . 98 . 108 . 123 . 133 2 Altri manuali 139 2.1 Creare un tema con Diazo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 2.2 ZODB - un database nativo ad oggetti per Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 2.3 La guida completa alla Zope Component Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 166 3 Contributori 245 i
- 4. ii
- 5. CAPITOLO 1 Plone 4: Manuale utente Il manuale per utenti, redattori e amministratori. 1.1 Introduzione Una panoramica dei concetti di Plone 1.1.1 Panoramica Una spiegazione di Plone come content management system. Traduzione Giacomo Spettoli (27/11/2012) Impaginazione Giacomo Spettoli (27/11/2012) Revisione Maurizio Delmonte (28/04/2013) Cos’è Plone? Plone è un sistema di gestione dei contenuti (CMS) che permette di costruire un sito web. Con Plone, anche chi ha poca esperienza può contribuire alla creazione dei contenuti di un sito senza l’aiuto di un mago del computer. Inoltre Plone “gira sul Web”, quindi non c’è bisogno di installare alcun software speciale sul proprio computer. La parola contenuto vuole essere generale, in quanto è possibile pubblicare molti tipi di informazioni, tra cui: Un sito web Plone contiene diversi tipi di contenuto, compresi testi, foto e immagini. Questi possono esistere in molte forme: documenti, notizie, eventi, video, file audio e tutti i tipi di file e dati che possono essere caricati o creati su un sito web. I contenuti possono anche essere caricati dal proprio computer. In un sito Plone puoi creare delle cartelle per raccogliere i contenuti e per definire una struttura di navigazione: Ti piacciono le farfalle Ad esempio, per pubblicare un contenuto sulle farfalle, potresti creare una cartella denominata “Farfalle” e poi aggiungere del testo a una pagina Web nella cartella: Poi potresti caricare alcune foto di farfalle nella cartella: 1
- 6. Documentazione di Plone, Release 4 2 Capitolo 1. Plone 4: Manuale utente
- 7. Documentazione di Plone, Release 4 In una cartella puoi aggiungere vari tipi di contenuto, comprese delle sotto-cartelle. Dopo aver inserito alcune notizie e video nella cartella Farfalle, il contenuto potrebbe essere organizzato in questo modo, con due sottocartelle all’interno della cartella Farfalle: Cosa succede dietro le quinte Ci si potrebbe chiedere come funziona tutto questo. Un tipico sito web Plone esiste come installazione del software Plone su un server web. Il web server può essere ovunque, spesso si trova su un server di società specializzate all’interno di un “rack” di computer dedicati al compito: Il diagramma mostra i cavi che collegano i singoli server a Internet, attraverso connessioni di rete veloci. Il sito Plone è prodotto da del software e da un database installati su uno dei server. Quando digiti o clicchi sul tuo computer, i dati vengono inviati su e giù per i cavi di rete e dei canali di comunicazione di Internet per interagire con il software Plone installato sul server. Ora semplifichiamo un pò il diagramma che mostra come interagire con Plone: Puoi utilizzare il tuo browser web - Firefox, Safari, Internet Explorer, ecc - per visualizzare e modificare il tuo sito web Plone, e le modifiche vengono memorizzate dal software Plone nel suo sistema di archiviazione. Per esempio, immagina che il tuo sito web Plone sulle farfalle si trovi su mysite.com. In questo caso dovresti digitare www.mysite.com nel tuo web browser. Dopo aver premuto Invio, inizia la seguente sequenza di eventi quando il tuo browser “parla” con il server web su mysite.com: e il sito Plone risponde con: Plone legge il suo database per cercare informazioni memorizzate in mysite.com. Quindi restituisce la pagina web al tuo computer, in un codice chiamato HTML. HTML è un linguaggio per computer che descrive come una pagina web appare. Include testo, grafica, font, il colore dello sfondo, e tutto il resto. Ci sono molte risorse online che possono insegnarti i dettagli di HTML, ma uno dei vantaggi di Plone è che non c’è bisogno di sapere (molto) di HTML. 1.1. Introduzione 3
- 8. Documentazione di Plone, Release 4 4 Capitolo 1. Plone 4: Manuale utente
- 9. Documentazione di Plone, Release 4 1.1. Introduzione 5
- 10. Documentazione di Plone, Release 4 6 Capitolo 1. Plone 4: Manuale utente
- 11. Documentazione di Plone, Release 4 Questo è uno dei motivi per cui esistono Plone e altri software web simili, perchè ti permettono di concentrarti sui tuoi contenuti, come testo e grafica delle farfalle, invece di imparare un nuovo linguaggio del computer. Ma torniamo alla nostra panoramica. Il tuo browser “renderizza” (traduce) questo HTML, e viene visualizzata la seguente pagina web: Mentre stai guardando la pagina web della tua farfalla, puoi decidere di cambiare o aggiungere nuovo testo. È inoltre possibile caricare foto, documenti, ecc., in qualsiasi momento: Dopo aver effettuato le modifiche e premuto su “salva modifiche”, la nuova versione della pagina web sarà immediatamente disponibile per chiunque navighi sul tuo sito: 1.1.2 Design Grafico dei Siti Web Plone Plone permette agli amministratori e ai designer dei siti web di creare design unici. Ecco una panoramica del layout Plone, e alcuni esempi di design. Traduzione Federica D’Elia (27/11/2012) Impaginazione Federica D’Elia (27/11/2012) 1.1. Introduzione 7
- 12. Documentazione di Plone, Release 4 8 Capitolo 1. Plone 4: Manuale utente
- 13. Documentazione di Plone, Release 4 Revisione Maurizio Delmonte (28/04/2013) Come dovrebbe apparire un sito web Plone? Per anni c’è stato un design coerente per l’aspetto predefinito di Plone. Il design predefinito appare generalmente così: Il tuo sito web Plone potrebbe avere un design radicalmente diverso da questo, ma dovresti essere in grado di trovare elementi comuni, come il link al log-in e un pannello o menu di navigazione. Nel design di default, il menu di navigazione si trova nella zona a sinistra, e di solito appare come un elenco indentato delle cartelle del sito. Ci può anche essere un insieme di schede nella striscia Log In, Location Information in testata. Possiamo fare una distinzione tra il design e la funzionalità di un sito web. Per quanto riguarda i contenuti, concentrati sulla funzionalità e non preoccuparti tanto dell’aspetto e del layout del sito web. Un punto di forza del sistema di gestione dei contenuti Plone è che un sito web può essere radicalmente riprogettato con un nuovo look, senza incidere sul contenuto sottostante e sulle funzionalità. Il menu di navigazione potrebbe essere spostato da sinistra a destra, ma funzionerebbe lo stesso. L’area di destra potrebbe essere cancellata se le funzionalità che normalmente contiene non sono necessarie. Le aree sinistra, centrale e destra, come illustrato sopra e sotto, potrebbero essere spostate in alto, al 1.1. Introduzione 9
- 14. Documentazione di Plone, Release 4 centro e in basso, ma continuerebbe comunque a essere un sito web Plone. Useremo il design del layout di default di Plone come esempio di tipica divisione dello schermo: Potrebbe essere necessario adattare queste parti, se servono per il design del tuo sito web Plone. Ti potresti imbattere in diversi termini usati per descrivere le varie parti dello schermo, come ad esempio “slot” sinistro e destro, per le colonne di sinistra e destra, “portlet”, o “viewlet”, per zone o box specifici, e molti altri termini. Per esempio, selezioniamo tre siti web dalla lista di siti web Plone per fare un confronto: Questo è il sito web per Akamai, un fornitore leader di strumenti web online e acceleration technology. L’area di intestazione ha un semplice menu testuale per cinque aree di contenuto principali disposte orizzontalmente nella parte inferiore dell’area di intestazione. A destra, l’intestazione contiene un altro menù orizzontale e una casella di ricerca. La parte inferiore dell’area di intestazione conterrebbe dati di accesso, per l’uso da parte dei manutentori del sito. La grafica principale in alto a sinistra è una zona di messa a fuoco per la grafica accattivante e gli argomenti attuali. C’è un’area principale al centro sinistra dove si trova il testo più importante. La colonna di destra contiene una serie di “portlet”. Il piè di pagina contiene un menu orizzontale, ripetendo le scelte di menu nell’intestazione, per comodità. C’è una colonna più a destra che contiene le impostazioni di zoom. Questo è il sito web per Discover Magazine. L’area di intestazione contiene un menu orizzontale di grandi dimensioni, il “menu principale”, se si vuole chiamarlo così, un menu orizzontale più piccolo in alto a destra, e una casella di ricerca. Questo sito è ricco di “portlet” testuali che coprono molte aree tematiche, divise in tre colonne, sinistra, centro, e destra. La parte superiore della colonna centrale contiene una zona focus con un video. Ci sono grandi box interattivi in diversi punti della pagina. Il piè di pagina contiene le informazioni di identificazione di base del sito e un link al “chi siamo”. Per un grande sito web come Discover, i manutentori del sito effettuano il log-in per accedere a funzioni di editing personalizzate, e c’è molta automazione nei flussi informativi - Plone utilizza Zope, un sofisticato sistema di archiviazione, e Python, un celebre linguaggio di programmazione, che facilita un intelligente “collegamento” del flusso di testo e grafica nel sito web. L’ultimo dei tre siti da esaminare è il sito web per lo Smeal College of Business della Penn State University. L’intestazione contiene un logo, un menu orizzontale per le aree tematiche principali, e una casella di ricerca a destra. C’è un menu principale per questo sito a sinistra, il che è più tradizionale per un sito web Plone. Una vasta area grafica contiene un’animazione “rolling focus”. C’è un altro piccolo focus grafico nella colonna di sinistra. Tre colonne testuali completano il design, al di sopra dell’identificazione di base a piè di pagina. I manutentori di questo sito accedono 10 Capitolo 1. Plone 4: Manuale utente
- 15. Documentazione di Plone, Release 4 1.1. Introduzione 11
- 16. Documentazione di Plone, Release 4 12 Capitolo 1. Plone 4: Manuale utente
- 17. Documentazione di Plone, Release 4 1.1. Introduzione 13
- 18. Documentazione di Plone, Release 4 per mezzo di una pagina di log-in personalizzata, con il log-in e le informazioni utente che appaiono lungo la parte inferiore dell’area più in alto in testata. Allora, come dovrebbe apparire un sito web Plone? Tradizionalmente, l’aspetto out-of-the-box è simile a quello mostrato nella parte superiore di questa pagina, con intestazione, menu, colonne, e un piè di pagina. Questi tre siti illustrano come i designer tipicamente combinano le aree di interesse, i menu verticali e orizzontali, “portlet” e contenuti testuali, di solito disposti in diverse colonne. La struttura di base della pagina è generata da Plone, Zope e Python, ma il “tema” o “skin” di design può essere fatto risultare in qualunque modo il designer preferisca. 1.1.3 Account e Ruoli di un utente Plone In questo capitolo vedremo le basi di utilizzo di un account utente su un sito Plone, la distinzione fra navigazione anonima e quella autenticata e una descrizione dei ruoli degli utenti. Traduzione Giacomo Spettoli (27/11/2012) Impaginazione Giacomo Spettoli (27/11/2012) Revisione Maurizio Delmonte (29/04/2013) I siti Plone possono essere di molti tipi, dal sito personale con un solo utente ai portali di comunità ed organizzazioni con centinaia di utenti. Ogni persona che vuole aggiungere dei contenuti al sito deve avere un proprio account, definito da un nome utente e una password. Alcuni siti Plone consentono di auto-iscriversi visitando il collegamento “Accedi” e compilando un form con le proprie informazioni di base. In altri siti invece gli account utente vengono creati solo dagli amministratori del sito, nel qual caso le persone normalmente ricevono un messaggio di posta elettronica con i dettagli del loro nuovo account. In qualsiasi modo sia stato creato, un account utente Plone permette sempre ad una persona di autenticarsi inserendo il proprio username e password. Le password sono case-sensitive, cioè la stessa lettera viene considerata diversa se scritta in maiuscolo o in minuscolo. Ad esempio, se la password è xcFGt6v, l’utente deve scrivere esattamente questa password per potersi autenticare. Le password con una buona variabilità di caratteri sono preferibili a parole troppo semplici come “cane” o “giallo”, poichè sono più difficili da indovinare e quindi sono più sicure. Differenze tra navigazione anonima e autenticata La distinzione tra navigazione anonima e navigazione autenticata è molto importante: Navigazione anonima La navigazione anonima identifica la normale esperienza di un utente che naviga un sito web. Si digita l’indirizzo web di un sito nel proprio browser e si visualizza la pagina, si guardano video e immagini, ma non è necessario autenticarsi. Ecco perchè questa viene chiamata navigazione anonima: chiunque è anonimo prima dell’autenticazione. Da notare che la presenza del link Fatti riconoscere (n.d.t. “Log in” in Inglese) nell’angolo in alto a destra dell’immagine qui sotto. Se c’è un link “Fatti riconoscere” sulla pagina, significa che non hai effettuato l’accesso e stai visitando il sito come utente anonimo: Navigazione autenticata Se hai utilizzato il sito di una banca, o qualsiasi altro sito che preveda l’uso di un account, allora hai già avuto esperienza di navigazione utenticata. Il sito di una banca ad esempio ti permette di vedere le informazioni del tuo account, di riempire dei form, di trasferire dei fondi e altri tipi di operazioni, ma tutto questo solo dopo aver effettuato l’accesso. Un sito Plone non è molto differente, ad eccezione del fatto che si possono fare cose più complesse. Dai un’occhiata all’immagine qui sotto, catturata dopo che un utente “Mario Rossi” ha effettuato l’accesso. Vicino all’angolo in alto a destra, puoi vedere il link con il nome di Mario Rossi e un link di uscita. Un’altra differenza 14 Capitolo 1. Plone 4: Manuale utente
- 19. Documentazione di Plone, Release 4 importante che si nota quando si è autenticati è che nell’area principale al centro c’è una barra verde con dei tab (o schede). Questa specie di striscia di testa è presente quando un utente ha i permessi per modificare l’area del sito che sta visitando. I tab nella striscia verde potrebbero variare, ma avranno sempre questo aspetto e questo caratteristico colore. Nella seguente immagine, l’utente Mario Rossi si è autenticato in un nuovo sito Plone: Ruoli utente In un sito Plone è molto importante la distinzione dei diversi ruoli degli utenti. Per illustrare il caso più semplice, consideriamo due ruoli utente: collaboratore e manager. Vediamo i diversi permessi o “poteri” di questi due ruoli: Collaboratore • ha un account utente, quindi può autenticarsi; • può aggiungere contenuti, ma solo in aree specifiche, e non può modificare niente al di fuori di queste aree; spesso agli utenti viene assegnata un’area “home” da utilizzare come uno spazio personale dove possono aggiungere contenuti; • non può pubblicare un contenuto per renderlo visibile nella navigazione anonima, nemmeno nel caso dei contenuti che ha creato direttamente; un utente con il ruolo di manager dovrà approvare il contenuto per la pubblicazione. Manager • ha un account utente, quindi può autenticarsi; • può aggiungere contenuti ovunque e ha il potere di modificare qualunque cosa; • può pubblicare qualsiasi contenuto. 1.1. Introduzione 15
- 20. Documentazione di Plone, Release 4 Quando ottieni il tuo nuovo account su un sito Plone, ti dovrebbero fornire tutte le informazioni che indicano dove hai il diritto di aggiungere contenuti. Dopo aver effettuato l’accesso, se vai in una cartella in cui hai i permessi adeguati, vedrai la striscia di intestazione con il tipico colore verde e le schede Contenuti, Visualizza, Modifica, Regole, e Condivisione: Potrai navigare per scoprire di persona le differenze tra questi tab, ma ecco qualche indicazione per aiutarti a cominciare: • Contenuti - mostra la lista dei contenuti in una cartella; • Visualizza - mostra come un utente anonimo vede il contenuto corrente; • Modifica - mostra un pannello per modificare il contenuto; • Condivisione - mostra un pannello per assegnare ad altri utenti i permessi per vedere e modificare il contenuto. Puoi inoltre vedere i menu nella parte finale della barra verde, Vista, Aggiungi... e Stato: Esplora anche questi menu. Ecco qualche indicazione per partire: • Vista - mostra il menu per sciegliere il tipo di visualizzazione (vista tabellare, vista riassuntiva, etc..); 16 Capitolo 1. Plone 4: Manuale utente
- 21. Documentazione di Plone, Release 4 • Aggiungi... - mostra il menu per aggiungere nuovi contenuti (immagini, pagine, cartelle, etc...); • Stato - mostra il menu per modificare lo stato di pubblicazione (privato, bozza, pubblicato, etc..). Questi menu e tab sono il modo principale per interagire con Plone. Ti saranno molto familiari quando imparerai di più su come gestire un sito Plone. 1.1.4 Autenticazione Cosa aspettarsi quando ci si autentica in un sito Plone Traduzione Massimo Azzolini (27/11/2012) Impaginazione Massimo Azzolini (27/11/2012) Revisione Maurizio Delmonte (01/05/2013) Quando visiti un sito Plone come anonimo, oppure ti viene dato un indirizzo web per manutenzione del sito, potrai vedere un bottone “Fatti riconoscere” in alto a destra come questo: Una volta cliccato il link Fatti riconoscere, vedrai un pannello di autenticazione dove inserire il tuo nome utente e la tua password: Dopo l’autenticazione ad un sito web Plone, potrai vedere il tuo nome, solitamente in alto nell’angolo a destra del tuo schermo. Puoi cliccare sul tuo nome per effettuare alcune azioni relative al tuo utente, come spiegato nelle sezioni successive. Da Plone 4 in poi, tu (o l’amministratore del sito) puoi permettere agli utenti di utilizzare il loro indirizzo di posta elettronica come nome utente per effettuare l’autenticazione. Questa funzionalità può essere attivata nelle impostazioni di sicurezza nel pannello di controllo. L’effetto è tale per cui: • nel modulo di registrazione non viene richiesto uno specifico nome utente • nel modulo di autenticazione viene chiesto all’utente di inserire l’email. Vedi E-mail address based login in the Upgrade Guide per maggiori informazioni su questa funzionalità. 1.1. Introduzione 17
- 22. Documentazione di Plone, Release 4 1.1.5 Impostare il tuo profilo Traduzione Massimo Azzolini (27/11/2012) Impaginazione Massimo Azzolini (27/11/2012) Revisione Maurizio Delmonte (01/05/2013) Una volta autenticato in un sito web Plone, puoi cambiare il tuo profilo personale indicando informazioni circa la tua identità e scegliere le impostazioni del sito web. Il tuo nome completo viene mostrato nell’angolo in alto a destra dello schermo. Clicca sul tuo nome per aprire il menù a discesa, quindi clicca il link Dashboard per entrare nella tua area personale: Vedrai la dashboard (o scrivania personale): La prima volta che ti autentichi, la dashboard sarà vuota come indica il messaggio di Info. Le portlet sono specifiche “viste” di vari tipi di contenuto. Puoi scegliere quali vedere nella tua dashboard cliccando sul tab modifica, ma ci arriveremo in un secondo. Prima di tutto, diamo un’occhiata al link Preferenze personali, nel menù di cui parlavamo prima, che ti porterà alla modifica del tuo profilo: I campi disponibili sono: • Nome e cognome - Indica il tuo nome completo. • Indirizzo e-mail - OBBLIGATORIO - Puoi ricevere email dall’amministratore del sito web, o da un forum, se installato, ecc. Quando un campo è obbligatorio, un piccolo quadrato rosso è presente a fianco del nome del campo. • Località - Questo è il nome della tua città, stato, provincia o qualsiasi altra informazione vorrai fornire. • Selezione della lingua - Plone eccelle nell’offire un supporto multilingua. • Biografia - Inserisci una breve descrizione di te stesso in questo campo, un paragrafo o poco più. 18 Capitolo 1. Plone 4: Manuale utente
- 23. Documentazione di Plone, Release 4 1.1. Introduzione 19
- 24. Documentazione di Plone, Release 4 • Pagina personale - Se hai un tuo web site personale o, per esempio, un’area dove condividi foto, se vuoi puoi inserire qui l’indirizzo web. In questo modo altre persone potranno trovare più informazioni su di te. • Editor - Puoi scegliere di utilizzare TinyMCE o Kupu, che ti permettono di modificare le pagine web con una interfaccia grafica oppure una normale area di testo, che è adatta se sei abituato a scrivere pagine web in HTML (il “codice” base delle pagine web). L’impostazione di default per i siti appena creati è di utilizzare TinyMCE, e, in questo manuale, si assume che sia questa l’impostazione. • Abilita la modifica con l’editor esterno - Questa impostazione abilita e disabilita l’uso di un editor “esterno”, se questo è stato impostato dall’amministratore del sito web. L’uso di un editor esterno è principalmente inteso per web designer e programmatori che modificano il codice sorgente, ma può essere utile per la creazione di pagine quando si usa un linguaggio di markup specializzato. (Non ti preoccupare di questa impostazione se il tuo amministratore non te ne ha parlato esplicitamente). • Ritratto - Il tuo ritratto apparirà come una piccola immagine, quindi è consigliata una foto del viso o del busto. Puoi cambiare le tue preferenze ogni volta che vuoi. 1.1.6 La tua Dashboard Ogni utente Plone ha una sua “dashboard” da personalizzare. Traduzione Massimo Azzolini (27/11/20129) Impaginazione Massimo Azzolini (27/11/2012) Revisione Maurizio Delmonte (01/05/2013) Plone ha diversi “viste” predefinite per le notizie, gli eventi, i documenti modificati recentemente, ecc. Queste liste sono raggruppate in aree rettangolari chiamate portlet. Pensa ad una portlet come ad una finestra su un dato tipo di contenuti. Per esempio, la portlet “notizie” offre una vista delle notizie pubblicate recentemente. Tu controlli quali portlet vedi nella tua dashboard e dove sono disposte. Il seguente screenshot mostra cosa vedrebbe l’utente Mario Rossi una volta che si fosse autenticato e che avesse cliccato sul suo nome, posto in alto a destra, per andare alla sua area personale: La dashboard appare vuota per un nuovo utente. Un click sul tab di modifica per la dashboard mostrerà che ci sono portlet già assegnate alla dashboard – la dashboard mostrata sopra è vuota perchè non ci sono contenuti disponibili da presentare nelle portlet di questo nuovo sito web. Ecco le portlet di default: Vedi le portlet Notizie ed Eventi nella colonna più a sinistra, i Contenuti recenti nella seconda colonna e l’Elenco di revisione nella colonna di destra. La terza colonna non ha portlet assegnate. L’account di un nuovo utente, in un sito web Plone base, avrà una dashboard come quella mostrata, ma per un sito web che è stato personalizzato con funzionalità aggiuntive potrebbero esserci più portlet tra cui scegliere e la dashboard potrebbe partire con diverse portlet già posizionate nelle colonne. Per esempio, potrebbero esserci portlet per “il meteo”, “quotazioni di borsa”, “frase del giorno”, ecc. a seconda di cosa è stato installato sul sito web (queste opzioni richiederebbero software personalizzato). L’utente può personalizzare le portlet che vuole vedere e la loro posizione tra le quattro colonne. 20 Capitolo 1. Plone 4: Manuale utente
- 25. Documentazione di Plone, Release 4 Quindi, per l’account Plone tipico, la dashboard parte con le portlet mostrate sopra che verrebbero popolate con le news, gli eventi e gli altri contenuti creati nel sito web. 1.2 Aggiungere contenuti Come aggiungere contenuti base ai siti web Plone 1.2.1 Aggiungere nuovi contenuti Una panoramica generale su come aggiungere nuovi contenuti in Plone e definizione dei tipi di contenuto standard. Traduzione Alex Sani (27/11/2012) Impaginazione Alex Sani (27/11/2012) Revisione Giacomo Spettoli (19/05/2013) Per aggiungere nuovi contenuti si utilizza il menu a discesa Aggiungi...: In Plone, i contenuti vengono aggiunti localmente quindi devi navigare fino alla sezione dove desideri aggiungere il contenuto prima di usare la voce del menu Aggiungi.... E’ possibile ovviamente tagliare, copiare e incollare contenuti da una sezione ad un altra se necessario. Tipi di contenuti In Plone, hai a disposizione un certo numero di Tipi di contenuto che corrispondono ai diversi tipi di contenuto che puoi pubblicare. Ad esempio, per caricare un’immagine devi utilizzare il tipo di contenuto Immagine. Di seguito la lista dei tipi di contenuti disponibili nell’ordine in cui appaiono ed una breve descrizione: Collezione Le Collezioni sono utilizzate per raggruppare e visualizzare contenuti in base a dei criteri configurabili. Il funzionamento delle Collezioni è molto simile a quello delle query in un normale database. Evento Un Evento è un tipo di pagina speciale specifico per la pubblicazione di un evento (ad esempio una raccolta fondi, un barbecue, etc). Questo tipo di contenuto ha una funzione che permette ai visitatori del sito di aggiungere l’evento al proprio calendario personale utilizzando gli standard iCal e vCal. Questi standard sono compatibili con: Google Calendar, Outlook, Sunbird e altri. Per aggiungere un singolo evento al tuo calendario personale, fai click sui link vCal o iCal accanto al testo “Aggiungi l’evento al calendario” nella pagina principale dell’Evento. A partire da Plone 3.3 è anche possibile scaricare tutti gli Eventi di una cartella in una sola volta (al momento è disponibile solo in formato iCal). Per scaricare il file iCal, appendi @@ics_view alla fine dell’URL della cartella che contiene gli eventi. Ad esempio, se si desidera ottenere tutti gli eventi della cartella eventi posizionata nella 1.2. Aggiungere contenuti 21
- 26. Documentazione di Plone, Release 4 Figura 1.1: events-summary-chart.jpg 22 Capitolo 1. Plone 4: Manuale utente
- 27. Documentazione di Plone, Release 4 radice del tuo sito, vai all’ indirizzo http://tuodominio.tld/events/@@ics_view. In un futuro rilascio di Plone, è in programma l’inserimento di questo indirizzo direttamente nell’interfaccia utente. File Un File in Plone è un file binario caricabile sul sito con l’intento di farlo scaricare dai visitatori. Gli esempi più comuni di file sono PDF, Documenti di testo e fogli di calcolo. Cartella Le Cartelle in Plone funzionano come le cartelle del tuo computer. Puoi utilizzare le cartelle per organizzare i contenuti e per dare al tuo sito Plone una struttura di navigazione. Immagine Il tipo di contenuto Immagine è utilizzato per caricare file di immagini (JPG, GIF, PNG) in modo tale che tu possa inserirli all’interno di pagine o di contenuti simili. Collegamento Indicato anche come ‘Oggetto Link’, non è da confondere con i collegamenti che vengono creati tramite TinyMCE o Kupu, gli editor visuali per le pagine di Plone. Il tipo di contenuto Collegamento è spesso usato per includere un collegamento ad un sito web esterno nell’albero di navigazione o per altri usi specifici. Notizia Questo tipo di contenuto è molto simile agli Eventi, anche se una Notizia si utilizza appositamente per la pubblicazione di notizie. È inoltre possibile allegare un’immagine ad una Notizia, la miniatura apparirà nella vista riassuntiva della cartella accanto alla descrizione della stessa. Pagina Una Pagina in Plone è uno dei tipi di contenuto più semplici disponibili. Utilizza questo oggetto per scrivere la maggior parte delle pagine web del tuo sito Plone. Nota: a seconda di quali prodotti aggiuntivi hai installato, potresti vedere più opzioni sotto la voce Aggiungi... del tuo menu. Per informazioni su questi tipi di contenuto, fai riferimento alla documentazione dei vari prodotti installati. Titolo Quasi tutti i tipi di contenuto in Plone hanno due campi in comune: Titolo e Descrizione. Il campo Titolo delle cartelle, delle immagini, delle pagine, etc., può contenere tutto quello che vuoi – puoi usare qualsiasi carattere della tastiera, inclusi gli spazi. I Titoli vanno a comporre l’indirizzo web dei contenuti creati. Gli indirizzi web, noti come URLs, sono quello che digiti in un browser per passare in una specifica posizione di un sito (o il percorso del link selezionato), come ad esempio: www.mysite.com/about/personnel/sally/bio o www.mysite.com/images/butterflies/skippers/long-tailed-skippers Gli indirizzi web, al contrario dei titoli, sono soggetti a restrizioni. Alcuni caratteri della tastiera non sono consentiti come, ad esempio, gli spazi. Plone fa un buon lavoro nel mantenere gli indirizzi web molto simili ai Titoli forniti, convertendoli in lettere minuscole, sostituendo gli spazi con i trattini e sostituendo altri segni di punteggiatura. In Plone l’indirizzo web di un certo elemento è denominato nome breve. Quando si utilizza la funzione Rinomina, verrà visualizzato sia il nome breve sia il titolo. I campi variano a seconda del tipo di contenuto. Per esempio, il tipo di contenuto Collegamento ha il campo URL. Il tipo di contenuto File ha il campo File e così via. Descrizione La Descrizione appare nella parte superiore delle pagine, appena sotto il titolo. Sono spesso visualizzate in molte viste assegnate a Cartelle e Collezioni (come in quella Standard e in quella Sintetica). La descrizione appare anche nei risultati delle ricerche eseguite con il motore di ricerca nativo di Plone. 1.2. Aggiungere contenuti 23
- 28. Documentazione di Plone, Release 4 1.2.2 Aggiungere una Cartella Aggiungere cartelle ad un sito web Plone è il passo fondamentale per controllare l’organizzazione dei contenuti Traduzione Giampiero Lago (27/11/2012) Impaginazione Giacomo Spettoli (27/11/2012) Revisione Giacomo Spettoli (19/05/2013) I pc utilizzano una struttura gerarchica per organizzare i programmi e i files all’interno del disco rigido. In passato avrai sicuramente creato delle cartelle (o directory) sul tuo computer per organizzare i tuoi documenti. In Plone le cartelle sono utilizzate praticamente nello stesso modo, l’unica differenza è che sono create in un sito web al fine di dare una struttura al contenuto. Le cartelle si aggiungono cliccando sul menu Aggiungi. . . e selezionando Cartella: Figura 1.2: add-item-menu-folder.png Ora dovresti vedere il pannello Aggiungi Cartella: E’ necessario compilare il campo Titolo, perchè si tratta di un campo obbligatorio (come è indicato dal quadratino rosso). Il campo Descrizione è invece opzionale; potrai sempre tornare indietro al pannello di modifica se hai necessità di aggiungere una descrizione alla cartella. Le descrizioni sono utili quando un visitatore utilizza la ricerca di Plone – nei risultati saranno visualizzati sia il Titolo sia la Descrizione del contenuto. Potrete notare altri tab nella parte superiore: • Default, per inserire i campi Titolo e Descrizione, 24 Capitolo 1. Plone 4: Manuale utente
- 29. Documentazione di Plone, Release 4 • Categorizzazione, per specificare le categorie a cui appartiene la cartella (conosciute anche come keywords o tag), • Date, per settare il periodo di tempo durante il quale la cartella sarà visibile nel sito, • Proprietario, per specificare l’autore e/o i collaboratori dell’elemento in questione, • Impostazioni, per abilitare i commenti, abilitare la navigazione precedente/successivo e scegliere se visualizzare il contenuto nel menu di navigazione del sito web. Queste schede sono standard e si trovano anche su altri tipi di contenuto. Vedremo più nel dettaglio queste schede più avanti in questo manuale. Assicurati di cliccare sul bottone Salva in basso alla pagina quando hai finito di inserire le informazioni. Questo completerà il processo di creazione di una cartella Guarda un video su come aggiungere una cartella. 1.2.3 Cosa c’è in un nome Web? Ogni contenuto di un sito Plone ha un indirizzo web univoco. Plone crea gli indirizzi automaticamente, in base al Titolo che avete fornito. Data 27-11-2012 Traduzione Giampiero Lago Impaginazione Giacomo Spettoli Revisione 1.2. Aggiungere contenuti 25
- 30. Documentazione di Plone, Release 4 Il Titolo di un contenuto, incluse cartelle, immagini, pagine, etc. può essere tutto ciò che vuoi – puoi usare tutti i caratteri della tastiera, inclusi gli spazi bianchi. I titoli diventano parte dell’indirizzo web per ogni elemento che crei in Plone. Gli indirizzi Web, conosciuti anche come URL, sono quello che scrivete in un browser web per andare ad una posizione specifica in un sito web (In alternativa, come ad esempio: www.mysite.com/about/personnel/sally/bio o www.mysite.com/images/butterflies/skippers/long-tailed-skippers Al contrario dei titoli, gli indirizzi web hanno restrizioni sui caratteri consentiti, come gli spazi bianchi.Plone fa un ottimo lavoro per mantenere gli indirizzi web corretti utilizzando una struttura quasi equivalente al titolo che avete fornito, convertendo tutte le lettere in minuscolo e sostituendo i trattini agli spazi bianchi e alla punteggiatura. Per capire meglio, prendiamo ciascuno di questi due indirizzi web e dividiamoli nei vari componenti: www.mysite.com/about/personnel/sally/bio ^ website name ^ a folder named About ^ a folder named Personnel ^ a folder named Sally ^ a folder named Bio In questo caso Plone ha cambiato ogni titolo della cartella in lettere minuscole, ad esempio da Personnel a personnel. Ma non dovete preoccuparvi di questo perchè Plone gestisce l’indirizzamento web; vi basterà digitare nei titoli quello che volete. E, per il secondo esempio: www.mysite.com/images/butterflies/skippers/long-tailed-skippers ^ website name ^ a folder named Images ^ a folder named Butterflies ^ a folder named Skippers ^ a folder named Long-Tailed Skippers Questo esempio è simile al primo ed illustra come avviene la conversione in lettere minuscole del titolo di ciascuna cartella alla corrispondente parte dell’indirizzo web. Da notare il caso della cartella nominata “Long-tailed Skippers”: Plone conserva il trattino, in quanto carattere consentito, sia nel titolo che nella parte dell’indirizzo web, ma converte in un trattino, nell’indirizzo web, lo spazio bianco tra le parole Tailed e Skippers oltre che le lettere da maiuscole a minuscole. L’indirizzo web di un certo contenuto è indicato in Plone come nome breve. Quando usate la funzione Rinomina verrà visualizzato il nome breve insieme al titolo. 1.2.4 Aggiungere un’Immagine Aggiungere immagini in un sito web Plone è un compito fondamentale che può comportare un po’ di lavoro da parte del computer locale, ma è essenziale perché fotografie, mappe e grafica personalizzata sono molto 26 Capitolo 1. Plone 4: Manuale utente
- 31. Documentazione di Plone, Release 4 importanti nei siti web. Data 27-11-2012 Traduzione Giampiero Lago Impaginazione Giacomo Spettoli Revisione Preparare le immagini per il web Nota: Ricorda di utilizzare per tutte le immagini i formati di file web-standard. I formati consentiti includono: JPG, JPEG, GIF e PNG. Non usare i formati BMP e TIFF in quanto non sono pienamente supportati da tutti i web browsers. Quando vuoi caricare una immagine, utilizza il menu Aggiungi. . . (vedrai il menu Aggiungi. . . solo dopo aver effettuato l’accesso): Dopo aver cliccato per aggiungere una Immagine, vedrai il pannello Aggiungi Immagine: Ci sono i campi Titolo e Descrizione (campo inteso come “campo di immissione dati”) come per l’aggiunta di una cartella. In fondo c’è un campo per caricare un’immagine. Vediamo i tre campi di input: • Titolo - Inserisci il testo che preferisci, compresi spazi bianchi e punteggiatura (Plone gestisce automaticamente l’indirizzamento web) • Descrizione - È sempre una buona idea valorizzare questo campo che però non è obbligatorio • Immagine - Il campo immagine è un campo testo con un bottone Sfoglia. . . vicino. Non dovi scrivere niente qui; devi solo cliccare su Sfoglia e potrai navigare nel tuo computer per selezionare il file da caricare (ammesso che ricordi dove hai messo le tue immagini sul computer). 1.2. Aggiungere contenuti 27
- 32. Documentazione di Plone, Release 4 28 Capitolo 1. Plone 4: Manuale utente
- 33. Documentazione di Plone, Release 4 Per le immagini dovi selezionare dal tuo computer il file immagine e cliccare su Salva nella parte inferiore per caricare l’immagine sul sito web Plone. Dovrai aspettare qualche secondo per il completamento del caricamento (qualche minuto, se hai una connessione internet lenta). Un’anteprima dell’immagine caricata verrà visualizzata al termine del caricamento. A partire da Plone 4, le immagini e i file che vengono caricati sul sito hanno un loro ID (URL) basato sul titolo che gli è stato assegnato (invece del nome del file o immagine). Siccome il campo Titolo non è obbligatorio, se non è specificato, come nome del contenuto sarà utilizzato di default il nome del file al posto del titolo. 1.2.5 Aggiungere una Pagina Le pagine in Plone possono variare molto, ma ad ogni modo sono sempre “pagine web”. Data 27-11-2012 Traduzione Giacomo Spettoli Impaginazione Giacomo Spettoli Revisione Per aggiungere una pagina, utilizza il menu Aggiungi... dentro ad una cartella: Seleziona la voce Pagina dal menu a discesa e vedrai il pannello Aggiungi pagina: I campi Titolo e Descrizione sono i primi in alto, riempili in maniera appropriata. C’è un campo Commento alle modifiche in fondo, un normale campo di testo utile per memorizzare eventuali annotazioni che descrivano le modifiche fatte al documento. Questo è utile per le pagine sulle quali potresti dover collaborare con altri. 1.2. Aggiungere contenuti 29
- 34. Documentazione di Plone, Release 4 30 Capitolo 1. Plone 4: Manuale utente
- 35. Documentazione di Plone, Release 4 Al centro del pannello c’è il campo Testo del documento. Il software utilizzato per la composizione delle pagine è comunemente detto editor di testo visuale e nello specifico in Plone si utilizza TinyMCE. Questo permette di comporre le pagine in maniera visuale o WYSIWYG (What You See Is What You Get, quello che vedi è quello che avrai). Ad esempio quando applichi uno stile grassettato ad una parola, vedrai immediatamente il risultato del nuovo stile applicato. Le persone normalmente si trovano subito a proprio agio con l’approcio utilizzato dagli editor WYSIWYG. Vedremo in maniera più approfondita questo argomento più avanti in questo manuale. Linguaggi di markup Se preferite scrivere il testo delle pagine utilizzando i formati di markup, è possibile disabilitare l’editor di testo visual nel pannello delle preferenze personali, e rimpiazzare così TinyMCE con un campo di testo semplificato. I formati di markup disponibili in Plone sono: • Markdown • Textile • Structured Text • Restructured Text Ogniuno di questi necessita di aggiungere speciali codici per la formattazione all’interno del testo. Ad esempio, con la formattazione structured text, mettere tra doppi asterischi una parola o una frase le renderà con stile grassettato così **Questo testo sarebbe grassettato**. Vale la pena di imparare questi formati di markup per aumentare la velocità di input se si creano molte pagine o se sei appassionato di questo approcio leggermente più tecnico di inserimento del testo. Alcune persone preferiscono questi formati non solo per la velocità in sè ma anche per la fluidità di espressione. 1.2.6 Aggiungere un File File di vari tipi possono essere caricati su un sito Plone. Data 27-11-2012 Traduzione Giacomo Spettoli Impaginazione Giacomo Spettoli Revisione Per aggiungere un file, utilizza il menu Aggiungi... dentro ad una cartella: Seleziona la voce File dal menu a discesa e vedrai il pannello Aggiungi file: Fai click sul pulsante Mostra per cercare il file da caricare dal proprio computer locale. Fornisci un titolo (puoi utilizzare lo stesso nome del file se vuoi). Fornisci una descrizione. Quando fai click sul bottone Salva il file verrà caricato nella cartella. Guarda un video su come aggiungere un file. Alcuni esempi di file includono i file PDF, i documenti Word, i file di database, gli archivi zip...- praticamente qualunque cosa. I file su un sito Plone vengono trattati semplicemente come file e verranno mostrati nelle liste di contenuti delle cartelle, ma non ci sara nessuna visualizzazione speciale per loro. Appariranno con il loro nome nelle liste e sarà possibile scaricarli cliccando su di loro. 1.2. Aggiungere contenuti 31
- 36. Documentazione di Plone, Release 4 Figura 1.3: add-new-menu.png 32 Capitolo 1. Plone 4: Manuale utente
- 37. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 33
- 38. Documentazione di Plone, Release 4 1.2.7 Aggiungere un Collegamento Oltre ad inserire dei collegamenti nel testo delle pagine, i collegamenti possono essere creati anche come contenuti a se stanti. Avere collegamenti come contenuti separati ti permette ad esempio di organizzarli in cartelle, di impostando delle parole chiave su di loro per facilitarne il raggruppamento negli elenchi e nei risultati di ricerca, o di inserirli in navigazione. Per aggiungere un collegamento clicca sul menu Aggiungi...: Figura 1.4: add-new-menu.png Seleziona la voce Collegamento: Sciegliere dei buoni titoli per i collegamenti è importante perchè i titoli verranno visualizzati nelle liste dei contenuti e per una buona organizzazione all’interno di cartelle piene di contenuti. Incolla l’indirizzo web nel campo URL oppure digitalo. Qui non c’è la funzionalità di anteprima quindi è meglio incollare l’URL dalla finestra del browser su cui stai visualizzando la destinazione del collegamento in modo da essere sicuri della correttezza del collegamento. L’oggetto collegamento Un contenuto collegamento si comporterà nei seguenti modi, a seconda delle autorizzazioni di cui si dispone. • Se hai il permesso di modificare il contenuto collegamento, quando clicchi sul collegamento vieni rimandato al contenuto stesso per poterlo modificare (se così non fosse, verresti rimandato alla destinazione del collegamento e non avresti modo di modificarlo) 34 Capitolo 1. Plone 4: Manuale utente
- 39. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 35
- 40. Documentazione di Plone, Release 4 • Se non hai il permesso di modificare il collegamento, quando clicchi sul collegamento vieni rimandato direttamente alla destinazione impostata. Il comportamento in questo caso è lo stesso che si avrebbe inserendo direttamente l’indirizzo nel browser. L’oggetto collegamento in questo caso si comporta come un redirect 1.2.8 Aggiungere un Evento I siti Plone hanno un sistema integrato per la gestione e la visualizzazione di eventi in un caledario. Data 27-11-2012 Traduzione Alex Sani Impaginazione Alex Sani Revisione In una cartella, utilizza la voce del menu Aggiungi... per aggiungere un evento: Figura 1.5: add-new-menu.png Comparirà un pannello abbastanza grande Aggiungi Evento: 36 Capitolo 1. Plone 4: Manuale utente
- 41. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 37
- 42. Documentazione di Plone, Release 4 Dall’alto, si hanno i seguenti campi: • Titolo - OBBLIGATORIO • Descrizione • Luogo dell’evento • Inizio dell’evento - OBBLIGATORIO • Termine dell’evento - OBBLIGATORIO • Testo dell’evento (editor visuale) • Partecipanti • Tipo(i) di evento • URL dell’evento • Nome del contatto • Indirizzo e-mail per contatti • Telefono del contatto • Commento alle modifiche Nota che solo tre campi sono obbligatori: titolo, inizio e termine dell’evento. Anche se si tratta di una finestra abbastanza ampia, se hai fretta, ti basta inserire questi tre campi e salvare per creare un evento. Ovviamente, se hai altre informazioni, puoi inserirle. Una parte del pannello richiede una maggiore spiegazione: l’inizio e il termine dell’evento. L’anno, il mese, il giorno ed altri campi sono semplicemente menu a discesa. Spesso però non è semplice ricordarsi esattamente il giorno da inserire e si ha la necessità di consultare un calendario. C’è un comodo calendario pop-up che offre un modo alternativo per selezionare il giorno. Se clicchi una volta sull’icona del calendario accanto al selettore a discesa del giorno, : comparirà questo calendario pop-up: E’ sufficiente cliccare il giorno e questo verrà impostato. Compila i campi per i quali hai informazioni e salva, ma ricorda : IMPORTANTE:***L’evento non verrà visualizzato nel calendario principale del sito fino a quando non sarà **pubblicato***. ** |image5| Guarda il video con Plone 2 su come aggiungere un evento. 1.2.9 Aggiungere una Notizia Plone web sites have a built-in system for publishing news items. Use the Add new... menu for a folder to add a news item: You will see the Add News Item panel: 38 Capitolo 1. Plone 4: Manuale utente
- 43. Documentazione di Plone, Release 4 Figura 1.6: add-new-menu.png 1.2. Aggiungere contenuti 39
- 44. Documentazione di Plone, Release 4 40 Capitolo 1. Plone 4: Manuale utente
- 45. Documentazione di Plone, Release 4 The standard fields for title, description, and change note are in the panel, along with a visual editor area for body text and image and image caption fields. You can be as creative as you want in the body text area, and you can use the insert image (upload image) function to add as much illustration as needed. The images you upload for the news item will be added to the folder in which you are adding the news item. The Image and Image Caption fields are for adding an image to be used as a representative graphic for the news item, for posting in news item listings. The image will be automatically resized and positioned. Use the Body Text to insert an image in the actual body of the News Item. IMPORTANT: News items will not appear in the main web site news listing or news portlet until they are published.* * |image6| Watch a Plone video on adding a news item. 1.2.10 Impostazione delle proprietà di base Data 27-11-2012 Traduzione Federica D’Elia Impaginazione Federica D’Elia Revisione I riquadri corrispondenti ai tab disponibili su ogni elemento di contenuto dispongono di campi per le informazioni di base. Fornire tali dati è importante, significa fornire combustibile per il motore di Plone. Ogni elemento di contenuto, se cliccato da un utente con diritti di modifica per tale elemento, mostrerà una serie di tab nella parte superiore, per l’impostazione delle proprietà di base: Questi tab per le proprietà di base sono: • Default - mostra il form di inserimento dei dati principali per l’elemento di contenuto • Categorizzazione - mostra un pannello per la creazione e l’impostazione delle categorie (parole chiave) per l’elemento • Date - mostra la data di pubblicazione e la data di scadenza per l’elemento • Possessore - mostra un pannello per l’impostazione dei creatori, dei contributori e di tutte le informazioni sul copyright dell’elemento • Impostazioni - mostra un piccolo pannello per stabilire se l’elemento apparirà nel menu di navigazione e se sono ammessi i commenti sull’elemento I campi di inserimento in queste schede coprono le informazioni descrittive di base chiamate *metadati*. I metadati vengono a volte chiamati “dati sui dati”. Plone può utilizzare questi metadati in moltissimi modi. Ecco il pannello di Categorizzazione, mostrato per un elemento di contenuto pagina (sarebbe lo stesso per altri tipi di contenuto): Nota: I tag sono stati precedentemente chiamati Categorie in Plone 3 e Parole Chiave prima della versione 3.0. Il campo principale di inserimento del pannello serve a specificare le categorie. Per crearne di nuove basta semplicemente digitare parole o frasi, una per riga, nel box Nuovi tag. Quando si salva, i nuovi tag saranno creati nel sistema di tag per il sito web, e l’elemento di contenuto sarà archiviato sotto di esse. Se si ri-modifica questo elemento, o si modifica qualsiasi altro elemento, le nuove etichette verranno visualizzate sotto i Tag esistenti. Il campo Elementi Correlati permette di impostare i collegamenti tra gli elementi di contenuto, che verranno mostrati come link in fondo, quando un elemento di contenuto viene visualizzato. Questo è utile quando non si desidera utilizzare le categorie esplicite per connettere il contenuto. 1.2. Aggiungere contenuti 41
- 46. Documentazione di Plone, Release 4 Figura 1.7: 42 Capitolo 1. Plone 4: Manuale utente
- 47. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 43
- 48. Documentazione di Plone, Release 4 Il campo Posizione è una posizione geografica, è adatto per l’uso con sistemi di mappatura, ma adeguato per l’archiviazione dei documenti in generale. La Lingua scelta normalmente è quella di default del sito, ma su siti web multilingue, lingue diverse potrebbero essere utilizzate in un mix di contenuti. Il pannello Date ha campi per la data di pubblicazione e la data di scadenza, che si riferiscono esattamente alle date di inizio e fine per il contenuto, se si desidera impostarle: Le date di pubblicazione e di scadenza funzionano in questo modo: • Quando un elemento è oltre la sua data di scadenza, è contrassegnato “scaduto” in rosso nel suo sottotitolo quando viene visualizzato. • Un oggetto la cui data di pubblicazione è precedente alla data attuale non presenta testo aggiuntivo nel suo sottotitolo. • In entrambi i casi, l’elemento è “non pubblicato”, definizione che non deve essere confusa con uno stato del suo workflow. • Vuol dire semplicemente che l’elemento non compare negli elenchi e nelle ricerche. • Questi elenchi includono gli elenchi delle cartelle. • Tuttavia, il proprietario dell’elemento continuerà a vederlo, questo perchè è desiderabile sapere quali documenti giacenti ci sono nel nostro sito. • Il permesso che controlla tutto questo si chiama “Access inactive portal content”. • Gli elementi scaduti in una cartella sono contrassegnati come tali durante la visualizzazione folder_contents. • Non c’è un modo rapido di vedere se gli elementi in un elenco di cartelle sono non ancora pubblicati. • Quando si imposta un elemento non pubblicato come la visualizzazione predefinita per una cartella tale elemento verrà visualizzato. • L’annullamento della pubblicazione di un elemento non ha alcun effetto per gli amministratori. Essi potranno sempre vedere gli oggetti non pubblicati nei loro elenchi e nelle ricerche. • Dare un altro dei diritti degli utenti regolari (“può aggiungere”, “può modificare”, “può revisionare”) sull’elemento non lo rende meno non pubblicato per questi utenti. • Un modo pratico per un utente non amministratore per accedere a un elemento non pubblicato è direttamente attraverso il suo URL. Il pannello Possessore dispone di tre campi liberi per assegnare i creatori, i contributori, e le informazioni in merito ai diritti d’autore o alle proprietà del contenuto: 44 Capitolo 1. Plone 4: Manuale utente
- 49. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 45
- 50. Documentazione di Plone, Release 4 Il pannello Impostazioni ha campi che possono variare un po’ da tipo di contenuto a tipo di contenuto, ma in generale ci sono campi di input per stabilire se o meno l’elemento appare nella navigazione, o se sono autorizzati i commenti, e altri controlli simili: Raccomandazioni Non vi è alcun obbligo di inserire le informazioni specificate attraverso questi pannelli, ma farlo è una buona idea. Per il pannello Possessore, fornire i dati è importante per situazioni dove ci sono diversi persone coinvolte nella creazione di contenuti, soprattutto se ci sono più creatori e collaboratori che lavorano in gruppo. Non sempre è necessario compilare campi quali la data di pubblicazione e di scadenza, lingua e diritti d’autore, ma questi dati devono essere specificati al 46 Capitolo 1. Plone 4: Manuale utente
- 51. Documentazione di Plone, Release 4 1.2. Aggiungere contenuti 47
- 52. Documentazione di Plone, Release 4 momento opportuno. Un sistema di gestione dei contenuti non può che essere buono quanto la completezza dei dati che permette. Specificare le categorie richiede attenzione, ma se si prende l’abitudine, e se ci siamo impegnati a creare un insieme significativo di categorie, vi è un grande ritorno. Il ritorno avviene attraverso l’uso della ricerca e altri servizi di Plone che lavorano con la categorizzazione. Lo stesso vale per l’impostazione degli elementi correlati. Sarai in grado di mettere le mani su quello che ti serve, e di scoprire e utilizzare le relazioni all’interno del contenuto. Esposizione delle proprietà dei metadati come meta tag nel codice HTML Da Plone 4 in poi, in Configurazioni del sito, Sito, c’è un check box che esporrà le proprietà di base dei metadati Dublin Core. Selezionando questa casella si esporrà il titolo, la descrizione, ecc... e altri metadati come meta tag all’interno dell’HTML <head>. Per esempio: <meta <meta <meta <meta <meta <meta <meta <meta content="short description" name="DC.description" /> content="short description" name="description" /> content="text/html" name="DC.format" /> content="Page" name="DC.type" /> content="admin" name="DC.creator" /> content="2009-11-27 17:04:03" name="DC.date.modified" /> content="2009-11-27 17:04:02" name="DC.date.created" /> content="en" name="DC.language" /> ‘ <http://dublincore.org/>‘_Il generatore verificherà e rispetterà l’impostazione allowAnonymousViewAbout e riguarderà le proprietà Creatore, Collaboratori e Publisher. Puoi saperne di più su Dublin Core e HTML Metatags. 1.2.11 Restringere i tipi in una cartella Il menu “Aggiungi nuovo” ha la possibilità di restringere i tipi di contenuto che posono essere aggiunti alla cartella. Data 27-11-2012 Traduzione Massimo Azzolini Impaginazione Massimo Azzolini Revisione Restringere i tipi disponibili ad essere aggiunti ad una cartella è il modo più semplice per controllare la creazione di contenuti in un sito web Plone. Puoi scegliere di restringere i tipi di contenuti se il tuo sito viene gestito da numerose persone. In questo modo puoi forzare buone pratiche come ad esempio inserire solo immagini in una cartella cui hai dato nome “cartella immagini”. Prima di tutto, seleziona l’ultima opzione nel menu “aggiungi” chiamata “Restrizioni...” Ci sono tre scelte possibili per restringere tipi in una cartella: La scelta di default è di utilizzare le impostazioni della cartella in cui l’oggetto è salvato. Avere questa come default significa che se crei una cartella e restringi i tipi che possono essere aggiunti, ogni sottocartella creata automaticamente erediterà le restrizini. La seconda scelta, permettere ai tipi standard di essere aggiunti, è il modo di ritornare alla modalità iniziale: nessuna restrizione. L’ultima scelta permette di selezionare da una lista di tipi disponibili: 48 Capitolo 1. Plone 4: Manuale utente
- 53. Documentazione di Plone, Release 4 Figura 1.11: add-new-menu.png 1.2. Aggiungere contenuti 49
- 54. Documentazione di Plone, Release 4 50 Capitolo 1. Plone 4: Manuale utente
- 55. Documentazione di Plone, Release 4 I tipi elencati sotto la voce Tipi consentiti sono quelli disponibili nel sito web. Il default, come mostrato, è di permettere tutti i tipi. I tipi disponibili possono essere abilitato o disabilitati per la cartella. L’uso di tipi supplementari permette un controllo ancora più di dettaglio. Per esempio, se è si è deciso di salvare le immagini in una cartella, invece di spargerle in varie cartelle sul sito web – uno schema che in molti preferiscono – una cartella “immagini” può essere creata con i tipi disponibili impostati al solo tipo Immagine. Allo stesso modo una cartella “Eventi aziendali” potrebbe essere creata per contenere solo contenuti di tipo Evento. Se si impostassero le cose in questo modo, i creatori di contenuti sarebbero forzati a seguire questo schema restrittivo. Forse un po’ più di flessibilità è desiderabile per le immagini. Selezionando il contenuto “Immagine” nella voce tipi supplementari per la cartella “Eventi aziendali”, le immagini possono essere aggiunte, se è effettivamente necessario, utilizzando il sotto menù “Altri...” che appare quando viene attivato questo meccanismo. Alcune persone preferiscono un mix eteronegeo di contenuti sul sito web, senza restrizioni. Altri preferiscono un approccio più regolamentato, restringendo tipi secondo un dato schema organizzativo. Plone ha la flessibilità necessaria per accettare un ampio spettro di impostazioni. 1.2.12 Preparare le immagini per il web Preparare le immagini per il web è una parte essenziale per utilizzare le immagini in Plone, come in qualsiasi contesto online. Come vedrai, le dimensioni contano. Molte fotografie utlizzate dagli utenti sono scattate con una fotocamera digitale, ma possono anche essere immagini acquisite da scanner, illustrazioni grafiche realizzate con software specifici e altri tipi di immagini particolari. Prendiamo il caso di una foto di una farfalla scattata con una fotocamera digitale. Le fotografie digitali scattate con macchine fotografiche moderne sono di solito troppo grandi per essere inserite direttamente su un sito web, quindi hanno bisogno di essere ridimensionate. Un tipico design di un sito web potrebbe avere una larghezza di circa 1000 pixel. Quando una foto viene scattata con una moderna macchina fotografica, può avere diverse migliaia di pixel di larghezza e altezza, e quindi risultare di diversi megabyte di dimensione come file. Dovrai quindi utilizzare software appositi che ridimensionino l’immagine in qualcosa di meno di 1000 x 1000 pixel, molto spesso serviranno anche dimensioni più piccole. I software che si utilizzano per visualizzare o stampare le foto digitali hanno spesso questa funzionalità di ridimensionamento, in alternativa si potrebbero utilizzare software di grafica come Corel Draw, Adobe Photoshop, Irfanview, o Gimp. Il ridimensionamento di un’immagine, a volte chiamato ricampionamento, è una funzione standard che spesso si trova nei software di fotoritocco sotto la voce di menu Immagine. Come facciamo a sapere di che dimensione di larghezza in pixel abbiamo bisogno per ridimensionare la nostra immagine? Dipende. Per un “head shot”, una fotografia da inserire in una biografia, forse 200 pixel di larghezza potrebbero bastare. Per una foto di gruppo, 200 pixel risulterebbero troppo poco per consentire l’identificazione delle persone nella fotografia, quindi magari si potrebbe aver bisogno di una larghezza di almeno 400 pixel. Per una immagine di una mappa presa da scanner, forse la larghezza dovrebbe essere di 1000 pixel per permettere di visualizzare i dettagli della mappa. Dopo aver salvato l’immagine ridimensionata, diamogli un nome che indichi il nuovo formato (ad esempio, butteryflyresized-300px.jpg). Il formato del file è di solito jpg (o. jpeg). Altri formati comuni per le immagini sono png e gif. Prendi nota dove salvi le immagini sul tuo computer in modo che può trovarle facilmente quando le carichi sul tuo sito web Plone. Per riassumere: 1. Scatta la fotografia con la tua fotocamera, o trova un’immagine esistente che desideri utilizzare 2. Trasferiscila al tuo computer 3. Utilizzare software di fotoritocco sul tuo computer per ridimensionare la foto 4. Carica la fotografia sul tuo sito Plone 1.2. Aggiungere contenuti 51
- 56. Documentazione di Plone, Release 4 Figura 1.12: image_resizing.png 52 Capitolo 1. Plone 4: Manuale utente
- 57. Documentazione di Plone, Release 4 1.2.13 Aggiungere collezioni Data 27-11-2012 Traduzione Alex Sani Impaginazione Alex Sani Revisione Le collezioni (precedentemente chiamate Smart Folders) sono contenitori virtuali di liste di elementi trovati attraverso specifiche ricerche. Consultare la sezione del manuale Utilizzo delle collezioni. 1.3 Gestione dei contenuti La scheda contenuti è il posto dove gli oggetti posso essere copiati, tagliati, incollati, spostati, rinominati, etc. 1.3.1 Tagliare, Copiare e Incollare contenuti Le operazioni taglia, copia e incolla comportano lo spostamento di uno o più contenuti da una cartella ad un’altra Taglia/Incolla Spostare contenuti da una area ad un’altra in un sito web è un operazione comune. Spesso si ha necessità di questa operazione quando il posizionamento di alcuni contenuti è nella cartella sbagliata. Ad esempio, se l’autore del seguente contenuto sulle farfalle Skipper si rende conto che una farfalla Swallowtail è stata erroneamente inclusa - la cartella Eastern Tiger Swallowtail illustrato di seguito - la cartella può essere semplicemente spostata con una operazione di taglia/incolla: Nota che la cartella Eastern Tiger Swallowtail è stata selezionata, e che il pulsante Taglia sta per essere cliccato. Dopo aver fatto clic sul pulsante Taglia, lo schermo mostrerà un nuovo pulsante Incolla. La cartella Eastern Tiger Swallowtail e tutto il suo contenuto sono ora nella “memoria” del sito web. La cartella Eastern Tiger Swallowtail non scompare subito in quanto è in attesa della relativa operazione Incolla. Il pulsante Incolla viene ora evidenziato per mostrare che l’operazione taglia/incolla è in corso: Il pulsante Incolla ora è attivo. Il passo successivo è quello di selezionare la cartella di destinazione, in questo caso la cartella Swallowtails: Dopo aver cliccato ed essere entrati nella cartella Swallowtails, il pulsante Incolla continuerà a vedersi, perché l’operazione Incolla non è ancora stata completata: Per ultimo, facendo clic sul pulsante Incolla nella cartella di destinazione viene aggiunta la cartella Eastern Tiger Swallowtail nel giusto posto nella cartella Swallowtails, viene quindi tagliata dalla posizione originale, la cartella Skippers, e l’operazione di Copia/Incolla è ora completata: Il pulsante Incolla rimane attivo, perché sarebbe consentito continuare ad incollare la cartella in altri posti se si vuole. Questo potrebbe accadere in diverse situazioni, quando magari è necessario copiare una pagina, ad esempio una sorta di modello o documento standard, in diverse cartelle. Copia/Incolla Un’operazione di Copia/Incolla è identica all’operazione di Taglia/Incolla, tranne che non c’è rimozione del contenuto dalla cartella originale. Esso funziona come ci si aspetta che funzioni. 1.3. Gestione dei contenuti 53
- 58. Documentazione di Plone, Release 4 54 Capitolo 1. Plone 4: Manuale utente
- 59. Documentazione di Plone, Release 4 1.3. Gestione dei contenuti 55
- 60. Documentazione di Plone, Release 4 56 Capitolo 1. Plone 4: Manuale utente
- 61. Documentazione di Plone, Release 4 |image8| Guarda un Video riguardo Plone 2 sull’esecuzione <http://media.plone.org/LearnPlone/Copy,%20Paste,%20Cut,%20etc.swf>‘_ di queste operazioni 1.3.2 Modificare i contenuti La modifica dei contenuti in Plone funziona allo stesso modo dell’aggiunta - solitamente i pannelli per l’immissione dei dati e per la modifica dei contenuti sono gli stessi. Naturalmente, quando si modifica un elemento, l’oggetto esiste già. Fare clic sulla scheda Modifica di un contenuto per vedere il pannello di inserimento dati per quel contenuto, insieme con i valori già esistenti per quell’elemento. Vediamo un esempio molto semplice, quando si modifica o viene aggiunto qualcosa, l’aspetto è lo stesso, possiamo rivedere come si modifica una cartella. Il pannello Modifica di una cartella mostra semplicemente l’area di input per il titolo e la descrizione. Spesso la descrizione non è prevista per una cartella, quindi l’unica cosa da cambiare è il titolo Se si desidera dare una descrizione, che è una buona idea per distinguere le cartelle in un elenco, la descrizione può essere inserita solo in formato testo – non c’è alcuna possibilità di impostare lo stile di testo, come grassetto, corsivo, o altre formattazioni Ciò mantiene le descrizioni degli elementi Plone il più semplice possibile. Ecco il pannello Modifica di una cartella, in questo caso, una cartella chiamata “Butterflies”: Tutto qui. Cambiare ciò che si desidera e salvare, e il contenuto dell’elemento sarà aggiornato nel sistema Plone. Puoi modificare ripetutamente il contenuto degli elementi, proprio come puoi farlo con i file presenti sul tuo computer personale Ormai avrete apprezzato il fatto che Plone memorizza gli elementi come entità separate, simili a “file” su un computer locale, ma non c’è bisogno di pensarla necessariamente in questo modo. Plone è un CMS (sistema di gestione dei contenuti), in cui il contenuto viene fornito sotto forma di numerosi elementi separati che possono essere modificati singolarmente a piacimento. Per fare un esempio di modifica di un contenuto che è un po ‘diverso dall’aggiunta, in primo luogo, possiamo esaminare la modifica di un’immagine. La modifica di una immagine può essere fatta navigando fino a trovare la singola 1.3. Gestione dei contenuti 57
- 62. Documentazione di Plone, Release 4 58 Capitolo 1. Plone 4: Manuale utente
- 63. Documentazione di Plone, Release 4 immagine e facendo clic sul pannello Modifica. Facendo clic sul pannello Modifica, verrà visualizzato il seguente pannello Modifica immagine: Qui, un’immagine chiamata “Eastern Tiger Swallowtail Butterfly” sta per essere modificata. Puoi modificare il titolo e la descrizione, come al solito, e in questo caso potresti lasciare l’impostazione di “Mantieni l’immagine corrente”. È anche possibile modificare l’immagine stessa scegliendo “Sostituisci con la nuova immagine”. In alternativa, cliccando sul pulsante “Elimina immagine corrente” l’immagine sarà eliminata del tutto. Si noti anche sulla parte superiore la presenza del tab Trasforma, che è pertinente alle immagini, e che offre una scelta di diverse trasformazioni dell’ immagine: Quindi, la modifica di un immagine è un operazione po ‘diversa che aggiungerne una inizialmente, ma non di molto. I pannelli di modifica per gli altri tipi di contenuto sono solitamente simili ai pannelli per l’aggiunta. Modifica in linea (opzionale) La modifica in linea è disabilitata di default nelle ultime versioni di Plone (3.3 +). Può essere abilitata tramite il pannello di controllo da un Amministratore del Sito (Configurazione del sito -> Modifica -> Spuntare la checkbox Abilita modifica in linea). La normale procedura per modificare un contenuto è quello di fare clic sul pannello Modifica e utilizzare i relativi campi di input del contenuto Per i campi di testo, ad esempio Titolo, Descrizione, Testo del documento, ecc, c’è un modo più rapido per farlo, ed è chiamato modifica in linea. La modifica in linea è utilizzata durante la visualizzazione dell’elemento stesso (il pannello Visualizza è attivo). Quando il mouse passa sopra parti di testo modificabili, un piccolo box evidenzierà il testo modificabile. Nella seguente schermata, il cursore del mouse non si trova sopra di testo da modificare, in modo da far vedere il titolo della pagina ed il testo del documento come di consueto: 1.3. Gestione dei contenuti 59
- 64. Documentazione di Plone, Release 4 Ma quando il mouse viene spostato sopra il testo del documento, un box lo metterà in evidenza permettendo la modifica: Facendo clic all’interno del testo del documento dopo che il box della modifica in linea è apparso, si attiverà l’editor di testo: Cambiare o aggiungere del testo e salvare, e si torna alla normale. Questo è notevolmente più veloce ( in termini di numero di click e tempo di attesa) di fare clic sul pannello Modifica ed attivare l’intero pannello di modifica per tutta la pagina. Se il mouse viene spostato sopra il titolo, anch’esso editabile, appare un box di modifica in linea: Facendo clic sul titolo dopo che compare il box si attiva un campo di editing molto semplice con due bottoni di scelta Salva e Annulla: Cambia il titolo e salva. Il vantaggio della velocità della modifica in linea è realmente percepito per l’editing di qualcosa di semplice come ad esempio un titolo. 60 Capitolo 1. Plone 4: Manuale utente
- 65. Documentazione di Plone, Release 4 1.3. Gestione dei contenuti 61
- 66. Documentazione di Plone, Release 4 1.3.3 Folder View Folders have the Display tab which controls the several ways of showing folder contents. For most content items, if you want to change how it looks, you edit the content directly. But folders are a different animal. As containers of other items, folders can display their contents in a variety of ways. We’ll cover each of the options in this section. Consider a scenario where a butterfly enthusiast, John Smith, has logged in to his web site to work on the part devoted to Skipper butterflies. He navigates to the “Skippers” folder by clicking the top tabs of the web site, or the navigation menu, which is on the left in his default Plone web site design. When he clicks the “Skippers” folder, the standard view tab panel, or just “standard view,” for the folder is shown: The View is always how a content item would show for anonymous web site visitors. Click the View tab when you want to see what a content item looks like after you have changed something. For folders, you will see a listing of contained content items, in one of several list presentations, selected via the display pull-down menu. The default view is called standard view: And, here is summary view: And, tabular view: And, thumbnail view, which is mainly useful for photographs, but still works for normal content: Making a photo album is easy. Just add the photographs (images, or image files, the most common being .jpg files) to a folder and set the display view for the folder to thumbnail view. Thumbnail view will automatically update the display as images are added to the folder, presenting a multi-page division into sets of images, as needed, as the number of images grows. If you are uploading photographic images from a digital camera or scanner, you will most likely want to resize them on your local computer before uploading them, because they are too large. 62 Capitolo 1. Plone 4: Manuale utente
- 67. Documentazione di Plone, Release 4 Figura 1.13: folder-view-standard.png 1.3. Gestione dei contenuti 63
- 68. Documentazione di Plone, Release 4 64 Capitolo 1. Plone 4: Manuale utente
- 69. Documentazione di Plone, Release 4 1.3. Gestione dei contenuti 65
- 70. Documentazione di Plone, Release 4 Setting an Individual Content Item as the View for a Folder The basic list view functionality described above for folders fits the normal way we think of folders – as containers of items – but Plone adds a nice facility to set the view of a folder to be that of any single item contained within the folder. This takes advantage of the way the navigation system dynamically reflects the folder structure of a Plone web site as folders are created. You can set the display view for a folder to show a single page, which can be useful for showing the most recent document within a list of documents stored in the folder. Or, you can set it to a collection, which on its own is already a powerful content filter. The display view setting should be used with care, because it changes the behavior of folders, from acting as simple containers to acting as direct links to content. Instead, you can often accomplish what you want by only using collections, which will be covered later in this manual. |image10| Watch a Plone 2 video about setting the page display view. Next, we move to the Contents tab to see important functions for accessing content in a list of folder content. 1.3.4 Contenuti delle cartelle Data 27-11-2012 Traduzione Alex Sani Impaginazione Alex Sani Revisione Il tab Contenuti mostra la lista degli elementi in una cartella. E’ il posto dove eseguire semplici operazioni sugli elementi e dove eseguire azioni come copiare, tagliare, incollare, spostare, riordinare, etc. Il tab Contenuti delle cartelle è come la sezione “Gestione file” o “Risorse del Computer” dei pc con Windows e Linux ed il “Cerca” nei Mac OS X, con funzionalità simili. Cliccando il tab Contenuti, come ad esempio per la cartella “Skippers” qui sotto, verrà mostrato la scheda Contenuti: La scheda Contenuti è immediatamente riconoscibile osservando i check boxes accanto alle voci della lista. Clicca questi check boxes per selezionare più elementi e per eseguire le funzioni copia, taglia, rinomina, elimina o cambia lo stato. Plone ha una sezione di appunti dove gestisce le operazioni di copia e taglia. Se selezioni uno o più elementi e premi taglia o copia, sarà aggiunto un pulsante incolla in fondo alla scheda nella stessa riga dove si trovano gli altri pulsanti. Se a questo punto vai in un’altra cartella, vi potrai incollare l’elemento. Utilizzando la funzione taglia , gli elementi rimangono nella cartella sorgente – non scompariranno – finchè non saranno incollati da un’altra parte. Quando si Rinominano i contenuti, verrà mostrata una scheda dove inserire un nuovo valore per il nome breve (o id) dell’elemento , così come per il titolo. La differenza tra il nome breve ed il titolo diventa evidente solo quando si utilizza la funzione rinomina, perchè Plone crea automaticamente il nome breve dal titolo nella maggior parte dei siti Plone. Ma la funzione rinomina deve mostrarti sia il nome breve sia il titolo, perchè normalmente vorrai modificare entrambi per ottenere una modifica completa. Considera il seguente esempio: Se vuoi modificare il titolo in “Long-tailed Skippers,” vorrai cambiare anche il nome breve in “long-tailed-skippers.” In questo modo i due attributi saranno in ordine e corretti, così che l’URL dell’elemento, l’indirizzo web , sarà aggiornato rispetto all’elemento stesso. Nota che il nome breve non deve contenere spazi. Utilizza i trattini al posto degli spazi e, se non ce ne sono, fai una copia precisa del titolo. Inoltre, usa solo lettere minuscole per il nome breve. Guarda la pagina “What’s in a Web Name?” per una descrizione di come Plone gestisce gli indirizzi web e i nomi brevi. Il seguente video include anche la funzione rinomina: |image11| Guarda un video con Plone 2 che include la funzione rinomina di un elemento. L’operazione cancella è semplice. Clicca per selezionare uno o più elementi, in seguito premi il pulsante cancella e gli elementi saranno cancellati. 66 Capitolo 1. Plone 4: Manuale utente
- 71. Documentazione di Plone, Release 4 Figura 1.14: folder-contents.png Figura 1.15: rename-item.png 1.3. Gestione dei contenuti 67
- 72. Documentazione di Plone, Release 4 L’operazione cambia stato offre un ottimo modo per cambiare lo stato di pubblicazione delle cartelle selezionate e dei loro contenuti se hai selezionato l’opzione corrispondente. Nel seguente esempio, lo stato di pubblicazione della cartella “Long-tailed Skippers” sarà modificato. Selezionando “Includi gli elementi contenuti” il cambiamento dello stato avrà effetto anche su tutto il suo contenuto. Non dimenticare che, ad esempio, tre cartelle e tutto il loro contenuto possono essere pubblicati, nascosti, etc. in un solo colpo. Utilizza Shift-click per selezionare un intervallo di elementi. Questo è molto utile in una cartella con più di una dozzina di elementi e risulta indispensabile in cartelle con centinaia di oggetti. In aggiunta a queste operazioni, il riordinamento può essere fatto in maniera naturale con il mouse, come descritto nella sezione successiva. 1.3.5 Ordinamento elementi Il tab dei contenuti contiene una funzione veloce e precisa per l’ordinamento degli elementi di una cartella. Considera la seguente cartella, chiamata “Skippers,” che contiene informazioni sui tipi di farfalle. Spesso, quando aggiungiamo contenuti , non li inseriamo nell’ordine finale che vorremmo ottenere. L’ordine desiderato non è sempre alfabetico ma in questo esempio il risultato finale sarà questo. Sotto puoi vedere che le sottocartelle di Skipper non sono in ordine alfabetico: 68 Capitolo 1. Plone 4: Manuale utente
- 73. Documentazione di Plone, Release 4 Per muovere l’elemento più in alto chiamato “Spread-winged Skippers” in fondo alla lista, dovrai cliccare nella colonna di sinistra per l’Ordinamento (quella con il simbolo dei due punti ripetuti) e trascinare la riga nella posizione desiderata: Il trascinamento si esegue tenendo premuto il pulsante del mouse mentre sposti l’elemento. L’oggetto che stai spostando diventerà giallo e inizierà a muoversi: Quando rilascierai il pulsante del mouse, l’elemento si posizionerà in quel punto: 1.3.6 Previous - Next Links Automatic previous-next links for content items in a folder can be enabled under the Settings tab for a folder. The Settings tab is found by clicking the Edit tab for the folder. There is a toggle for enabling previous-next links for items contained in the folder: Once enabled, as content items are added to the folder, previous and next links will automatically appear as needed: Three pages have been created within the Cloudywings folder, and “Page Two” (which has no text, for this example) has been clicked. At the bottom of “Page Two” are links for “Previous: Page One” and “Next: Page Three.” This is a really useful feature! 1.3.7 Deleting Items Items may be deleted from a folder with ease. 1.3. Gestione dei contenuti 69
- 74. Documentazione di Plone, Release 4 Figura 1.16: Esempio di Ordinamento 70 Capitolo 1. Plone 4: Manuale utente
- 75. Documentazione di Plone, Release 4 1.3. Gestione dei contenuti 71
- 76. Documentazione di Plone, Release 4 72 Capitolo 1. Plone 4: Manuale utente
- 77. Documentazione di Plone, Release 4 Sometimes it is necessary to delete a content item, often to replace it with an updated version. Or, you could simply delete an item, for a variety of reasons. In the example of the swallowtail butterfly mistakenly added to the Skippers folder, instead of cutting it and pasting it somewhere, it could simply be deleted: In the example shown above, the Eastern Tiger Swallowtail folder is will be deleted after clicking on the Delete button. Entire folders may be deleted, so care must be taken with the delete operation, but this is true for computer use in general, and we all have learned to do a last minute self-check to make sure the delete operation is intended. 1.3.8 Automatic Locking and Unlocking Plone gives you a locking message that will tell you that a document was locked, by whom, and how long ago — so you won’t accidentally stomp on somebody else’s changes. When somebody clicks on the Edit tab, that item immediately becomes locked. This feature prevents two people from editing the same document at the same time, or accidentally saving edits over another users edits. In this example, George Schrubb has started editing the “Widget Installation” document. When Jane Smythe (who has permissions to edit that document as well) goes to view it, she will see the following: Once George has finished editing the document and clicks the Save button, the document is automatically unlocked and available to be edited by others (should they have the proper permissions to do so, of course). 1.3. Gestione dei contenuti 73
- 78. Documentazione di Plone, Release 4 Figura 1.17: locking01.png However, if it becomes clear to Jane that George isn’t really editing the document anymore (e.g. the locking message says that the item was locked several days ago and not just a few minutes ago) then Jane can “unlock” it and make it available for editing again. In Plone 3.3 or higher: If a user leaves the edit page without clicking Save or Cancel, the content locking will remain effective for the next ten minutes after which time, the locked content item becomes automatically unlocked. This timeout feature is important for browsers that do not execute the “on-unload” javascript action properly such as Safari. Should you desire to disable locking, go to the Plone control panel (Site Setup -> Site) and uncheck Enable locking for through-the-web edits. 1.3.9 Controllo di versione Una panoramica su come visualizzare la cronologia delle versioni di un elemento, confrontare le versioni, visualizzare in anteprima le versioni precedenti e ripristinare versioni precedenti. Creare una nuova versione Plone include una funzione per gestire le versioni. Per impostazione predefinita, i seguenti tipi di contenuti hanno il controllo di versione abilitato: • Pagina • Notizia • Eventi • Collegamento Si noti che tutti gli altri tipi di contenuto mantengono la storia del flusso del workflow associato. I tipi di contenuto posso essere configurati per avere il controllo di versione abilitato/disabilitato attraverso il pannello Configurazione del Sitote Setup sotto la voce “Tipi di contenuto”. 74 Capitolo 1. Plone 4: Manuale utente
- 79. Documentazione di Plone, Release 4 Quando modifichi un elemento, puoi utilizzare il campo commento alle modifiche in fondo; il commento alle modifiche verrà memorizzato nella cronologia delle versioni dell’elemento. Se il commento alle modifiche viene lasciato vuoto, Plone includerà una nota standard:”Revisione iniziale”. Una nuova versione viene creata ogni volta che un elemento viene salvato. Il controllo di versione tiene traccia di qualsiasi modifica effettuata: contenuti, metadata, impostazioni, etc. Visualizzazione della cronologia delle versioni Una volta salvato un oggetto, è possibile utilizzare il link Cronologia situato nella parte superiore della pagina. Semplicemente cliccalo per visualizzare la Cronologia in una finestra sovrapposta alla pagina: Figura 1.18: history-viewlet.png La versione più recente viene elencata per prima. La viewlet della Cronologia fornisce le seguenti informazioni: • Il tipo di modifica (al contenuto o al workflow) • quale utente ha fatto la modifica • in che data e ora è stata fatta la modifica Confrontare le versioni Dalla viewlet della Cronologia puoi confrontare qualsiasi versione precedente con quella corrente o qualsiasi altra versione con quella appena prima. Per confrontare qualsiasi versione precedente con quella appena prima, cliccare sul link Confronta collocato tra le due versioni nella finestra della Cronologia. Cliccando questo link, vedrai un una schermata come questa in cui è possibile vedere le differenze fra le due versioni: In questo esempio, il testo in rosso è quello che è stato cancellato e il testo in verde è quello che è stato aggiunto alla versione più recente. È possibile visualizzare le differenze tra le versioni in modalità in linea o come codice. 1.3. Gestione dei contenuti 75
- 80. Documentazione di Plone, Release 4 Figura 1.19: compare-button.png Figura 1.20: compare-versions.png Figura 1.21: Confronto versioni (Sorgente HTML) 76 Capitolo 1. Plone 4: Manuale utente
- 81. Documentazione di Plone, Release 4 È inoltre possibile confrontare qualsiasi versione precedente con la versione corrente cliccando sul link Confronta con versione attuale nella finestra della Cronologia, situato all’estrema destra di ogni versione elencata. Visualizzare e tornare alle versioni precedenti Puoi fare una anteprima di qualsiasi versione precedente di un documento cliccando il link Visualizza alla destra di ogni versione elencata. Per tornare ad una versione precedente, clicca sul pulsante Ripristina questa versione alla destra di ogni versione elencata. 1.3.10 Modalità di presentazione Plone viene fornito con la possibilità di creare semplici presentazioni di diapositiva. La Modalità di Presentazione è una funzione speciale del tipo di contenuto Pagina. Puoi abilitare la Modalità di Presentazione modificando la pagina, entrando nella linguetta Impostazioni. Nota che lì sarà presente la checkbox Modalità di Presentazione. Una volta selezionata, un link apparirà nella vista della pagina per dare la possibilità ad un utente di visualizzarla nella Modalità di Presentazionee. Come creare una diapositiva Tutto il contenuto di una presentazione rimane in una sola pagina. Non devi creare una pagina per ogni diapositiva. Una dispositiva viene creata quando vedi la classe Intestazione (h1) nella pagina - queste effettivamente indicano a Plone dove si vuole far iniziare una diapositiva. Non ci sono limiti al numero di diapositive che puoi aggiungere in una presentazione. Ti basta inserire più tags Intestazione (h1) nella tua pagina ed il contenuto tra quel tag h1 e quello successivo diverrà il contenuto della tua diapositiva. Come Formattare una Diapositiva E’ molto importante notare che i contenuti con associato lo Stile Paragrafo Normale non vengono visualizzati nelle diapositive. Le diapositive sono pensate per visualizzare informazioni di riepilogo, non blocchi di testo. Per questo, devi dare uno stile diverso dal Paragrafo Normale al contenuto di ogni diapositiva. Esempi di questi stili sono: • Intestazione (h1) • Sottotitolo (h3) • Definizioni di liste • Liste non ordinate • Liste ordinate • Literal • Pull-quote • Call out • Evidenziato 1.3. Gestione dei contenuti 77
- 82. Documentazione di Plone, Release 4 1.3.11 Copia di lavoro La Copia di Lavoro ti permette di avere due versioni del tuo contenuto in parallelo. Quando un sito Plone viene creato per la prima volta, ci sono diverse funzioni aggiuntive che possono essere abilitate, tra cui la “Copia di Lavoro”. Se il sito Plone che stai usando non presenta l’opzione “Estrai versione” nel menu Azioni , devi contattare l’amministratore del sito e richiedere che “Il Supporto alla Copia di Lavoro” venga installato. Panoramica In precedenza potresti esserti trovato in una situazione a questa: hai pubblicato un documento e lo devi aggiornare molto frequentemente, ma vuoi che la vecchia versione continui ad esistere sul sito web finchè non hai pubblicato il nuovo. Vuoi anche che il nuovo documento sostituisca quello attuale, ma ti piacerebbe mantenere la storia di quello vecchio. La Copia di Lavoro rende tutto questo possibile. In sostanza, “estrai” la versione attualmente pubblicata del documento , che creerà una “copia di lavoro” del documento stesso. A questo punto modificherai la copia di lavoro (mettendoci tutto il tempo che ti servirà) e quando la nuova versione sarà pronta per essere pubblicata, utilizzando l’azione “crea versione” la tua copia di lavoro sarà online. Dietro le quinte, Plone sostituirà il documento originale con quello nuovo, nell’esatta posizione e con lo stesso indirizzo web e archivierà la vecchia versione come parte della storia nel controllo di versione del documento nuovo. Utilizzare la funzione “Estrai” First, navigate to the page you want check out. Then from the “Actions” In primo luogo, vai nella pagina in cui si desidera creare la copia di lavoro. Poi dal menu “Azioni” , seleziona “Estrai”: Un messaggio apparirà informandoti che da questo momento stai lavorando su una copia di lavoro: Da questo momento in poi potrai modificare la copia locale del documento pubblicato. Il documento originale risulterà “bloccato” – ovvero, nessun altro potrà modificare la versione pubblicata finchè avrai una copia di lavoro estratta. Questo impedirà che altre modifiche vengano effettuate (e conseguentemente perse) sulla versione pubblicata mentre stai modificando la tua copia di lavoro. Utilizzare la funzione “Crea versione” Quando sei pronto a sostituire la tua copia locale con quella pubblicata, ti basta semplicemente selezionare “Crea versione” dal menu “Azioni”: Ti verrà richiesto di inserire un messaggio legato alla creazione della nuova versione. Compilalo e clicca su “Crea versione”: 78 Capitolo 1. Plone 4: Manuale utente
- 83. Documentazione di Plone, Release 4 1.3. Gestione dei contenuti 79
- 84. Documentazione di Plone, Release 4 80 Capitolo 1. Plone 4: Manuale utente
- 85. Documentazione di Plone, Release 4 Il tuo documento aggiornato diventerà la nuova copia pubblicata. Verrai inoltre informato che non esisterà più una copia di lavoro del documento nella tua cartella personale. Nota che non è necessario (ed infatti non è consigliata) l’utilizzo del menu “Stato” con una copia di lavoro. Se tuttavia lo utilizzi senza volere, non farti prendere dal panico. Ti basta tornare nella tua copia di lavoro e utilizzare la funzione “Crea versione” dal menu “Azioni”. Cancellare una “Copia di lavoro” Se, per qualsiasi motivo, devi cancellare una copia di lavoro e non vuoi salvare le tue modifiche, vai semplicemente nella copia di lavoro e clicca su “Annulla il check-out”: Ti verrà chiesto di confermare il comando “Annulla il check-out” o di “Mantenere il checkout”: Nota che se un utente che ha estratto una copia di lavoro non è disponibile per effettuare la pubblicazione della copia di lavoro o annullarla, gli utenti con il ruolo di Manager possono accedere alla copia di lavoro ed effettuare sia la creazione della versione che l’annullamento della copia di lavoro. Questo perché non tutti i collaboratoti hanno il privilegio di eseguire la funzione “Crea versione”. Se tale opzione non è presente dal menu Azioni: 1. Utilizza il menu “Stato”. 2. Sottoponi per pubblicazione. 3. Chiedi ad un recensore di non cambiare lo stato. 4. Chiedi invece al revisore di effettuare il “Crea versione” per tuo conto. 1.3. Gestione dei contenuti 81
- 86. Documentazione di Plone, Release 4 La procedura “Crea versione” si occuperà della gestione dello stato. 1.4 Usare TinyMCE come visual editor 1.4.1 Introduzione Introduzione a TinyMCE. TinyMCE è una piattaforma web indipendente WYSIWYG in Javascript per la modifica dell’HTML . Questo significa che ti permette di creare contenuti html sul tuo sito web. TinyMCE supporta molti Sistemi Operativi e browsers. Alcuni esempi sono: Mozilla, Internet Explorer, Firefox, Opera, Safari e Chrome. TinyMCE è largamente utilizzato e una attiva comunità di sviluppo. TinyMCE è l’editor visuale di default a partire da Plone 4.0, Kupu è comunque disponibile per gli utenti che lo preferiscono. Si è deciso di fornire TinyMCE di default perchè Kupu non era ben mantenuto, mentre TinyMCE ha avuto un uso molto più ampio in altre comunità, così come un migliore sviluppo di plugin e qualche altra raffinatezza come la possibilità di aggiungere link sia interni sia esterni utilizzando lo stesso pulsante. 1.4.2 Nozioni di base Opzioni base di TinyMCE. L’editor TinyMCE di default ha il seguente aspetto: Nella parte alta puoi vedere la barra degli strumenti, sotto l’area di testo ed in fondo una barra per il ridimensionamento. Se trascini l’angolo in basso a destra puoi allargare o ridurre la finestra dell’editor. Barra degli strumenti La seguente tabella descrive le funzioni ed il risultato di ogni pulsante. 1.4.3 Inserire delle immagini Una panoramica delle opzioni disponibili per l’inserimento di immagini in TinyMCE. L’editor TinyMCE ti permette di inserire delle immagini caricate in Plone nella tua pagina, utilizzando il bottone sulla barra degli strumenti di TinyMCE: Cliccando su questo bottone, si apre la finestra per inserire un immagine: Le tre colonne della finestra sono: 82 Capitolo 1. Plone 4: Manuale utente
- 87. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 83
- 88. Documentazione di Plone, Release 4 84 Capitolo 1. Plone 4: Manuale utente
- 89. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 85
- 90. Documentazione di Plone, Release 4 • nella prima colonna c’è la lista di navigazione delle cartelle • nella seconda colonna c’è la lista dei contenuti della cartella corrente • nella terza colonna c’è l’anteprima dell’immagine, le opzioni di allineamento, le dimensioni disponibili per mostrare l’immagine e la didascalia. Nell’esempio sopra, è stata selezionata l’immagine di una rosa - rose.png ( l’immagine originale è piuttosto grande, 600*450 pixel). L’immagine verrà posizionata nella pagina in accordo al “Allineamento” scelto e verrà generato il seguente codice HTML: • A sinistra (<img class=”image-left captioned” src=”rose.png” alt=”rose” />) • A destra (<img class=”image-right captioned” src=”rose.png” alt=”rose” />) • In linea (<img class=”image-inline captioned” src=”rose.png” alt=”rose” />) Puoi anche scegliere la dimensione dell’immagine di cui hai bisogno. Questo è particolarmente utile quando hai a che fare con immagini di grandi dimensioni, poichè non c’è bisogno di utilizzare Photoshop o altre applicazioni esterne per ritagliare o modificare l’immagine. Il menu a tendina “Dimensioni” ti consente di scegliere tra diverse dimensioni e formati: • Large (<img src=”rose.png/image_large” alt=”rose” />); • Preview (<img src=”rose.png/image_preview” alt=”rose” />); • Mini (<img src=”rose.png/image_mini” alt=”rose” />) - questa è la dimensione minima per la visualizzazione dell’immagine; • Thumb (<img src=”rose.png/image_thumb” alt=”rose” />) - a thumb(inch)- dall’immagine verrà estratta una miniatura; (un pò più piccola di 2,5cm); • Tile (<img src=”rose.png/image_tile” alt=”rose” />) - a tile is made out of your image; • Icon (<img src=”rose.png/image_icon” alt=”rose” />) - dall’immagine verrà ricavata un’icona; • Listing (<img src=”rose.png/image_listing” alt=”rose” />) - dall’immagine verrà ricavata una piccola immagine in stile ‘elenco’; 86 Capitolo 1. Plone 4: Manuale utente
- 91. Documentazione di Plone, Release 4 Image Captioning In TinyMCE è possibile mettere una didascalia sotto l’immagine. La didascalia è presa dalla descrizione dell’immagine. Il testo alternativo è tratto dal titolo dell’immagine. Il testo alternativo e la didascalia si aggiornano automaticamente se l’immagine viene aggiornata. Per abilitare questa funzione accedere a Configurazione del sito -> Editor TinyMCE. Assicurati di selezionare Consenti la ‘titolazione’ delle immagini nella tab Tipi di risorse. Ora quando aggiungi un’immagine sul sito, puoi inserire una breve descrizione e questa verrà utilizzata come didascalia. Ora quando crei una pagina e inserisci un’immagine in essa, seleziona il box Didascalia: Ora, salvando le modifiche, il risultato dovrebbe essere simile a questo, con la descrizione dell’immagine inserita come didascalia all’interno di una cornice: 1.4.4 Inserting Links Inserting internal, external and anchor links. 1.4. Usare TinyMCE come visual editor 87
- 92. Documentazione di Plone, Release 4 88 Capitolo 1. Plone 4: Manuale utente
- 93. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 89
- 94. Documentazione di Plone, Release 4 90 Capitolo 1. Plone 4: Manuale utente
- 95. Documentazione di Plone, Release 4 Internal Links Select a word or phrase, click the Insert/edit link icon, and the Insert/edit link panel will appear: You use this panel by clicking on Home or Current folder to begin navigating the Plone web site to find a folder, page, or image to which you wish to make a link. In the example above, a page named “Long-tailed Skippers” has been chosen for the link. After this panel is closed, a link to the “Long-tailed Skippers” page will be set for the word or phrase selected for the link. External Links Select a word or phrase, click the Insert/edit link icon, select External under Libraries, and the External link panel will appear: Type the web address of the external web site in the box after http://. When you press return or leave the field a preview will appear to check the address. If you paste in the web address, make sure you don’t have duplicate http:// at the beginning of the address. Then click ok. The external link will be set to the word or phrase you selected. Anchors Anchors are like position markers within a document, based on headings, subheadings, or another style set within the document. As an example, for a page called “Eastern Tiger Swallowtail,” with subheadings entitled “Description,” “Habitat,” “Behavior,” “Conservation Status,” and “Literature,” an easy set of links to these subheadings (to the positions within the document at those subheadings) can be created using anchors. First, create the document with the subheadings set within it, and re-type the subheadings at the top of the document: Now create the anchors for each subheading. To create each anchor move the cursor to the beginning of the subheading and press the Insert/edit anchor icon. Enter the name of the anchor in the Anchor name field. Then click ok. 1.4. Usare TinyMCE come visual editor 91
- 96. Documentazione di Plone, Release 4 Then select each of the re-typed subheadings at the top and click the Insert/edit link icon to select by subheadings: When selecting Anchors under Libraries, a panel will appear for selecting which subheading to which the anchor link should connect: The Link to anchor tab will appear. The right side of the panel shows the anchors that have been set within the document. Here the Description anchor is chosen for the link (for the word Description, typed at the top of the document). You can be creative with this powerful feature, by weaving such links-to-anchors within narrative text, by setting anchors to other styles within the document, and coming up with clever mixes. This functionality is especially important for large documents. 1.4.5 Inserting Tables Inserting, updating and deleting tables, columns, rows and cells. Tables are handy for tabular data and lists. To add a table, put your cursor where you want it and click the Inserts a new table icon. You’ll see the Insert/Modify table panel: Setting rows and columns is straightforward. You can add a summary of the table in the Summary field if you like. Table class refers to how you want the table to be styled. You have choices such as these: Here are examples of these table styles: Subdued grid: Invisible grid: Fancy listing: 92 Capitolo 1. Plone 4: Manuale utente
- 97. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 93
- 98. Documentazione di Plone, Release 4 94 Capitolo 1. Plone 4: Manuale utente
- 99. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 95
- 100. Documentazione di Plone, Release 4 96 Capitolo 1. Plone 4: Manuale utente
- 101. Documentazione di Plone, Release 4 1.4. Usare TinyMCE come visual editor 97
- 102. Documentazione di Plone, Release 4 Fancy grid listing: Fancy vertical listing: After the table has been created you can click in a cell to show table resizing handles: In the table above, the cursor has been placed in the “Special Leader” cell, which activates little square handles around the edges for resizing the entire table. It also activates the other table controls in the toolbar which, lets you edit properties of a row or a cell, lets you add and remove rows or columns and lets you split and merge cells. 1.5 Usare Kupu come visual editor Kupu è una piattaforma indipendente, un editor Javascript HTML WYSIWYG, web based. Questo significa che ti consente di creare contenuti HTML sul tuo sito web. Da Plone 4 in poi, TinyMCE è il visual editor predefinito per i nuovi siti. Tuttavia, Kupu è ancora disponibile se lo preferisci. Controlla la sezione rst_setting-preferences per imparare a impostare Kupu come il tuo editor predefinito. Una tipica barra degli strumenti Kupu assomiglia a questa: 98 Capitolo 1. Plone 4: Manuale utente
- 103. Documentazione di Plone, Release 4 Il formato testo viene normalmente lasciato con l’impostazione HTML, ma alcuni siti offrono testo strutturato o altri linguaggi di markup per la modifica delle pagine. Le icone sono: • grassetto, • italico, • giustificato a sinistra, • giustificato centrato, • giustificato a destra, • elenco numerato, • elenco puntato, • elenco di definizioni, • tab a sinistra (blocco), • tab a destra (blocco), • immagine (l’icona “albero”), • link interno (l’icona “anello della catena”, crea un link a un’altra pagina nel sito), • link esterno (l’icona “mondo”, crea un link a una pagina web altrove), • ancora (l’icona “ancora”, crea un link ad una sezione specifica di una pagina), Figura 1.22: kupu-grab 1.5. Usare Kupu come visual editor 99
- 104. Documentazione di Plone, Release 4 • tabella (aggiunge una tabella con righe e colonne), • HTML editing diretto (l’icona “HTML”; se si conosce HTML, modifica direttamente il codice HTML per la pagina), • menu a tendina per lo stile del testo. 1.5.1 Immagini Posizionare il cursore all’interno del testo di una pagina, fare click sull’icona “albero”. Si aprirà questo pannello: Fare click su “Cartella Corrente” nella parte sinistra del pannello, se non è già evidenziata. La cartella corrente è la cartella che contiene la pagina che si sta modificando - tutte le pagine sono contenute in cartelle. Ci sono molti modi per gestire la memorizzazione di immagini, tra cui avere una cartella centrale di immagini, ma un metodo comune è quello di memorizzare le immagini mostrate su una pagina nella cartella che contiene la pagina (la cartella corrente). In questo modo, le pagine e le immagini ad esse associate sono memorizzate insieme all’interno della struttura delle cartelle. Se fai click sul pulsante Carica, ti verrà chiesto di selezionare un’immagine sul tuo computer e caricarla. Dopo aver selezionato l’immagine da caricare, il pannello di destra ti permetterà di dare all’immagine un titolo per l’uso sul sito web, e diverse opzioni per la posizione e il dimensionamento dell’immagine. Facendo click su OK viene caricata l’immagine e collocata nella pagina. Lo stesso pannello apparirà se si fa click su un’immagine nella pagina per selezionarla e scegliendo la stessa icona “albero” per modificare le opzioni di immagine o per modificare l’immagine. Sei responsabile per il dimensionamento e l’editing delle immagini sul tuo computer prima di caricarle, ma un modo semplice per gestire le immagini da usare sulla maggior parte delle pagine web è quello di fare una copia di un’immagine sul computer, quindi ridimensionarla a qualcosa come 1000 pixel nella dimensione più grande. Questo è una dimensione ragionevole per il caricamento - non è necessario caricare le tue immagini gigantesche provenienti dalla fotocamera digitale. Plone creerà automaticamente diversi formati di un’immagine caricata, tra cui “large”, “mini”, e altre dimensioni. Si sceglie la dimensione che si desidera utilizzare quando si carica o modifica l’immagine con l’icona “albero”. È anche possibile ignorare la scelta della dimensione dell’immagine modificando il codice HTML. 100 Capitolo 1. Plone 4: Manuale utente
- 105. Documentazione di Plone, Release 4 1.5.2 Collegamenti Interni Selezionare una parola o una frase, fare click sull’icona collegamento interno, e apparirà il pannello Inserisci Link: Puoi utilizzare questo pannello facendo click sulla cartella Home o cartella Corrente per iniziare la navigazione nel sito web Plone e per trovare una cartella, una pagina, o l’immagine a cui si desidera creare un collegamento. Nel precedente esempio, è stata scelta per il collegamento una pagina denominata “Long-tailed Skippers”. Dopo che questo pannello si è chiuso, verrà impostato un collegamento alla pagina “Long-tailed Skippers” per la parola o per la frase selezionata per il collegamento. 1.5.3 Collegamenti Esterni Selezionare una parola o una frase, fare click sull’icona collegamento esterno, e apparirà il pannello Link Esterno: Digitare l’indirizzo web del sito esterno nel box che inizia con http://. È possibile fare click su anteprima se hai bisogno di controllare l’indirizzo. Se incolli l’indirizzo web, assicurati di non duplicare http:// all’inizio dell’indirizzo. Poi fare click su OK. Il collegamento esterno verrà impostato per la parola o la frase selezionata. 1.5.4 Le Ancore Le Ancore sono dei link in un documento che puntano direttamente ad una sezione del documento stesso, sulla base di titoli, sottotitoli o altri stili definiti all’interno dello stesso. Ad esempio, in una pagina chiamata “Eastern Tiger Swallowtail”, in cui sono definite delle sottosezioni intitolate “Description”, “Habitat”, “Behavior”, “Conservation Status” e “Literature”, è possibile creare un semplice elenco di link a queste sottovoci (che puntano direttamente alla sottovoce all’interno del documento) utilizzando le ancore. Per prima cosa, crea il documento con i sottotitoli e riscrivi i sottotitoli all’inizio del documento come per un indice: Quindi seleziona ogni sottotitolo riscritto all’inizio del documento e clicca l’icona a forma di ancora: Apparirà una maschera che permetterà di selezionare quale sottotitolo deve essere collegato all’ancora: 1.5. Usare Kupu come visual editor 101
- 106. Documentazione di Plone, Release 4 Verrà visualizzata la scheda Collegamento all’ancora. La sezione di sinistra mostrerà una lista di stili che posso essere utilizzati nel documento. Nel nostro esempio, i sottotitoli verranno usati per ogni sezione, ed è il caso più comune. La parte destra mostrerà i sottotitoli che sono stati creati nel documento. Nel nostro caso verrà selezionato il sottotitolo Description (per creare il collegamento con lo stesso riscritto all’inizio del documento). Puoi essere molto creativo con questa potente funzione, tessendo un testo dinamico, intelligente ed intersecando diverse sezioni della narrazione. Questa funzionalità è particolarmente importante per i documenti lunghi. 1.5.5 Tabelle Le tabelle sono a portata di mano per la visualizzazione di dati tabulari e liste. Per aggiungere una tabella posiziona il cursore nel punto desiderato e fai click sull’icona aggiungi tabella. Vedrai il pannello aggiungi tabella: L’impostazione delle righe e delle colonne è semplice. Se selezioni il box Crea Intestazioni avrai un posto dove digitare le intestazioni della colonna per la tabella. La classe della tabella si riferisce al suo stile. Hai scelte come queste: Ecco alcuni esempi di questi stili per la tabella: plain: Thoroughbred Champions Man O’ War Secretariat Citation Kelso Count Fleet Quarter Horse Champions First Down Dash Dashing Folly Special Leader Gold Coast Express Easy Jet listing: 102 Capitolo 1. Plone 4: Manuale utente
- 107. Documentazione di Plone, Release 4 1.5. Usare Kupu come visual editor 103
- 108. Documentazione di Plone, Release 4 104 Capitolo 1. Plone 4: Manuale utente
- 109. Documentazione di Plone, Release 4 1.5. Usare Kupu come visual editor 105
- 110. Documentazione di Plone, Release 4 Thoroughbred Champions Man O’ War Secretariat Citation Kelso Count Fleet Quarter Horse Champions First Down Dash Dashing Folly Special Leader Gold Coast Express Easy Jet Dopo che la tabella è stata creata puoi fare click in una cella per mostrare il ridimensionamento della tabella e le icone per aggiungere/eliminare righe e colonne: Nella tabella sopra, il cursore è stato posizionato nella cella “Special Leader”, esso attiva i quadrattini di gestione intorno ai bordi per ridimensionare l’intera tabella. Attiva anche le icone aggiungere/eliminare per la cella corrente, la cella “Special Leader”. Cliccando sulla piccola x nel cerchio si elimina l’intera riga o colonna che contiene l’attuale cella. Cliccando le piccole icone a punta di freccia si aggiunge una riga sopra o al di sotto, o una colonna a sinistra o a destra della cella corrente. 1.5.6 Stile del Testo L’impostazione dello stile del testo è fatta con un menu a tendina. Ecco le scelte: Come in un normale editor di testi, seleziona una parola, una frase, o paragrafo con il mouse, quindi scegli una delle opzioni di stile del menu a tendina e vedrai la modifica immediatamente. 1.5.7 Salvare Fare click sul pulsante Salva in fondo e le modifiche della pagina saranno memorizzate. 1.5.8 Note a pié di pagina Linguaggi di mark-up Se sei il tipo di persona che ama inserire il testo utilizzando i cosiddetti formati mark-up, è possibile disattivare l’editor visuale sotto le tue preferenze personali, e un pannello semplificato di inserimento testo andrà a sostituire Kupu. I formati mark-up disponibili in Plone sono: • Markdown • Textile • Structured Text 106 Capitolo 1. Plone 4: Manuale utente
- 111. Documentazione di Plone, Release 4 1.5. Usare Kupu come visual editor 107
- 112. Documentazione di Plone, Release 4 • Restructured Text Ognuno di questi funziona incorporando speciali codici di formattazione all’interno del testo. Ad esempio, con la formattazione Structured Text, circondando una parola o una frase da un asterisco doppio si otterrà quella parola o frase in grassetto, come in **Questo testo sarà in grassetto.** Vale la pena di imparare questi formati di mark-up per la velocità di inserimento se si creano molte pagine, o se si è abili in tali approcci per l’inserimento di testo leggermente più tecnici. Alcune persone preferiscono questi formati non solo per la velocità in sé, ma per fluidità di espressione. 1.6 Collaborazione e flusso di lavoro Imparare a condividere e controllare l’accesso al contenuto utilizzando la Scheda Condivisione e il menu Stato. 1.6.1 Stati di pubblicazione di base Il sistema di controllo della pubblicazione di Plone è molto flessibile, a partire dalle impostazioni di base per la creazione di un elemento privato o pubblico. Nell’angolo in alto a destra del riquadro di modifica di qualsiasi tipo di contenuto – cartelle, immagini, pagine, etc. e tutti i tipi di contenuto specializzati – c’è il menu per gestire lo stato di pubblicazione. Questo menu degli stati gestisce lo stato della pubblicazione: L’intestazione del menu mostrerà lo stato di pubblicazione attuale del contenuto, ad esempio Stato: Privato, come mostrato sopra. Lo stato Privato è lo stato iniziale al momento della creazione di un elemento – un’immagine caricata, una pagina, una notizia – ed in questo stato, come indica il nome, l’elemento non sarà generalmente fruibile dai visitatori del sito web. Scegliendo dal menu lo stato Pubblica, il contenuto diverrà fruibile agli utenti anonimi del sito. L’opzione Sottoponi per pubblicazione viene utilizzata nei siti dove ci sono dei revisori di contenuti che devono approvare l’elemento per la pubblicazione, come descritto in seguito. Inoltre, e questo sarà molto importante, certi tipi di contenuto, come ad esempio le notizie e gli eventi, non appariranno sul sito web come ti aspetteresti, fino a quando non verranno esplicitamente pubblicati. Imprimiti nella memoria che: Lo stato di pubblicazione è importante! Lo stato di pubblicazione può essere modificata solo dagli utenti che dispongono delle autorizzazioni necessarie. Le scelte nel menu rispecchieranno le autorizzazioni possedute. Ad esempio, in un sito web di un grande giornale, un giornalista potrebbe aggiungere delle pagine come se fossero degli articoli, ma il menu di pubblicazione non mostrerà la scelta Pubblica ma solo Sottoponi per pubblicazione. Questo perchè il giornalista, prima della pubblicazione, deve inviare l’articolo alla redazione per l’approvazione. Se tuttavia il tuo account ha i permessi , la scelta Pubblica sarà disponibile e potrai semplicemente pubblicarlo in un passaggio. Per un editore, un elemento che è stata inviato può essere pubblicato o revocato, revocato nei casi in cui l’invio sia inappropriato rispetto alla situazione o per la ragione più comune ovvero che il contenuto debba essere approvato. 108 Capitolo 1. Plone 4: Manuale utente
- 113. Documentazione di Plone, Release 4 Dopo che un elemento è stato pubblicato, può essere revocata la pubblicazione, per reimpostare lo stato alla bozza pubblica, o mandarlo indietro allo stato provato. Le scelte del menu di pubblicazione cambieranno di conseguenza: Occorre prendere in considerazione di revocare (“annullamento della pubblicazione”), o di rendere privato, qualsiasi contenuto che è diventato obsoleto o indesiderato per qualsiasi ragione. L’impostazione privato renderà l’elemento invisibile al pubblico e nei risultati delle ricerche, ma rimarrà nel caso in cui il formato o i contenuti (testo, immagini, etc.) servano in futuro. Questo è utile soprattutto per i contenuti relativi a eventi che possono ripresentarsi o ad inserimenti una tantum. La decisione di cancellare o di impostare come privato un elemento dipende dal fatto che il contenuto esista già da un’altra parte o in locale sul computer. Se il contenuto è di grandi dimensioni, nel senso di spazio su disco occupato, è probabilmente opportuno farsene una copia locale prima di concellarlo, se lo spazio sul server è un problema. 1.6.2 Controllo avanzato Il sistema di controllo della pubblicazione, alla voce del menu avanzate, ha caratteristiche sofisticate per impostare la disponibilità per data e per contesto. Il menu stato ha una voce Avanzate...: Figura 1.23: state-menu.png che porta al pannello per la gestione avanzata della pubblicazione: Di seguito una spiegazione dell’immagine: partendo dall’inizio del pannello c’è una casella che mostra il contenuto che sarà interessato dalla modifica dello stato di pubblicazione. Nel caso mostrato nella figura, la cartella “Long-tailed Skipper” sarà interessata da questo cambiamento. Il campo successivo, Includi gli elementi contenuti, è una casella per controllare se il cambiamento di stato debba avere effetto solo sull’oggetto selezionato (la cartella “Long-tailed Skipper”) o anche sugli elementi contenuti includendo sia eventuali sottocartelle e relativi sottocontenuti sia altri tipi di elementi. Questa è una casella importante. Ti permette di cambiare semplicemente lo stato di un’intera sezione del sito internet. Per esempio, la cartella “Long-tailed Skipper” 1.6. Collaborazione e flusso di lavoro 109
- 114. Documentazione di Plone, Release 4 110 Capitolo 1. Plone 4: Manuale utente
- 115. Documentazione di Plone, Release 4 potrebbe contenere quattro sottocartelle: una per le fotografie, una per le occorrenze speciali, una per la tassonomia e una per delle descrizioni, tutte lasciate private durante il lavoro iniziale per la creazione della sezione. Tutte possono essere rese pubbliche – possono essere pubblicate – selezionando questo controllo e selezionando Pubblica in basso prima di salvare. Analogamente, la scelta *Sottoponi per pubblicazione * può essere usata nei siti web dove gli editori revisionano cosa pubblicare. Allo stesso modo, una intera sezione potrebbe essere immediatamente resa privata. Per esempio, se un agenzia di noleggio auto ha deciso di rimuovere un modello di auto dalla sua flotta, un’intera sezione del loro sito web dedicato a questa vettura, con diverse sottocartelle piene di pagine, immagini e file, potrebbe essere impostata su privato. I prossimi due campi data sono per impostare la data di pubblicazione e la data di scadenza. Il loro significato è semplice. Se un elemento o un insieme di elementi devono essere pubblicati per un certo lasso di tempo, si possono impostare questi campi. Puoi lasciare un commento con la spiegazione legato a tutti i contenuti interessati dal cambiamento di stato. Ciò è particolarmente utile quando più persone lavorano sullo stesso sito web: una persona che ha meno familiarità con un’area del sito web si chiederebbe il motivo per cui certi elementi non sono stati pubblicati. Si domanderebbero: “Questa informazione sembra buona. Perché non è già stata pubblicata?”. In seguito però potrebbero leggere un commento che dice qualcosa del tipo: “Non pubblicare fino a che Richard non abbia fatto dei controlli su possibili problemi di copyright per quanto riguarda elementi descritti qui”. L’uso dei commenti è molto utile per annotare informazioni sensibili, anche se si è l’unica persona che lavora sul sito web, in quanto si potrebbe dimenticare il motivo di una decisione presa sullo stato di pubblicazione. Infine, nella parte finale, si può scegliere lo stato da applicare tra quelli disponibili per questa azione. Varierà, a seconda dello stato attuale dell’elemento. Ad esempio, se l’articolo è attualmente nello stato pubblicato, non vi sarà la scelta pubblica, se si trova nello stato privato, non sarà presente la scelta per renderlo privato, ecc. Se un elemento è già pubblicata, in questa parte inferiore del pannello saranno presenti le scelte per revocare e mandare indietro, che “annulleranno la pubblicazione” dell’elemento, reimpostandolo allo stato bozza o allo stato privato. |image24| Guarda un video con Plone 2 sul controllo dello stato di pubblicazione. 1.6.3 Politiche dei workflow Le politiche dei workflow consentono ad un amministratore del sito di creare un sistema formalizzato per controllare la pubblicazione e la gestione dei contenuti come in un flusso passo a passo che coinvolge utenti diversi con ruoli prestabiliti. I workflow sono un argomento avanzato. Implicano la creazione di un controllo più rigido nell’aggiunta di contenuti, revisione e pubblicazione. Se disponi di un account su un tipico sito Plone di piccole dimensioni, probabilmente non utilizzerai le politiche di workflow personalizzate perché non c’è bisogno di questo controllo sofisticato. Ma, la potenzialità di questo strumento è presente, in quanto è parte di Plone. Per una introduzione al concetto di workflow, considera un esempio che coinvolge il sito web di un quotidiano, dove lavorano questi differenti gruppi di persone: Reporters Possono creare articoli ma solo inviarli per essere revisionati. Redattori Possono revisionare articoli, ma non possono pubblicarli direttamente. Mandano la revisione positiva e fanno avanzare il flusso alla successiva approvazione. Editori Fanno il controllo finale, le correzioni, la revisione e possono pubblicare gli articoli. Una politica di workflow, spesso abbreviata in workflow, descrive i vincoli che esistono durante i cambiamenti di stato per i diversi gruppi di persone. Una volta che la politica di workflow è stato creato, deve essere applicata ad un’area del sito web in modo tale che le regole abbiano effetto. Nell’esempio del sito del quotidiano, una politica di workflow dovrà essere impostata e applicata alla cartella dove i reporters aggiungono nuovi articoli. In seguito, i reporters vi potranno creare gli articoli ed inviarli per la revisione e l’approvazione: 1.6. Collaborazione e flusso di lavoro 111
- 116. Documentazione di Plone, Release 4 I reporter dovrebbe aggiungere articoli e dovrebbero solo sottoporli per la pubblicazione (l’opzione pubblica del menu non è disponibile per loro). Allo stesso modo, i redattori possono rifiutare l’articolo da revisionare o possono, a loro volta, sottoporre l’articolo agli editori per la correzione finale e la pubblicazione. Nell’esempio dell’azienda di quotidiani, questa politica potrebbe essere chiamata “Politica di revisione editoriale”. Nella configurazione di una politica di workflow è fondamentale assegnare la stessa ad un’area del sito web – per definire il campo di applicazione del workflow. Questo è compito dell’amministratore del sito. L’amministratore deve usare il pannello di controllo di Plone per specificare dove la “Politica di revisione editoriale” si applica, a livello globale o in una sottosezione. Plone è dotato di diverse politiche workflow utili - quella di default è un semplice politica di pubblicazione web. Il tuo amministratore del sito potrebbe impiegare una politica più specifica, ad esempio configurata per una comunità web o configurata per una Intranet aziendale (sistema web interno). In tal caso, potrebbe essere necessario imparare alcuni passi procedurali per la pubblicazione, ma queste sono solo varianti della politica base di default. 1.6.4 Collaborazione attraverso la condivisione La scheda Condivisione consente di collaborare con altri utenti attraverso l’uso di diversi ruoli integrati. Esempio 1: Consentire ad altri di aggiungere contenuti in una cartella che hai creato In questo esempio, Jane Smythe ha pieno accesso al suo sito Plone. Lei è in grado di aggiungere, modificare, cancellare e pubblicare contenuti in qualsiasi parte del sito. Per ora, ha creato una cartella denominata “Documentazione” e vi ha aggiunto una pagina, “Presentazione Progetto”. Non ha pubblicato né la cartella né il documento. Il workflow di default per questo sito Plone non è stato modificato. Ora vuole dare il permesso al suo collega, George Shrubb, di aggiungere contenuti alla cartella Documentazione. Lui ha il permesso di modificare qualsiasi contenuto esistente, ma lei ha bisogno che lui inizi ad aggiungere contenuti. Prima di proseguire insieme a Jane, diamo uno sguardo a quello che George vede quando si autentica in questo sito Plone: Nota che in questo momento George non può nemmeno vedere la cartella Documentazione perché quando Jane l’ha creata, l’ha lasciata nello stato Privato. Tutte le autorizzazioni predefinite sono attualmente in atto e funzionano come previsto. 112 Capitolo 1. Plone 4: Manuale utente
- 117. Documentazione di Plone, Release 4 Jane conferisce a George le autorizzazioni necessarie per aggiungere contenuti alla cartella Documentazione. Jane passa alla cartella Documentazione e fa clic sul tab Condivisione: Una delle prime cose da notare è che Jane ha già tutte le autorizzazioni disponibili per questa cartella. Queste autorizzazioni erano in realtà state concesse in una sezione superiore del sito, come indicato dal simbolo di spunta verde. Dando un’occhiata più da vicino, le autorizzazioni disponibili sono: • Può aggiungere - Questo significa che quando questa autorizzazione viene concessa ad un particolare utente (o gruppo di utenti), esso può aggiungere nuovi contenuti. Dal momento che l’utente è stato anche il creatore di quel contenuto, sarà in grado di modificarlo a suo piacimento. • Può modificare - Quando questa autorizzazione viene concessa ad una cartella, l’utente può non solo modificare la Cartella (il titolo e la descrizione), ma può anche modificare uno qualsiasi degli elementi contenuti. Nota, tuttavia, che l’utente non è autorizzato ad eliminare i contenuto. Se questa autorizzazione viene concessa su una pagina, per esempio, l’utente può modificare solo quella pagina e nessuno degli altri elementi presenti nella cartella. • Può vedere - Quando questa autorizzazione viene utilizzata su una cartella o un altro elemento, l’utente può visualizzare il contenuto ma non apportare modifiche. • Possono revisionare - Quando questa autorizzazione viene concessa, l’utente può pubblicare i contenuti. Nota: queste autorizzazioni sovrascrivono i permessi definiti nel workflow! Ad esempio, se si concede a un utente l’autorizzazione “Può vedere” in una pagina che è nello stato privato, l’utente potrà vederla. In questo esempio, Jane concede a George l’autorizzazione “Può aggiungere” nella Cartella “Documentazione” in modo che possa aggiungere contenuti in essa. Per fare questo, come primo passo, lo cerca utilizzando il suo nome: Jane ora può aggiungere le autorizzazioni necessarie a George nella cartella “Documentazione”. Deve selezionare il permesso “Può aggiungere” e premere “Salva”: Questo è tutto ciò che devi fare! Vediamo come George vede il sito ora. 1.6. Collaborazione e flusso di lavoro 113
- 118. Documentazione di Plone, Release 4 114 Capitolo 1. Plone 4: Manuale utente
- 119. Documentazione di Plone, Release 4 Nota: George NON ha bisogno di disconnettersi e riconnettersi. Le autorizzazioni sono sempre aggiornate perché sono controllate ogni volta che un utente accede a qualsiasi cosa (ad esempio cliccando su un link) su un sito Plone. George clicca sulla scheda Home (per esempio) per aggiornare la sua visione del sito e visualizzerà la cartella “Documentazione”: Quando George fa click sulla scheda “Documentazione”, si accorge che può visualizzare tutto il contenuto e che è ora in grado di aggiungere i tipi di contenuto disponibili nela cartella, come mostrato nel menu Aggiungi...: George vuole visionare ciò che Jane ha già creato, quindi seleziona il link Project Overview e vede: 1.6. Collaborazione e flusso di lavoro 115
- 120. Documentazione di Plone, Release 4 Anche se George può visualizzare il documento, le sue autorizzazioni limitate non gli consentono di modificarlo o di cambiare il suo stato. L’unica cosa che può fare, al di là di visualizzare il documento, è di farne una sua copia. George aggiunge una pagina intitolata “Widget Installation” e ne crea il contenuto . Quando ha terminato, la salva: Jane vede il lavoro fatto da George. Seleziona la scheda “Documentazione” e vede il lavoro di George. Clicca sulla pagina “Widget Installation” per dare un’occhiata più da vicino: Si noti che Jane ha pieno accesso alla pagina che ha creato George. Lei può modificarla così come tagliarla/copiarla/incollarla. In realtà lei attenderà che George invii la pagina per la revisione prima di eventualmente 116 Capitolo 1. Plone 4: Manuale utente
- 121. Documentazione di Plone, Release 4 modificarla. Esempio 2: Permettere ad altri di modificare contenuti creati da te Sia Jane sia George hanno lavoro per creare le pagine della cartella Documentazione. Jane ha pubblicato la cartella e diverse pagine: Jane ha deciso che vuole consegnare a George i permessi di modifica (ma non di pubblicazione) per tutti gli elementi cartella “Documentazione”. Per fare questo Jane deve tornare nella cartella “Documentazione” e cliccare sulla scheda Condivisione: 1.6. Collaborazione e flusso di lavoro 117
- 122. Documentazione di Plone, Release 4 Figura 1.24: sharing10.png 118 Capitolo 1. Plone 4: Manuale utente
- 123. Documentazione di Plone, Release 4 Da qui deve solo selezionare la casella di controllo “Può modificare” e George sarà in grado di modificare tutto il contenuto nella cartella “Documentazione” – compresa la cartella “Documentazione” stessa. Quando successivamente George visiterà la cartella e cliccherà su “Presentazione del progetto” (che è una pagina che Jane ha creato), questo è quello che vedrà: Figura 1.25: sharing11.png Ora George può modificare qualsiasi elemento nella cartella “Documentazione”, indipendentemente da quando o da chi lo ha creato. Nel frattempo, Molly si è unita a George come nuovo membro del team. Molly aiuterà George nell’aggiornamento del documento “Widget Installation”. George dovrà andare nella scheda condivisione dell’elemento “Widget Installation” e cercare il nome completo di Molly (non il nome utente) e selezionerà “Può modificare” per darle l’autorizzazione su questo documento. Quando Molly entrerà nella cartella “Documentazione”, potrà vedere i due articoli pubblicati e l’elemento privato che ora è autorizzata a modificare: E, infatti, quando farà un click sul documento “Widget Installation”, sarà in grado di modificarlo: Si noti, tuttavia, che quando Molly selezionerà uno dei due elementi dove non ha il permesso di modifica, non avrà alcun ulteriore accesso. Può visualizzare questi due elementi perché sono pubblicati come definito nel workflow di default di Plone (il chè significa che chiunque può vederli). Una nota finale su questo esempio: se la cartella “Documentazione” non fosse stata nello stato di pubblicazione O Molly non avesse avuto delle autorizzazioni particolari (per esempio, “Può visualizzare” nella cartella Documentazione), Molly avrebbe avuto bisogno dell’URL completo per raggiungere il documento a cui le era stato dato l’accesso per la modifica. Le autorizzazioni sono molto specifiche in Plone! 1.6. Collaborazione e flusso di lavoro 119
- 124. Documentazione di Plone, Release 4 Figura 1.26: sharing12.png 120 Capitolo 1. Plone 4: Manuale utente
- 125. Documentazione di Plone, Release 4 Figura 1.27: sharing13.png Figura 1.28: sharing13b.png 1.6. Collaborazione e flusso di lavoro 121
- 126. Documentazione di Plone, Release 4 Figura 1.29: sharing13c.png 122 Capitolo 1. Plone 4: Manuale utente
- 127. Documentazione di Plone, Release 4 1.7 Utilizzo delle collezioni Le collezioni sfruttano l’intelligenza di Plone. 1.7.1 Introduzione alle Collezioni Una Collezione in Plone funziona come un report o una query fatta in un database. Utilizza le Collezioni per ordinare e visualizzare in modo dinamico il tuo contenuto. Una Collezione in Plone funziona come un report o una query fata in un database. L’idea è di utilizzare una collezione per cercare nel tuo sito web in base ad un insieme di Criteri quali: il tipo di contenuto (pagina, notizia, immagine), la data di pubblicazione o parole chiave contenute nel titolo, nella descrizione o nel corpo. Diciamo che sul tuo sito web hai un ampio catalogo di foto e mappe. Si possono facilmente visualizzare tutte in una sola volta creando un collegamento ipertestuale alla cartella dove sono archiviate. Inoltre, se avessi organizzato i contenuti in sottocartelle, dovresti anche creare dei collegamenti diversi per ognuna di esse. Tuttavia, se le immagini e le mappe fossero state inserite in più cartelle sparse nel sito, questa operazione potrebbe diventare macchinosa. Inoltre, le cartelle normali non hanno la possibilità di visualizzare contenuti diversi, provenienti da diverse parti del tuo sito basandosi su criteri come: • parole chiave nel titolo • data di creazione • autore • tipo di contenuto La necessità di visualizzazione i contenuti in una varietà di modi dinamici viene soddisfatta dalle Collezioni (precedentemente note come Smart Folders o Rich Topic nelle versioni precedenti di Plone). Le Collezioni di fatto non contengono elementi come accade in una cartella. Al contrario sono i Criteri stabiliti che determinano quali contenuti far apparire nella pagina dove è definita la Collezione. I casi comuni dove applicare le Collezioni sono: • Archivio di Notizie • Archivio di Eventi • Visualizzazione di Foto dato un intervallo di date • Visualizzazione di contenuti data una parola chiave 1.7.2 Aggiungere Collezioni Le Collezioni (una volta chiamate Smart Folders) sono contenitori virtuali con liste di elementi trovati utilizzando ricerche specifiche. Comprendere che i contenuti possono essere memorizzati ovunque ed imparare a creare collezioni personalizzare per fornire “viste” differenti ai contenuti, è un passo importante per poter utilizzare Plone in modo efficace. E’ un sistema intelligente. Per aggiungere una collezione, utilizza il menu “Aggiungi...”, nello stesso modo in cui aggiungi altri contenuti: Ti comparirà il riquadro per aggiungere una Collezione: Sotto i campi titolo e descrizione ci sono un insieme di campi per specificare il formato dei risultati restituiti dal criterio di ricerca della nuova collezione. I quattro campi nel riquadro sopra sono a coppie. I primi due in alto consentono di limitare i risultati della ricerca a un certo numero di elementi. Gli ultimi due consentono di controllare l’ordinamento dei risultati. 1.7. Utilizzo delle collezioni 123
- 128. Documentazione di Plone, Release 4 Figura 1.30: p4_addnewmenu Impostare il criterio di ricerca Dopo aver impostato le configurazioni di visualizzazione nel riquadro di modifica sopra indicato, fai click sulla scheda criteri per visualizzare il pannello per impostare i criteri di ricerca: L’area superiore del pannello, Aggiungi nuovo Criterio, consente di impostare un campo e un criterio di corrispondenza. L’area inferiore, Ordinamento, permette semplicemente di selezionare un campo per l’ordinamento: I tipi di criteri per la ricerca dipendono dal quale campo viene selezionato. Dopo aver salvato la collezione, i criteri di ricerca saranno applicati ed il risultato mostrato quando la collezione viene selezionata. È possibile creare un numero qualsiasi di collezioni per ogni visualizzazione che si vuole personalizzare. Per l’esempio delle farfalle sopra descritto, oltre ad un vincolo sulla data per trovare gli elementi recenti, il campo categorie potrebbe essere utilizzato per abbinare il colore alle farfalle e ottenere una serie di collezioni di “Farfalle blu”, “Farfalle Bianche,” ecc. Criteri multipli possono essere utilizzati nella stessa collezione. Per esempio, una collezione chiamata “Farfalle fotografate nel mese scorso,” potrebbe essere fatto impostando un criterio relativo alla data di creazione ed al tipo di elemento che dovrà essere una immagine. Questi data-base generati dalle collezioni sono veramente efficaci per mostrare viste di contenuti aggiornate che non richiedono alcun lavoro amministrativo a mano - una volta che tale raccolta è stata creata, verrà automaticamente aggiornata. Nota: Una collezione non si comporta come una normale cartella; non puoi aggiungere elementi tramite la voce del menu aggiungi, come è possibile fare in una normale cartella. 124 Capitolo 1. Plone 4: Manuale utente
- 129. Documentazione di Plone, Release 4 Figura 1.31: p4_addcollection2 1.7. Utilizzo delle collezioni 125
- 130. Documentazione di Plone, Release 4 Figura 1.32: p4_collectionssearchcrit1 2 126 Capitolo 1. Plone 4: Manuale utente
- 131. Documentazione di Plone, Release 4 Figura 1.33: p4_collectionssearchcrit2 2 1.7. Utilizzo delle collezioni 127
- 132. Documentazione di Plone, Release 4 1.7.3 Regolazione delle Impostazioni di Visualizzazione Ulteriori informazioni su come le impostazioni di visualizzazione possono modificare l’aspetto della pagina Collezione Mentre il punto di forza delle Collezioni sta nei Criteri, le impostazioni di display possono fare una grande differenza nel modo in cui la vostra Collezione sarà mostrata. Tutte e tre le impostazioni che tratteremo in questa sezione possono essere trovate facendo click sulla scheda Modifica di una Collezione. Eredita Criteri Selezionando l’opzione Eredita Criteri, la Collezione erediterà i Criteri da una Collezione padre. Questo è utile solo quando si utilizzano Collezioni Subordinate. Se questa opzione è selezionata, è possibile creare un’altra Collezione che è più specifica rispetto al Padre, pur mantenendo i Criteri di base del Padre. Un semplice esempio potrebbe essere una Collezione Padre per la visualizzazione di tutti gli Eventi in un sito, e una Collezione Subordinata che visualizza Eventi (ereditando i Criteri) ma solo gli Eventi con una particolare parola chiave. Limita i Risultati della Ricerca Possiamo usare Limita i Risultati della Ricerca per limitare il numero di risultati che verranno visualizzati per pagina. In questo modo se abbiamo una Collezione che sta mostrando Notizie, siamo in grado di limitare i risultati a cinque o dieci, invece di mostrare tutte le Notizie in un singolo elenco di grandi dimensioni. Visualizza come Tabella Visualizza come Tabella è semplicemente un altro modo per visualizzare i risultati di una Collezione. Invece di avere una Collezione che mostra i risultati in una lista, possiamo generare una tabella con i risultati, e impostare esattamente le informazioni che desideriamo visualizzare sui risultati. Si può personalizzare la tabella selezionando Colonne della Tabella a partire da sinistra e facendo clic sul pulsante freccia destra per spostare l’indice sulla destra. Nell’esempio precedente abbiamo scelto di includere il Titolo dell’oggetto, i suoi Creatori e la Data di Accessibilità. È possibile utilizzare qualsiasi numero di colonne, o tutte se lo si vuole. Quando si considera cosa scegliere, bisogna tenere presente che non tutti gli oggetti disporranno delle informazioni per ogni colonna disponibile. Per esempio, la Data di Inizio e la Data di Fine valgono solo per gli Eventi. Pertanto, se si aggiungono queste colonne e la tabella include Pagine oltre agli Eventi allora le righe per le pagine non avrebbero le date di inizio e di fine compilate. L’altra cosa da considerare è che più colonne stai mostrando più affollata diventerà la tabella. La migliore regola è quella di visualizzare solo ciò che è assolutamente necessario. Alcune note ulteriori sulla selezione delle colonne: è possibile selezionarne più di una alla volta tenendo premuto il tasto (Ctrl) mentre si fa click. Se si desidera rimuovere una colonna, selezionarla a destra e fare clic sul pulsante freccia sinistra. Inoltre è possibile aggiungere e rimuovere le colonne con un doppio click sul loro nome. 1.7.4 Definizione dei Criteri Definizioni ed esempi dei vari campi criteri disponibili Il potere delle Collezioni si trova certamente nei campi dei criteri. Imparare come utilizzare i diversi Criteri vi permetterà di creare Collezioni molto utili. In questa sezione, useremo esempi per illustrare i molti modi di utilizzare i Criteri. Categorie Il criterio Categoria consente di ricercare il campo Categoria degli oggetti. Perchè funzioni è necessario aver specificato prima le Categorie per i contenuti (questo è fatto tramite la scheda Categorizzazione sugli oggetti contenuto). Un esempio in cui è possibile utilizzare questo campo è creare una Collezione che riporti tutti gli oggetti relativi alla Categoria Organizzazione. Siamo in grado di selezionare il valore Organizzazione per il nostro criterio. Quindi, salvando questo criterio e visualizzando la nostra Collezione, i risultati sarebbero tutti gli oggetti di contenuto che avevamo marcato con la Categoria Organizzazione. 128 Capitolo 1. Plone 4: Manuale utente
- 133. Documentazione di Plone, Release 4 Ancora una volta, i valori disponibili sono completamente dipendenti da ciò che abbiamo specificato sui nostri oggetti nella scheda Categorizzazione. Creatore Quando utilizziamo il criterio Creatore, stiamo creando un filtro sugli oggetti basato su chi li ha creati. Questo potrebbe essere utile se si vuole creare una sezione autore, in cui si desidera visualizzare solo i contenuti sul tuo sito che sono stati creati da un certo autore. Come potete vedere abbiamo diverse opzioni per questo tipo di criterio. Esse ci permettono di limitare il creatore alla persona attualmente connessa, immettere il nome di un altro utente come testo, oppure selezionare gli utenti da un elenco. Se si vuole visualizzare i risultati di più utenti, è necessario utilizzare l’opzione Elenco dei Valori. In caso contrario, si usa normalmente l’opzione Testo a meno che il creatore che si vuole selezionare sia voi stessi, in questo caso si utilizza Limita a Utente Attuale. Descrizione Il campo Descrizione è essenzialmente un criterio come il box di ricerca. Tuttavia, invece di cercare il titolo e il corpo di una pagina, effettuerà una ricerca solo per il testo nel campo Descrizione di un oggetto contenuto. Questo criterio è realmente utile solo se si compila il campo Descrizione in modo coerente per tutti gli oggetti contenuti. Posizione Utilizzare il criterio Posizione è molto simile a specificare una posizione nella ricerca di un documento sul disco rigido. Specificando un criterio Posizione, i risultati che vengono visualizzati nella tua Collezione provengono solo da quella posizione, più comunemente una Cartella. Questo può essere utile se si desidera visualizzare solo il contenuto che si trova nella sezione Chi siamo del sito, per esempio. Il criterio Posizione è anche utile per restringere risultati delle Collezioni quando è combinato con altri criteri. Per specificare una Posizione, è sufficiente fare click sul pulsante Aggiungi, si apre quindi una nuova finestra che mostra una directory del tuo sito. Se seguiamo il nostro esempio e vogliamo cercare la sezione Chi siamo del nostro sito, dobbiamo fare click sul pulsante Inserisci accanto alla cartella Chi siamo. È possibile aprire le cartelle per visualizzare i contenuti in essi contenute sia facendo clic sul pulsante Sfoglia o direttamente sul titolo della cartella che si desidera aprire. È inoltre possibile utilizzare la casella di ricerca per cercare il Titolo di un oggetto. Testo Ricercabile Il Testo Ricercabile è un criterio molto utile. È simile al box di ricerca sul tuo sito o un motore di ricerca Internet. Prende il testo che hai indicato, cerca il Titolo, la Descrizione, e il Corpo di tutti gli oggetti e restituisce quelli che hanno la parola o la frase specificata. Questo è utile quando si desidera trovare oggetti che hanno a che fare con una certa cosa, soprattutto se la parola o la frase appare in molti tipi di contenuto. Utilizzando LearnPlone.Org come esempio, se voglio creare una Collezione che consente di visualizzare tutti gli oggetti che fanno riferimento alla parola Collezioni, lo farei utilizzando il criterio Testo Ricercabile e specificando Collezioni. Tutti i Tutorial, Video, voci di Glossario, ecc con Collezioni nel Titolo, nella Descrizione, o nel Corpo del Testo dovrebbero poi comparire nei risultati delle Collezione. 1.7. Utilizzo delle collezioni 129
- 134. Documentazione di Plone, Release 4 Contenuti Correlati Il campo Contenuti Correlati è un altro campo, come Categoria, che deve essere specificato su un oggetto contenuto prima di essere utilizzato per una Collezione. Il campo Contenuti Correlati su un oggetto consente di specificare quali altri oggetti nel tuo sito sono simili o sono rilevanti per l’oggetto creato. Specificando questo campo quando si crea un oggetto, è possibile creare una rete di contenuti correlati che faranno riferimento a vicenda (si pensi a un tipo di funzione “vedi anche”). Una volta fatto questo, è possibile utilizzare il criterio Contenuti Correlati in una Collezione, per visualizzare tutto ciò che è collegato a un specifico oggetto. In questo caso abbiamo specificato che ci sono pagine relative a Nostro Staff, Storia, e la Homepage Chi siamo. Selezionando uno o più valori di questa lista, la nostra collezione visualizzerà le pagine legata a quel Valore. Se avessimo scelto la Storia come il valore, la nostra Collezione mostrerebbe tutto ciò che è legato alla pagina Cronologia. Tenete a mente che la lista di Valori Contenuti Correlati non funziona sulla base di quali oggetti sono legati al contenuto, ma su quali oggetti hanno un altro oggetto correlato ad esso. La Collezione visualizzerà i risultati relativi a tale valore. Stato Utilizzare il criterio Stato è molto semplice. Ci permette di fare una selezione in base allo stato pubblicato o privato. È una buona idea limitare le Collezioni agli elementi visibili pubblicamente impostando il filtro sullo stato pubblicato, in modo che i contenuti privati non appaiano nei risultati della Collezione. Può essere utile anche impostare il filtro sullo stato Privato. Per esempio, un amministratore del sito potrebbe desiderare di vedere rapidamente i contenuti privati, in modo da poter determinare quale lavoro deve essere ancora fatto e che cosa potrebbe essere cancellato. Date Avrete notato che sono disponibili parecchie date da utilizzare come Criteri. Poiché ci sono un grande numero di date, esse avranno una propria sezione nel manuale. 1.7.5 Impostazione del criterio di Ordinamento Ulteriori informazioni su come utilizzare la funzione di Ordinamento per personalizzare l’ordine in cui i risultati vengono visualizzati L’Ordinamento determina l’ordine dei risultati della Collezione. L’Ordinamento consente di ordinare su tre principali categorie: testo, proprietà degli oggetti, e date. Quando si ordina in base al testo, gli oggetti saranno ordinati in ordine alfabetico. Quando si ordina in base alle proprietà degli oggetti, stiamo effettivamente raggruppando gli oggetti attraverso le proprietà specificate. Quando si ordina per data i risultati saranno visualizzati con la data più recente per prima (anche se ci sono molte ‘date’ in Plone). Tutti gli Ordinamenti sono in Ordine Crescente a meno che il checkbox Ordine Inverso sia selezionato. Selezionandolo è possibile visualizzare in ordine inverso, o visualizzare prima le date più recenti, ecc. Date Ci sono numerose opzioni Data che saranno descritte nella prossima sezione del manuale. 130 Capitolo 1. Plone 4: Manuale utente
- 135. Documentazione di Plone, Release 4 Proprietà degli oggetti Tipo Quando si ordina per Tipo, si ottiene una Collezione che presenta i risultati raggruppati per Tipo. Vorremmo utilizzare questo Ordinamento se avessimo una Collezione che deve restituire molti Tipi diversi di elementi. In questo modo possiamo rendere la Collezione molto facile da navigare per il visitatore del sito. Stato L’Ordinamento per Stato visualizzerà i risultati raggruppandoli per lo stato di pubblicazione. Dal momento che ci sono solo due Stati nella configurazione di default di Plone, ci saranno solo le voci Pubblicato e Privato. Possiamo usare questo Ordinamento per separare tutte le pagine del nostro sito e vedere facilmente quello che è pubblico (Pubblicato) e ciò che si nasconde agli occhi del pubblico (Privato). Categoria L’Ordinamento Categoria è utile quando si desidera visualizzare gli oggetti del nostro sito raggruppati in base alla Categoria che li ha posti lì. Tenete a mente che è necessario aver specificato la Categoria su alcuni oggetti perché l’ordinamento per Categoria sia utile. Se non avete specificato alcuna Categoria, l’ordinamento per categorie non farà nulla. Correlato con L’Ordinamento Correlato con applicarà effettivamente un criterio alla tua Collezione. Esso limita i risultati a quelli che hanno l’informazione Correlato con specificata sulla loro proprietà. Testo Nome breve L’Ordinamento per il Nome Breve è simile all’ordine alfabetico. Di default Plone imposta il Titolo come Nome Breve di un oggetto. La differenza tra i due è che il Nome breve è tutto in minuscolo e ha trattini tra tutte le parole. Per esempio il Nome breve per la pagina dal titolo Chi siamo sarebbe chi-siamo. Il Nome breve è quello che Plone utilizza anche nell’URL della pagina (www.myplonesite.org/chi-siamo). È possibile specificare un diverso Nome Breve per un oggetto utilizzando il pulsante Rinomina nella scheda Contenuti. Creatore L’Ordinamento Creatore raggrupperà tutti i risultati in ordine alfabetico sul loro autore. Per esempio, diciamo che abbiamo diversi documenti pubblicati da Bob Baker e molti altri documenti pubblicati da Jane Smith. L’Ordinamento Creatore si tradurrebbe in tutti i documenti creati da Bob Baker elencati per primi, seguiti da quelli di Jane Smith. Titolo L’Ordinamento per Titolo visualizzarà i risultati in ordine alfabetico, sui Titoli. Nella prossima sezione tratteremo le date che abbiamo saltato in questa sezione e in quella sui Criteri. 1.7.6 Uso e comprensione delle Date Spiegazione delle Date associate alle Collezioni ed il loro uso Ci sono diversi tipi di date che possiamo scegliere, molti di esse sembrano simili. Per questo motivo è molto facile confondersi su quale data utilizzare. Di seguito è definita ogni opzione data. 1.7. Utilizzo delle collezioni 131
- 136. Documentazione di Plone, Release 4 Definizione delle Date Data di Creazione La Data di Creazione è la data in cui è stato fatto il documento. Si può pensare questa data come il suo compleanno, il giorno in cui è nato. Non è possibile modificare la Data di Creazione di un oggetto. Data di Accessibilità La Data di Accessibilità è la data in cui un oggetto viene pubblicato. Questo data è personalizzabile attraverso la scheda Modifica sugli oggetti sotto, la scheda Data. Tuttavia, in questa scheda essa è indicata come Data di Pubblicazione (un discrepanza secondaria nella nomenclatura di Plone). La Data di Creazione e la Data di Accessibilità sono molto simili. Entrambe rappresentano il punto di inizio di un oggetto. Un importante punto da tenere a mente quando si sceglie la data da utilizzare, è che un oggetto può essere creato molto prima che diventi pubblico. Una pagina potrebbe venire modificata per diverse settimane prima che sia effettivamente pubblicata. Quindi si dovrebbero avere risultati diversi in un Collezione a seconda di quale data è stato utilizzata. Si consiglia di utilizzare la Data di Accessibilità, invece della Data di Creazione per Collezioni basate sulle date. In questo modo la tua Collezione mostra i risultati sulla base di quando sono diventati visibili, il che è più rilevante per il pubblico della tua collezione. Inoltre, è possibile modificare la Data di Accessibilità per controllare l’ordinamento, cosa che non si può fare con la Data di Creazione. Data di Scadenza La Data di Scadenza si riferisce al giorno in cui la voce non sarà più pubblica. Questa data è anche personalizzabile attraverso la scheda Modifica (indicata sopra), come la Data di Accessibilità. Per impostazione predefinita, gli oggetti non hanno la Data di Scadenza. Data di Modifica La Data di Modifica è la data dell’ultima modifica dell’oggetto. Notare che questa data è prima impostata al giorno in cui l’oggetto viene creato e sarà cambiata automaticamente ogni volta che l’oggetto viene modificato. Non vi è alcun modo per personalizzarla. Per esempio, è possibile utilizzare questa data come Ordinamento insieme ad un criterio Tipo impostato su Pagina, per visualizzare tutte le pagine modificate di recente entro la settimana scorsa. L’elenco What’s New sulla homepage di LearnPlone.Org usa la Data di Modifica come criterio data. In questo modo i documenti appena creati e quelli che sono stati aggiornati appaiono nell’elenco. Date specifiche degli Eventi Le due seguenti date si applicano solo agli oggetti Eventi. Queste due date sono molto efficaci per la creazione di Collezioni Eventi Recenti e Prossimi Eventi che permetterà al tuo pubblico di conoscere ciò che la tua organizzazione sta facendo e farà in futuro. Data di Inizio La Data di Inizio è semplicemente la data da cui parte un evento. Data di Fine La Data di Fine è semplicemente la data in cui l’evento si conclude. Data di Pubblicazione La Data di Pubblicazione è la data in cui un oggetto è stato pubblicato l’ultima volta. Può essere impostata manualmente per mezzo del campo Data di Accessibilità o, se quest’ultima non è stato impostata, può essere calcolata in base alla data in cui oggetto è stato pubblicato l’ultima volta. Per visualizzare la Data di Pubblicazione sulle proprie pagine è necessario attivare l’opzione “Visualizza la data di pubblicazione nelle informazioni personali” nel **Pannello di Configurazione del Sito*. La Data di Pubblicazione sarà mostrata prima della Data di Modifica dell’oggetto all’interno dell’area informazioni personali. Per essere sicuri che tutto funzioni attivare anche l’opzione “Consenti a chiunque di vedere le informazioni personali” all’interno del Pannello di Impostazioni sicurezza. 132 Capitolo 1. Plone 4: Manuale utente
- 137. Documentazione di Plone, Release 4 Impostazione Date Una cosa che può causare confusione sulle date è come impostare i loro Criteri. Essi hanno una configurazione che non è come quella degli altri. Prima di tutto, devi scegliere se desideri una Data Relativa o un Intervallo di Date. La Data Relativa permette di costruire un’istruzione condizionale. Come ad esempio: gli articoli modificati da meno di 5 giorni nel passato. L’Intervallo di Date consente di specificare un determinato range di date, ad esempio dal 01/02/08 al 02/02/08. L’Intervallo di Date è utile quando si desidera creare una Collezione con una data statica che non cambierà. La Data Relativa può essere molto utile in quanto vi permetterà di creare Collezioni che sono automaticamente auto-aggiornate, come una Collezione News Recenti o una Sezione Prossimo Evento. Data Relativa Osservando per prima l’opzione Data Relativa, si nota che abbiamo tre opzioni da compilare. La prima opzione è Quale giorno. Questo ci permette di selezionare il numero di giorni che il nostro criterio comprenderà. Una delle opzioni è chiamata Adesso. L’utilizzo di questa opzione imposterà l’intervallo di date al giorno corrente. Le altre due opzioni non hanno importanza e possono essere ignorate quando si utilizza Adesso. La seconda opzione è Nel passato o nel futuro. Questo ci permette di scegliere se stiamo cercando in avanti o indietro nel tempo. L’ultima opzione è Prima o dopo. Qui si può scegliere tra tre opzioni. Minore di ci permette di includere tutto da ora a un periodo di tempo pari o inferiore all’impostazione Quale giorno, sia in passato che nel futuro. Maggiore di includerà tutto ciò oltre il nostro numero di giorni specificato, pari o superiore di Quale giorno. Infine In Giornata comprenderà solo gli oggetti del giorno che abbiamo specificato in Quale giorno. Utilizzando l’esempio nell’immagine qui sopra se avessimo selezionato In Giornata invece di Minore di la nostra Collezione mostrerebbe solo gli oggetti che sono stati modificati 5 giorni fa (stiamo usando il criterio Data di Modifica). Se questo per te è fonte di confusione, prova a leggerlo come una frase sostituendo nei campo le opzioni che hai scelto. “Voglio i risultati per includere oggetti Prima o dopo di Quale giorno, Nel passato o nel Futuro. Il nostro esempio diventerebbe “Voglio i risultati che includono gli oggetti Minore di 5 giorni nel passato”. Intervallo di Date L’Intervallo di Date è molto più facile da capire. Sono obbligatori sia una Data di Inizio che una Data di Fine (non confondere questi termini con le date specifiche dell’Evento!). L’Intervallo di Date ci permette di inserire un inizio e una fine e viene mostrato tutto ciò che è entro la suddetta finestra. Si noti anche che ci permette di specificare una determinata ora del giorno. 1.8 Gestione delle Portlet Una introduzione all’uso e alla gestione delle portlets. 1.8.1 Gerarchia delle Portlet Le Portlet utilizzano un approccio gerarchico che determina come e se devono apparire in ogni sezione del sito. Le Portlet utilizzano un approccio basato sulla gerarchia. Per impostazione predefinita, le portlets che assegni alla radice (home page) del sito si propagano verso tutte le sottosezioni dello stesso. Se desideri un diverso insieme di portlets o un ordinamento differente per una particolare sotto-sezione, dovrai utilizzare il controllo Blocca/sblocca portlets per “bloccare” le portlets ereditate dalla pagina superiore. Quando blocchi le Portlets, è necessario aggiungere esplicitamente tutte quelle che desideri vedere sulla pagina figlia. 1.8. Gestione delle Portlet 133
- 138. Documentazione di Plone, Release 4 La schermata di gestione delle portlets è stato aggiornato in Plone 4 per mostrare tutte le portlets incluso quelle bloccate. Gli utenti ora possono vedere ciò che è stato bloccato e ciò che è stato ereditato. Quando una portlet è bloccata, si noterà un sottile cambiamento di colore nella schermata di gestione portlet: Figura 1.34: Portlets bloccate nel pannello di gestione In questo schema, le nostre Portlets sono rappresentate in blu sotto il titolo della Pagina: Figura 1.35: hierarchy.gif Come puoi vedere abbiamo due Portlets nella nostra pagina iniziale (navigation and recent items). Entrambe appariranno nella pagina About a causa della gerarchia delle portlet. Tuttavia, nella pagina Documentation abbiamo aggiunto un terzo portlet - la Collection Portlet. Qui stiamo ancora permettendo la visualizzazione delle Portlet della pagina genitore ma in più abbiamo espressamente aggiunto la Collection Portlet. Su entrambe le pagine Tutorials e Videos dobbiamo bloccato le portlet ereditate dai genitori, perché non vogliamo che la Collection Portlet che si trova nella pagina Documentation venga mostrata. Quando blocchiamo le Portlet ereditate 134 Capitolo 1. Plone 4: Manuale utente
- 139. Documentazione di Plone, Release 4 dai Genitori dobbiamo ri-aggiungere le portlets a ogni pagina figlia. In questo caso ri-aggiungiamo la Navigation Portlet ad entrambi e successivamente la Search Portlet a tutti e due. Ricorda che le pagine figlie ereditano solo dalla loro pagina padre superiore. Nel nostro esempio, se aggiungiamo una pagina chiamata Staff sotto About e permettiamo le portlets del genitore senza aggiungerne altre, essa avrebbe mostrato le stesse portlets della Home Page così come quelle della pagina About. Tuttavia non pensare che siano ereditate dalla Home page. Se dovessimo cambiare la pagina About e aggiungere una Search Portlet, la nostra Pagina Staff rispecchierebbe le portlets nella pagina About e non quelle nella Home Page. 1.8.2 Gestione delle Portlets Come aggiungere, rimuovere e riordinare le portlets. Per iniziare a manipolare le portlets, è necessario trovare il link a Gestione Portlet, solitamente posizionato nella parte inferiore di ogni colonna laterale. In Gestione Portlet è possibile crearne di nuove, rimuoverle, rinominarle e riordinarle. Cliccando su questo link verremo portati ad una nuova pagina che ci permetterà di modificare le portlet. L’altro metodo per arrivare a questa schermata è quello di aggiungendo /@@manage-portlets alla fine dell’URL della pagina dove si vuole modificare le portlet. Ad esempio, per modificare le portlet della pagina About Us, l’URL deve diventare www.myplonesite.org/about/@@manage-portlets. 1.8. Gestione delle Portlet 135
- 140. Documentazione di Plone, Release 4 Aggiungere una Portlet Per aggiungere una Portlet basta semplicemente selezionare Aggiungi Portlet dalla casella a discesa e cliccare sul tipo che si desidera aggiungere. Le diverse opzioni disponibili saranno spiegate nella sezione successiva. Modificare una Portlet Esistente Per modificare le proprietà di una Portlet esistente è sufficiente fare click sul suo nome. Nell’esempio a sinistra, se volessimo modificare le proprietà della portlet di navigazione, si dovrebbe Cliccare su Navigazione. Ogni tipo di portlet avrà diverse opzioni di configurazione disponibili. Riodinare le Portlet Per modificare l’ordine delle Portlet è sufficiente fare click sulle frecce blu. visualizzazione delle portlet nella pagina. Questo influenzerà l’ordine di Rimuovere le Portlets Per rimuovere una Portlet, cliccare sulla “X” rossa di fianco al nome della stessa. 136 Capitolo 1. Plone 4: Manuale utente
- 141. Documentazione di Plone, Release 4 Nascondere le Portlets Da Plone 4 puoi visualizzare/nascondere le portlets utilizzando il rispettivo link visualizza/nascondi. Come avrai notato nella schermata “Gestisci Portlet”, puoi modificare le portlets sia sul lato destro sia su quello sinistro della pagina. Questo perché ci sono due colonne per le portlets, una a sinistra e una a destra. ** Le Portlets appariranno solo sul lato in cui vengono aggiunte**. E’ possibile aggiungere più di una portlet dello stesso tipo in una pagina. Non c’è nessun limite rispetto a quante volte possa essere utilizzata la stessa portlet o al numero di portlet per pagina. 1.8.3 I tipi di Portlets Descrizione dei tipi di Portlets disponibili Ci sono diversi tipi di Portlets da scegliere. A volte, il nome dei vari tipi, può essere ambiguo. Inoltre, alcuni possono essere configurati attraverso la Gestione Portlet e altri richiedono configurazioni attraverso la ZMI o la preventiva creazione di un oggetto. Di seguito è riportato un elenco con la descrizione base d’uso e delle funzionalità di ogni tipo di portlet disponibile. Navigazione La portlet di Navigazione permette agli utenti di navigare il sito con facilità fornendo una “mappa del sito” strutturata, o albero di navigazione. Hai la possibilità di configurare la portlet in modo tale che la navigazione mostri l’intero sito o scegliere solo di visualizzare il contenuto della cartella corrente. In LearnPlone.Org, è possibile vedere un esempio della Portlet di Navigazione nella colonna di sinistra. Addentrandosi nel sito, l’albero continuerà ad espandersi. Ci sono diverse opzioni disponibili per modificare il comportamento della Portlet di Navigazione. Calendario La portlet Calendario è molto semplice e permette di visualizzare un Calendario sul proprio sito. Questa portlet non ha opzioni personalizzabili. Se hai pubblicato degli oggetti eventi sul tuo sito, i giorni in cui si verificheranno saranno in grassetto e cliccandoci sopra si verrà indirizzati all’ evento corrispondente sul sito. Classico La Portlet Classico si riferisce al modo in cui sono state utilizzate nelle vecchie versioni di Plone, prima di Plone 3. È necessario creare un Page Template nella ZMI ed impostare correttamente il percorso e le macro per attivare la portlet. Questo richiede una conoscenza tecnica sia di TALES sia della ZMI. Collezione La Portlet Collezione ti permette di visualizzare i risultati di una Collezione. È necessario creare precedentemente una collezione e dopo aver aggiunto questa Portlet, si potrà specificare la Collezione da utilizzare. Questo è un ottimo modo per riassumere i risultati di una importante raccolta in modo che sia facilmente visibile al pubblico. Per le istruzioni sulla creazione di una Portlet Collezione seguire questo How-to. Eventi La Portlet Eventi mostrerà gli Eventi Futuri, a condizione che ci siano Eventi sul proprio sito. È possibile personalizzare il numero di eventi che si desidera visualizzare e specificare un filtro in base allo stato di pubblicazione. 1.8. Gestione delle Portlet 137
- 142. Documentazione di Plone, Release 4 Autenticazione La Portlet di Autenticazione è un’altra portlet non configurabile che semplicemente **visualizza la Form di Log in ** che consentirà agli utenti di autenticarsi. Una volta che un utente è loggato sul sito, questa Portlet verrà nascosta automaticamente. Notizie La Portlet Notizie funziona esattamente come la Portlet Eventi. Tuttavia invece che visualizzare Eventi, mostrerà le ultime Notizie. Nuovamente potrai personalizzare il numero di Notizie da visualizzare e filtrarle in base allo stato di pubblicazione. Flusso RSS La Portlet Flusso RSS ti permette di fare un link ad un Flusso RSS, di scegliere quante notizie visualizzare e di specificare il tempo di aggiornamento. Contenuti Recenti La Portlet Contenuti Recenti visualizza un numero personalizzabile di Contenuti Recenti, elencati per Titolo. Un Contenuto viene classificato Recente in base alla Data dell’ultima Modifica fatta. Elenco di Revisione La Portlet Elenco di Revisione visualizzerà un elenco di oggetti da revisionare. Se si utilizza un workflow dove è presente uno stato di revisione (e sono impostati correttamente i ruoli globali per gli utenti), questa portlet è molto comoda ai revisori per tenere sott’occhio quando un oggetto viene inviato per essere sottoposto a revisione. Questa Portlet appare solo ai revisori come per lo stato citato che non è visibile al pubblico. Ricerca La Portlet Ricerca visualizzerà una casella di ricerca nella colonna dove viene aggiunta. La ricerca del testo specificato avverrà nel titolo, nella descrizione e nel corpo degli oggetti del sito. C’è la possibilità di abilitare la Ricerca Istantanea che mostra i risultati durante la digitazione del testo da ricercare se il browser supporta JavaScript. Testo Statico La Portlet Testo Statico permette di inserire del testo come in una normale Pagina. E’ utile per aggiungere collegamenti ad altri siti o qualsiasi informazione statica. Un esempio è la Portlet “Ancora Perplessi?” sulla destra di questo sito. Per maggiori informazioni ed esempi vedere l’How-to Static Portlets. 138 Capitolo 1. Plone 4: Manuale utente
- 143. CAPITOLO 2 Altri manuali 2.1 Creare un tema con Diazo Questa guida fornisce una panaromica sull’uso di DIAZO per creare un tema in Plone. Date 27-11-2012 Translator Naldesi Impagination Giacomo Spettoli Source http://pypi.python.org/pypi/plone.app.theming 139
- 144. Documentazione di Plone, Release 4 Contents • Creare un tema con Diazo – Che cos’è un tema Diazo? – Uso del pannello di controllo * Selezionare un tema * Creare un nuovo tema * Caricamento di un tema esistente * Modifica del tema * Ispezione del tema * Il generatore delle regole * Impostazioni avanzate – Riferimenti * Sviluppo e test dei temi · Installazione sul filesystem · Installazione attraverso il web · Installazione come file zip · Installazione tramite un pacchetto Python (solo per programmatori) * Il file ‘manifesto’ * Sintassi delle regole · Selettori · Condizioni · Regole disponibili · rules · theme · replace · before · drop · merge · Modifiche avanzate * Parametri del tema * Debug del tema * Regole di uso comune * Uso avanzato di portal_css per la gestione del proprio CSS 2.1.1 Che cos’è un tema Diazo? Un “tema” definisce l’aspetto grafico e le modalità di interazione per un sito web (in questo caso un sito basato su Plone). Diazo (già conosciuto cone XDV) è una tecnologia utilizzabile per creare il tema di un sito web. Non è specifico per Plone, ma è stato creato dalla comunità Plone e, a partire dalla versione Plone 4.3, fornisce la modalità predefinita per l’applicazione di un tema ad un sito Plone. Per saperne di più: http://diazo.org. I temi Diazo possono esseri un po’ differenti da quelli creati in altri sistemi, ed anche dai temi creati per le precedenti versioni di Plone. Un tema Diazo è in realtà la trasformazione di contenuti – in questo caso l’output di un Plone “base” – in un diverso insieme di modelli HTML mediante l’applicazione di regole che combinano il modello HTML statico del risultato finale che si vuole ottenere con il contenuto dinamico proveniente da Plone. La precedente modalità per la creazione di un tema in un sito Plone (come pure la modalità presente in molti altri sistemi di gestione dei contenuti) si basa sulla sovrascrittura (overriding) selettiva di template e script che Plone utilizza per costruire una pagina con le versioni personalizzate che producono un diverso markup HTML. Quest’ultima strategia può risultare sicuramente più potente, ma richiede però una profonda conoscenza dei meccanismi interni di 140 Capitolo 2. Altri manuali
- 145. Documentazione di Plone, Release 4 Plone e dei comandi di tecnologie usate lato server come Zope Page Templates ed anche Python. I temi Diazo sono invece facili da capire per i progettisti web ed anche per chi non è sviluppatore. Un tema Diazo si compone di tre elementi: 1. Uno o più modelli HTML, indicati anche come file del tema, che rappresentano l’aspetto e l’interfaccia desiderati. Essi conterrano segnaposti per il contenuto che deve essere fonito dal sistema di gestione dei contenuti di Plone. I modelli fanno di solito riferimento a file CSS, JavaScript e di immagini con i relativi percorsi. La modalità più comune usata per creare un tema prevede l’utilizzo di software come Dreamweaver o di un editor di testo per impostare i relativi markup, stili e script, e testare poi localmente il tema in un browser web. 2. Il contenuto a cui il tema deve essere applicato. In questo caso si tratta dell’output da Plone. 3. Un file di regole, che definisce il modo in cui i segnaposti nel tema (cioè il modello HTML) dovranno essere sostituiti dal markup pertinente nel contenuto. Il file delle regole usa la sintassi XML (simile all’HTML). Questo è un semplice esempio: <?xml version="1.0" encoding="UTF-8"?> <rules xmlns="http://namespaces.plone.org/diazo" xmlns:css="http://namespaces.plone.org/diazo/css" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">‘ <theme href="theme.html" /> <replace css:content-children="#content" css:theme-children="#main" /> </rules> Nell’esempio si sostituiscono i contenuti (nodi figli) di un elemento segnaposto con id HTML main nel file del tema (theme.html, che si trova nella stessa directory del file rules.xml, come indicato nel riferimnto della regola <theme />) con i contenuti (figli) dell’elemento con l’id HTML content nel markup generato da Plone. Quando viene applicato questo tema, il risultato avrà un aspetto molto simile a quello del file HTML statico theme.html (ed ai suoi file di riferimento CSS, JavaScript ed immagini), eccezzion fatta per il segnaposto identificato nel tema dal nodo con id main che sarà riempito dall’area di contenuto principale di Plone. Plone viene fornito con un tema di esempio chiamato appunto Example theme, che usa il venerabile Twitter Bootstrap per costruire un tema semplice ma funzionale che espone la maggior parte delle funzionalità di Plone “base”. Si consiglia di studiarlo - in particolare il file rules.xml – per capire meglio come lavorano i temi Diazo. 2.1.2 Uso del pannello di controllo Dopo l’installazione del package ‘Diazo theme support’ in un sito Plone, nella pagina di configurazione del sito Plone comparirà il pannello di controllo Theming. La scheda principale, Themes, di questo pannello di controllo mostrerà tutti i temi disponibili, con i tasti comando per attivare/disattivare, modificare, copiare o cancellare ciascun tema, come pure i tasti comando per creare nuovi temi o far apparire il contenuto di questo documento. . Con un click sull’immagine con l’anteprima del tema si apre l’anteprima del tema in una nuova scheda o in una nuova finestra. L’anteprima è navigabile, ma l’invio di un form ed alcune funzioni avanzate non funzionano. 2.1. Creare un tema con Diazo 141
- 146. Documentazione di Plone, Release 4 Selezionare un tema Per applicare un tema esistente basta un click sul tasto comando Activate posizionato sotto l’anteprima del tema. Il tema attualmente attivo sarà evidenziato in giallo. Se il tema attivo viene disattivato, non risulterà applicato alcun tema Diazo, pertanto verrà applicato il tema “base” di Plone. n.b.: Al pannello di controllo Theming non si applica mai il tema, assicurando in tal modo che si potrà sempre disattivare un tema che genera errore e che potrebbe rendere inutilizzabile lo stesso pannello di controllo. Non si vedrà pertanto alcuna differenza immediatamente dopo l’abilitazione di un tema. Basta però passare a un’altra pagina del sito Plone e si dovrebbe vedere il tema applicato. Creare un nuovo tema I nuovi temi possono essere creati in due modi: • Nel pannello di controllo Theming, Click sul tasto comando New theme nella parte superiore della scheda Themes ed immettere un titolo e una descrizione nel form visualizzato. Verrà creata la struttura essenziale del tema, e verrà visualizzata la pagina Modify theme dove si potranno modificare o creare i file del tema e delle regole. • Click sul tasto comando Copy presente sotto ad ogni tema esistente e, nel form visualizzato, inserire il titolo e la descrizione del tema. Verrà creato un nuovo tema copia del tema esistente e verrà visualizzata la pagina Modify theme dove si potranno modificare o creare i file del tema e delle regole. Caricamento di un tema esistente I temi possono essere distribuiti come file Zip contenenti i file del modello HTML e delle regole. Per caricare un file esistente basta un click sul tasto comando Download presente sotto al tema nella scheda Themes del pannello di controllo di Theming. Per caricare un file di questo tipo in un altro sito si usa il tasto comando Upload Zip file nella scheda Themes del pannello di controllo di Theming. Si può scegliere se sostituire o meno un tema esistente ed avente lo stesso nome (in base al nome della directory di livello superiore contenuta all’interno del file Zip). Si può anche caricare il file di un modello statico HTML che non contiene il file delle regole, quale può essere per esempio un progetto fornito da un progettista che non è un praticante di Plone. In questo caso verrà aggiunto automaticamente un file di base (rules.xml) per permettere di iniziare a costruire un tema utilizzando la schermata Modify theme. Il file di regole generato assume che il file principale del modello HTML abbia nome index.html, che potrà comunque essere cambiato in rules.xml. Una volta caricato con successo un file Zip del tema, verrà presentata la schermata Modify theme dove si potrà modificare il file del tema o creare un nuovo file. Suggerimento: Se si riceve un messaggio di errore del tipo “Il file caricato non contiene un archivio valido di tema”, questo di solito significa che è stato caricato un file zip che contiene più file e cartelle, piuttosto che una singola cartella di livello superiore contenente tutte le risorse del tema. Ciò potrebbe accadere se è stato compresso un tema o un modello HTML aggiungendo i relativi file e cartelle direttamente in un archivio Zip, piuttosto che comprimere la directory in cui sono stati trovati. Per risolvere questo problema, è sufficiente decomprimere l’archivio in una nuova directory sul computer locale, salire di un livello, e comprimere questa directory da sola in un nuovo file Zip, che è poi possibile caricare. 142 Capitolo 2. Altri manuali
- 147. Documentazione di Plone, Release 4 Modifica del tema Si accede alla modifica di un tema con un click sul tasto comando Modify theme posto sotto al tema nella scheda Themes del pannello di controllo di Theming. Questa schermata viene aperta automaticamente quando si crea o si carica un nuovo tema. n.b.: Da Plone si possono modificare solo i temi creati o caricati dal pannello di controllo di Theming. Non possono invece essere modificati i temi installati dagli add-on di terze parti, anche se le modifiche apportate sul file system si rifletteranno immediatamente se Zope viene eseguito in modalità di debug . Per modificare un tema presente sul filesystem, si può copiarlo in un nuovo tema Plone con il tasto comando Copy presente sotto il tema nel pannello di controllo di Theming La schermata Modify theme mostra inizialmente un gestore di file con l’albero dei file sulla sinistra ed un editor sulla destra. Un Click su un file nell’albero dei file apre un editor o un’anteprima: file HTML, CSS, JavaScript ed altri file di testo possono essere visualizzati direttamente nell’editor. Altri file (p.es. immagini) saranno aperti in anteprima. N.b.: Nel browser Internet Exploredi Microsoft non è disponibile l’editor avanzato con la sintassi evidenziata. Un click su New folder per creare una nuova cartella. Questo si può ottenere anche con un click destro su una cartella dell’albero dei file. Un click su New file per creare un nuovo file. Questo si può ottenere anche con un click destro su una cartella dell’albero dei file. Un click su Upload file per caricare un file dal computer locale. Questo si può ottenere anche con un click destro su una cartella dell’albero dei file. Un click su Preview theme per per visualizzare in anteprima il tema secondo il modello e le regole attualmente salvate. L’anteprima è navigabile ma i form ed alcune funzionalità avanzate non funzionano. Per salvare le modifiche fatte nel file corrente, click sul tasto comando Save file oppure utilizzare i tasti di scelta rapida Ctrl+S (Windows/Linux) o Cmd+S (Mac). Per rinominare o cancellare un file o una cartella basta un click destro sull’elemento di interesse nell’albero dei file e si seleziona poi l’azione desiderata. Ispezione del tema Lo strumento di ispezione di un tema fornisce un’interfaccia avanzata per scoprire e costruire le regole di un tema Diazo. Può essere lanciato con il tasto comando Show inspectors presente nella schermata Modify theme per i temi propri di Plone, o con il tasto comando Inspect theme presente sotto ad un tema del filesystem nella scheda Themes del pannello di controllo di Theming. Lo strumento di ispezione di un tema è costituito da due pannelli: • Il mockup HTML. Se ci sono diversi file HTML in un tema, è possibile passare da uno all’altro utilizzando la lista a discesa posizionata sotto il pannello del modello HTML. • Il Unthemed content. Mostra Plone senza alcun tema applicato. La dimensione di entrambi i pannelli possono essere massimizzate con un click sulle icone delle frecce presenti in alto a destra in ciascun pannello. I pannelli HTML mockups ed Unthemed content possono passare alla vista sorgente e mostrare il codice HTML sottostante con un click sulle icone tag presenti in alto a destra in ciascun pannello. Posizionando il mouse sopra gli elementi nei pannelli del mockup HTML o del Unthemed content, si vedrà: • Un contorno che mostra l’elemento sotto il cursore. • Un selettore CSS o XPath nella barra di stato nella parte inferiore del pannello; il selettore identifica univocamente l’elemento in una regola Diazo. 2.1. Creare un tema con Diazo 143
- 148. Documentazione di Plone, Release 4 Click su un elemento o premere Enter quando il mouse è posizionato sopra un elemento per selezionarlo. L’ elemento selezionato più di recente in ciascun pannello viene mostrato nella barra di stato presente nella parte inferiore di ciascun pannello. Premendo Esc quando il mouse è posizionato sopra un elemento per selezionare il suo genitore. Ciò è utiite quando si cerca di selezionare elementi contenitori “non visibili”. Premere Enter per salvare la selezione. I contenuti del pannello del mockup HTML o (più comunemente ) di quello del Unthemed content sono navigabili, per ottenere per esempio una pagina di contento che richiede regole del tema specifiche disabilitando lo strumento di ispezione. Utilizzare i commutatori in basso a destra del pannello in questione per attivare o disattivare il selettore. Il generatore delle regole Usare il tasto comando Build rule nella parte superiore della schermata Modify theme o Inspect theme per lanciare la procedura guidata per la costruzione interattiva delle regole. Verrà richiesto il tipo di regola da costruire e quindi di selezionare, come richiesto, i relativi elementi nei pannelli del mockup HTML e/o di Unthemed content. Per impostazione predefinita, vengono utilizzate le selezioni salvate, a meno che non si deselezioni la casella Use selected elements nella prima pagina della procedura guidata. Al termine della procedura guidata, verrà mostrata la regola generata. Se si vuole, la regola può essere modificata. Con un click su Insert, la nuova regola generata viene inserita nell’editor di rules.xml in corrispondenza o vicino all’attuale posizione del cursore. È possibile spostare o modificare ulteriormente la regola a proprio piacimento. Click Preview theme per l’anteprima del tema in una nuova scheda o finestra. Se sono state fatte modifiche, ricordarsi di salvare il file rules.xml. N.b.: In modalità di solo lettura, si possono costruire regole ed ispezionare il modello HTML ed il tema ma non cambiare il file rules.xml file. In questo caso, anche il tasto comando Insert del generatore di regole non sarà disponibile. N.b.: Nel browser Internet Explorer di Microsoft non è disponibile la possibilità di inserire regole con la procedura guidata Build rule, anche se sarà data la possibilità di copiare la regola negli appunti quando si utilizza questo browser. Impostazioni avanzate Il pannello di controllo di Theming contiene anche una scheda con nome Advanced settings. E qui comincia l’avventura. La scheda Advanced settings è divisa in due aree. La prima, Theme details, contiene le impostazioni che vengono modificate quando viene applicato un tema dal pannello di controllo Themes. Queste sono: • Abilitazione dei temi Diazo. • Il percorso del file di regole, chiamato convenzionalmente rules.xml, sia relativo alla root del sito Plone o come percorso assoluto verso un server esterno. • Il prefisso da applicare per passare nei temi da percorsi relativi (p. es. i riferimenti ad immagini nell’attributo src del tag <img /> ) a percorsi assoluti in fase di visualizzazione dei contenuti. • Il DOCTYPE HTML da applicare all’output generato, se diverso dal valore predefinito XHTML 1.0 Transitional. • Se permettere o meno la lettura dalla rete delle risorse del tema (come rules.xml). Disattivare questa voce porta ad un modesto miglioramento delle prestazioni. • Una lista di nomi di host ai quali non viene mai applicato un tema. Spesso contiene 127.0.0.1, che consente di vedere, per esempio nella fase di sviluppo, un sito senza tema in http://127.0.0.1:8080 ed il sito con tema in http://localhost:8080. 144 Capitolo 2. Altri manuali
- 149. Documentazione di Plone, Release 4 • Una lista di parametri del tema e le espressioni TALES che li generano (vedi di seguito). Il secondo, Theme base, controlla la presentazioni dei contenuti senza l’applicazione di alcun tema, utilizzabile anche se non viene applicato alcun tema Diazo. Queste sono le impostazioni che si trovavano nel pannello di controlli di Themes nelle precedenti versioni di Plone. 2.1.3 Riferimenti Il resto di questa guida contiene materiale di riferimento utile per i realizzatori di temi. Sviluppo e test dei temi Per costruire e testare un tema, si deve prima creare un modello statico HTML con l’aspetto grafico e le modalità di interazione che si desiderano, e realizzare poi un file di regole per descrivere come il contenuto di Plone viene mappato nei segnaposto di questo modello. Il modello può essere creato ovunque con l’utilizzo dello strumento che si ritiene più adatto per la realizzazione di pagine web. Per semplificare l’integrazione con Plone, si raccomanda di essere certi che vengano usati i collegamenti relativi per le risorse quali file CSS, JavaScript ed immagini, in modo che siano visualizzati correttamente quando vengono aperti in un browser Web da un file locale. Plone convertirà automaticamente questi collegamenti relativi negli appropriati percorsi assoluti, assicurando così il corretto funzionamento del tema indipendentemente dll’URL visualizzato dall’utente quando il tema è applicato ad un sito Plone. Ci sono diversi modi per rendere disponibile il tema in Plone: Installazione sul filesystem Se si usa un’installatore o un “buildout” standard per allestire un sito Plone, dovrebbe allora essere presente una directory con nome resources nella root dell’installazione Plone (questa directory viene creata se si usa l’opzione resources nella ricetta del buildout plone.recipe.zope2instance. Vedi http://pypi.python.org/pypi/plone.recipe.zope2instance per maggiori dettagli) Dentro questa directory si può trovare (o creare) una directory theme che viene usata per contenere temi, Ciascun tema richiede una propria directory con un nome univoco. Se ne crea una (p. es. resources/theme/mytheme) e si inseriscono al suo interno i file HTML e ogni risorsa di riferimento. Se lo si desidera, si possono usare subdirectory, ma si consiglia di conservare i file HTML di base del tema nella parte superiore della cartella del tema. Sarà necessario anche un file di regole chiamato rules.xml all’interno della directory. Se non è già disponibile se ne crea uno vuoto: <?xml version="1.0" encoding="UTF-8"?> <rules xmlns="http://namespaces.plone.org/diazo" xmlns:css="http://namespaces.plone.org/diazo/css" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">‘ <theme href="theme.html" /> <replace css:content-children="#content" css:theme-children="#main" /> </rules> Se si esegue Zope in modalità debug (p. es.. è stato avviato con bin/instance fg), le modifiche fatte al tema e alle regole hanno effetto immediato. Si può avere un’anteprima o abilitare il tema attraverso il pannello di controlloThemes, e quindi modificare come si desidera ed in modo interattivo il file rules.xml o il modello del tema. 2.1. Creare un tema con Diazo 145
- 150. Documentazione di Plone, Release 4 Installazione attraverso il web Se lo si preferisce (o non si ha l’accesso al filesystem), si può creare completamente il tema dal pannello di controllo di Plone, sia per duplicazione di un tema esistente, sia partendo da zero con un tema quasi vuoto. Per maggiori dettagli si rimanda alle istruzioni sull’uso del pannello di controllo descritte precedentemente. Una volta creato, il tema può essere modificato dal pannello di controllo di Theming. Per maggiori dettagli si rimanda alle istruzioni descritte precedentemente. Installazione come file zip I temi possono essere scaricati da Plone come file Zip; questi file possono essere poi caricati in altri siti web. Per maggiori dettagli si rimanda alle istruzioni sull’uso del pannello di controllo descritte precedentemente. E’ infatti possibile creare archivi zip del tema validi, comprimendo la cartella di un tema presente su filesystem utilizzando uno strumento standard di compressione come 7-Zip o Winzip (per Windows) o l’azione Compress incorporata nel Mac OS X Finder. Bisogna solo essere certi di comprimere esattamente la cartella che contiene tutti i file del tema ed il file rules.xml. (Non comprimere direttamente i contenuti della cartella: il file zip quando viene scompattato deve produrre esattamente una cartella che a sua volta contiene i relativi file). Installazione tramite un pacchetto Python (solo per programmatori) Se si sta creando un pacchetto Python che contiene le personalizzazioni di Plone che si intendono installare nel sito, si può usarlo per registrare un tema da installare nel sito. Per fare questo si posiziona una directory, p. es. di nome. Theme,all’inizio del pacchetto, accanto al file Zope configure.zcml, ed si aggiunge una dichiarazione <plone:static /> nel file configure.zcml: <configure xmlns:plone="http://namespaces.plone.org/plone" xmlns="http://namespaces.zope.org/zope"> ... <plone:static name="mytheme" directory="theme" type="theme" /> ... </configure> Si noti la dichiarazione del namespace plone nell’elemento radice <configure />. I file del tema ed il file rules.xml vanno posizionati nella directory theme. Se il pacchetto ha un GenericSetup profile, si può abilitare dopo l’installazione di questo profilo aggiungendo nella directory profiles/default un file theme.xml contenente p. es.: <theme> <name>mytheme</name> <enabled>true</enabled> </theme> 146 Capitolo 2. Altri manuali
- 151. Documentazione di Plone, Release 4 Il file ‘manifesto’ E’ possibile dare ulteriori informazioni sul tema inserendo all’inizio della directory di un tema un file con nome manifest.cfg accanto al file rules.xml. Il file ha un aspetto di questo tipo: [theme] title = My theme description = A test theme Come si vede, il file ‘manifesto’ può essere utilizzato per fornire un titolo del tema più comprensibile ed una descrizione più lunga da usare poi nel pannello di controllo. E’ richiesta solo l’intestazione [theme] – tutte le altre chiavi sono opzionali. Si può anche impostare: rules = http://example.org/myrules.xml per usare un nome per il file delle regole diverso da rules.xml (si deve fornire un URL o un percorso relativo). Per cambiare l prefisso per il percorso assoluto (vedi Impostazioni avanzate), si usa: prefix = /some/prefix Per impiegare un DOCTYPE diverso da XHTML 1.0 Transitional per il contenuto a cui viene applicato il tema, aggiungere p. es.: doctype = html Per visualizzare nel pannello di controllo Theming un’anteprima user-friendly del tema, aggiungere: preview = preview.png preview.png è il file di un’immagine relative to the location del file manifest.cfg. Estensioni del motore di Diazo possono aggiunger il supporto per ulteriori blocchi di parametri configurabili. Sintassi delle regole Nel seguito un breve sommario della sintassi delle regole di Diazo. Vedi http://diazo.org per maggiori dettagli ed altri esempi. Selettori Ciascuna regola è composta da un tag XML che opera su uno o più elementi HTML nel contenuto e /o sul tema. Gli elementi su cui operare sono indicati da attributi delle regole noti come selettori. Il modo più semplice per selezionare gli elementi è quello di utilizzare una espressione selettore CSS, come ad esempio css:content=”#content” o css:theme=”#main .content”. Si può utilizzare una qualsiasi espressione CSS3 valida (inclusi pseudo-selettori quali:first-child). I selettori standard, css:theme e css:content, operano sull’elemento/i che soddisfano la selezione. Se invece si vuole operare sui figli degli elementi selezionati si deve usare css:theme-children=”...” o css:content-children=”...”. Se non è possibile costruire una espressione CSS 3 adeguata, è possibile utilizzare espressioni XPath come content=”/head/link” o theme=”//div[@id=’main’]” (si noti la mancanza di un prefisso css: quando si usano le espressioni 2.1. Creare un tema con Diazo 147
- 152. Documentazione di Plone, Release 4 XPath). I due approcci sono equivalenti, e si possono combinare liberamente, ma non si può avere ad esempio sia un css:theme ed un attributo theme nella stessa regola. Per operare sui figli di un nodo selezionato con un’espressione XPath si può usare theme-children=”...” o content-children=”...”. Per approfondire XPath vedi http://www.w3schools.com/xpath/default.asp. Condizioni Per impostazione predefinita, ogni regola viene eseguita, anche se le regole a cui non corrispondono elementi non modificano nulla nella pagina attuale. Si può creare una regola, un’insieme di regole o un riferimento al tema (vedi sotto) a condizione che un elemento sia presente nel contenuto, aggiungendo un attributo alla regole del tipo css:ifcontent=”#some-element” (per usare invece un’espressione XPath, eliminare il prefisso css: ). La regola viene ignorata se nessun elemento soddisfa l’espressione. Suggerimento: se una regola <replace /> corrisponde a un elemento nel tema, ma non nel contenuto, il nodo tema sarà eliminato e non sostituito. Se non si desidera questo comportamento e non si è sicuri se il contenuto conterrà l’elemento/i in questione, è possibile utilizzare la regola condizionale css:if-content. Poiché questa è una situazione comune, è disponibile una scorciatoia: css:if-content=”” che significa “usare l’espressione dall’attributo css:content”. Allo stesso modo è possibile creare una condizione in base al percorso della richiesta corrente utilizzando un attributo del tipo if-path=”/news” (si noti l’assenza di css:if-path ). Se questo percorso inizia con una barra (/), l’eventuale corrispondenza sarà con la fine dell’URL. Si può impostare un percorso assoluto usando un barra iniziale ed una finale (/..../). Si possono infine usare espressioni XPath arbitrarie invece di una variabile definita, con un attributo del tipo if=”$host = ‘localhost”’ . Per impostazione predefinita, sono disponibili le variabili url , scheme , host e base che rappresentano l’URL attuale. I temi possono definire ulteriori variabili nei rispettivi manifesti. Regole disponibili Di seguito il riassunto dei vari tipi di regole. rules <rules> ... </rules> Racchiude un insieme di regole. Deve essere utilizzato come elemento radice del file delle regole. <rules /> nidificato può essere utilizzato assieme ad una condition per applicare una singola condizione ad un’insieme di regole. Quando viene utilizzato come elemento radice del file delle regole, debbono essere dichiarati i vari namespace XML: <rules xmlns="http://namespaces.plone.org/diazo" xmlns:css="http://namespaces.plone.org/diazo/css" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> ... </rules> 148 Capitolo 2. Altri manuali
- 153. Documentazione di Plone, Release 4 theme <theme href="theme.html" /> <theme href="news.html" if-path="/news" /> <notheme if="$host = ’admin.example.org’" /> Sceglie il file del tema da utilizzare. L’attributo href è un percorso relativo a file di regole. Se sono presenti più elementi <theme />, solo per uno di essi può essere assente una condizione. Verrà utilizzato il primo tema con una condizione che sia vera, con il tema senza condizioni utilizzato come riserva. <notheme /> può essere usato per specificare una condizione che non prevede l’uso di alcun tema. <notheme /> ha la precedenza su <theme />. Suggerimento: Per essere sicuri di non applicare gli stili a pagine non Plone, aggiungere all’ultimo tema della lista una condizione del tipo css:if-condition=”#visual-portal-wrapper”, e non inserire alcun tema senza condizione. replace <replace css:content="#content" css:theme="#main" /> Sostituisce gli elementi che soddisfano la regola nel tema con i corrispondenti che soddisfano la regola nel contenuto. before <before css:content-children="#portal-column-one" css:theme-children="#portlets" /> <after css:content-children="#portal-column-two" css:theme-children="#portlets" /> Inserisce gli elementi che soddisfano la regola nel contenuto prima o dopo i corrispondenti nel tema. Utilizzando theme-children , si possono inserire gli elementi del contenuto selezionati all’inizio (prepend) o alla fine (append) all’interno dei corrispondenti elementi che soddisfano la regola nel tema. drop <drop css:content=".documentByLine" /> <drop theme="/head/link" /> <drop css:theme="#content *" attributes="onclick onmouseup" /> <strip css:content="#parent-fieldname-text" /> Rimuove gli elementi dal tema o dal contenuto. Si noti che a differenza di altre regole, una regola <drop /> o <strip /> può operare sul theme o sul content , ma non su entrambi. <drop /> rimuove gli elementi corrispondenti ed i relativi figli, mentre <strip /> rimuove gli elementi corrispondenti ma non i relativi figli. A <drop /> può essere data una lista di attributes da rimuovere separati da spazi bianchi. In questo caso gli elementi corrispondenti non saranno rimossi. Usando attributes=”*” si rimuovono tutti gli attributi. merge 2.1. Creare un tema con Diazo 149
- 154. Documentazione di Plone, Release 4 <merge attributes="class" css:content="body" css:theme="body" /> <copy attributes="class" css:content="#content" css:theme="#main" /> Queste regole operano sugli attributi. <merge /> aggiungerà i contenuti letti nel tema per gli attributi indicati, ai valori di ogni attributo esistente nel contenuto avente lo stesso nome; i valori sono separarti da spazi bianchi. E’ principalmente usato per aggiungere classi CSS. <copy /> copia gli attributi dagli elementi che soddisfano la regola nel contenuto, nei corrispondenti elementi nel tema; gli attributi con lo stesso nome eventualmente già presenti nel tema, vengono completamente sostituiti. L’attributo attributes può contenere una lista di attributi separati da spazi bianchi, oppure il valore speciale * per operare su tutti gli attributi degli elementi che soddisfano la regola. Modifiche avanzate Invece di selezionare il markup da inserire nel tema dal contenuto, è possibile inserire il markup direttamente nel file delle regole, come nodi figlio dell’elemento della relativa regola: <after css:theme="head"> <style type="text/css"> body > h1 { color: red; } </style> </after> Nello stesso modo si può operare sul contenuto. E’ così possibile modificarlo prima dell’applicazione delle regole: <replace css:content="#portal-searchbox input.searchButton"> <button type="submit"> <img src="images/search.png" alt="Search" /> </button> </replace> Oltre ad aggiungere in questo modo HTML statico, si possono usare le istruzioni XSLT che operano sul contenuto. In XSLT, si possono anche usare direttamente i selettori css: <replace css:theme="#details"> <dl id="details"> <xsl:for-each css:select="table#details > tr"> <dt><xsl:copy-of select="td[1]/text()"/></dt> <dd><xsl:copy-of select="td[2]/node()"/></dd> </xsl:for-each> </dl> </replace> Utilizzando l’attributo href per specificare il percorso di una risorsa relativamente alla root del sito Plone, le regole possono operare su contenuti provenienti da sorgenti che non siano l’attuale pagina restituita da Plone: <after css:theme-children="#leftnav" 150 Capitolo 2. Altri manuali
- 155. Documentazione di Plone, Release 4 css:content=".navitem" href="/@@extra-nav" /> Parametri del tema E’ possibile passare al tema parametri arbitrari a cui si può far riferimento come a variabili nelle espressioni di XPath. I parametri possono essere impostati nel pannello di controllo Theming di Plone e possono anche venire importati da un file manifest.cfg. Si potrebbe avere, per esempio, un parametro mode impostabile con la stringa live o test. Nelle proprie regole si potrebbe fare qualcosa del genere per inserire un avviso visualizzato quando si lavora sul server di prova: <before css:theme-children="body" if="$mode = ’test’"> <span class="warning">Attenzione: questo è il server di prova</span> </before> Si può usare anche direttamente il valore del parametro, p. es..: <before css:theme-children="body"> <span class="info">Questo è il server di <xsl:value-of select="$mode" /> </span> </before> I seguenti parametri sono sempre disponibili per i temi Plone: scheme Il nome dello schema dell’URL in entrata (la parte che precede i due punti), normalmente http o https. host Il nome, nell’URL in entrata, del server che ha inviato i dati. path Il segmento dell’URL in entrata relativo al percorso. Non include alcun virtual hosting tokens, è cioè il percorso visto dall’utente finale. base Il Zope base url (la variabile BASE1 di una request a Zope). Si possono aggiungere ulteriori parametri dal pannello di controllo utilizzando espressioni TALES. I parametri sono elencati, uno per riga, nella scheda Advanced nel formato <name> = <expression>. Se, per esempio, si vuole evitare di applicare il tema ad ogni pagina caricata dai diversi livelli (overlays) di Plone, si può far uso del parametro ajax_load della request parameter impostato dai livelli (overlays). In questo caso ii file delle regole includerebbe: <notheme if="$ajax_load" /> Per aggiungere questo parametro come pure il parametro mode descritto in precedenza, è possibile aggiungere quanto segue nel pannello di controllo: ajax_load = python: request.form.get(’ajax_load’) mode = string: test La parte destra presenta un’espressione TALES . Deve restituire un valore di tipo string, integer, float, boolean o None: le liste, i dizionari e gli oggetti non sono supportati. python:, string: ed espressioni di percorso funzionano come nei Zope Page Templates. Sono disponibili le seguenti variabili quando si costruiscono queste espressioni TALES: context Il contesto dell’attuale request, normalmente un oggetto contenuto. request L’attuale request. 2.1. Creare un tema con Diazo 151
- 156. Documentazione di Plone, Release 4 portal L’oggetto radice del portale. context_state La vista @@plone_context_state, da cui è possibile cercare altri valori come l’URL del contesto o la vista predefinita. portal_state La vista @@plone_portal_state, da cui è possibile cercare altri valori come la root dell’URL di navigazione o se l’utente attuale è collegato (autenticato?) o meno. Vedi plone.app.layout per i dettagli circa le viste @@plone_context_state e @@plone_portal_state. I parametri del tema sono normalmente parte integrante di un temaTheme e saranno pertanto impostati in base al manifesto del tema quando il tema viene importato od abilitato. Questo è fatto utilizzando la sezione [theme:parameters] nel file manifest.cfg. Per esempio: [theme] title = My theme description = A test theme [theme:parameters] ajax_load = python: request.form.get(’ajax_load’) mode = string: test Debug del tema Quando Zope è in modalità sviluppo (cioè esecuzione in foreground in una console con bin/instance fg), il tema sarà ricompilato ad ogni request. Se la modalità non è di sviluppo viene compilato al primo accesso, poi ricompilato solo se vengono cambiati i valori del pannello di controllo. Anche nella fase di sviluppo è possibile disabilitare temporaneamente il tema aggiungendo alla request una query string con il parametro diazo.off=1. Per esempio: http://localhost:8080/Plone/some-page?diazo.off=1 Il parametro viene ignorato se la modalità non è di sviluppo. Regole di uso comune Le ricette che seguono mostrano le regole di uso comune nella costruzione di temi per Plone: Per copiare il titolo della pagina: <replace css:theme="title" css:content="title" /> Per copiare il tag <base /> (necessario perchè funzionino i link di Plone): <replace css:theme="base" css:content="base" /> Se non è presente nel tema il tag <base />, si può procedere così: <before css:theme-children="head" css:content="base" /> Per eliminare dal tema tutte le risorse relative agli stili ed a JavaScript e copiarle invece dallo strumento di Plone portal_css: 152 Capitolo 2. Altri manuali
- 157. Documentazione di Plone, Release 4 <!-- elimina gli stili in head - questi vengono aggiunti nuovamente includendo quelli di Plone --> <drop theme="/html/head/link" /> <drop theme="/html/head/style" /> <!-- inserimento dei CSS di Plone --> <after theme-children="/html/head" content="/html/head/link | /html/head/style" /> Per copiare le risorse JavaScript di Plone: <!-- inserimento degli script di Plone --> <after theme-children="/html/head" content="/html/head/script" /> Per copiare la classe del tag <body /> (necessaria per il corretto funzionamento di alcune funzioni e di alcuni stili JavaScript di Plone): <!-- Body --> <merge attributes="class" css:theme="body" css:content="body" /> Uso avanzato di portal_css per la gestione del proprio CSS I “registri delle risorse” di Plone, incluso lo strumento portal_css, possono essere utilizzati per gestire i fogli di stile CSS. Questa opportunità offre diversi vantaggi rispetto al semplice collegamento ai propri fogli di stile nel template, come: • Controllo dettagliato sull’ordine dei fogli di stile • L’unione dei fogli di stile per ridurre il numero di download necessari per la presentazione di una pagina • Compressione On-the-fly del foglio di stile (ad esempio con rimozione degli spazi bianchi) • La possibilità di includere od escludere un foglio d stile in base ad un’espressione E’ spesso desiderabile (e qualche volta assolutamente necessario) lasciare intatto il file del tema, ma è comunque possibile utilizzare portal_css per gestire i fogli di stile. Il trucco consiste in: • Registrare i propri stili del tema con lo strumento di Plone portal_css (questo è normalmente meglio farlo quando si inserisce un tema in un pacchetto di Pyton - attualmente non esiste un modo per fare questo automaticamente per un tema importato da un file Zip o creato attraverso il web) • Eliminare gli stili del tema con una regola e quindi – Includere tutti gli stili da Plone Si potrebbero, per esempio, aggiungere le seguenti regole: <drop theme="/html/head/link" /> <drop theme="/html/head/style" /> <!-- Pull in Plone CSS --> <after theme-children="/html/head" content="/html/head/link | /html/head/style" /> 2.1. Creare un tema con Diazo 153
- 158. Documentazione di Plone, Release 4 L’uso per il contenuto di un’espressione “or” nella regola <after /> indica che viene mantenuto l’ordine relativo degli elementi link e style. Per registrare i fogli di stile al momento dell’installazione del prodotto mediante GenericSetup, bisogna usare il passo di importazione di cssregistry.xml nella directory del proprio GenericSetup profiles/default: <?xml version="1.0"?> <object name="portal_css"> <!-- Imposta le condizioni relative ai fogli di stile che non si vogliono includere --> <stylesheet expression="not:request/HTTP_X_THEME_ENABLED | nothing" id="public.css" /> <!-- aggiunge i nuovi fogli di stile --> <stylesheet title="" authenticated="False" cacheable="True" compression="safe" conditionalcomment="" cookable="True" enabled="on" expression="request/HTTP_X_THEME_ENABLED | nothing" id="++theme++my.theme/css/styles.css" media="" rel="stylesheet" rendering="link" applyPrefix="True" /> </object> C’è però una cosa importante da cui stare in guardia. I propri fogli di stile possono includere dei riferimenti ad URL relativi nella forma seguente: background-image: url(../images/bg.jpg); Se il foglio di stile è posizionato in una directory di risorse (ad esempio è registrato in portal_css con l’id ++theme++my.theme/css/styles.css), questo funziona bene fino a quando il registro (e Zope) è in modalità di debug . L’URL relativo sarà tradotto dal browser in ++theme++my.theme/images/bg.jpg. Tuttavia, è possibile che l’URL relativo non funzioni quando il Registro di sistema viene messo in modalità di produzione. Questo perché l’unione delle risorse cambia anche l’URL del foglio di stile in qualcosa del tipo: /plone-site/portal_css/Suburst+Theme/merged-cachekey-1234.css 1. 1.Per correggere questo, si deve impostare in cssregistry.xml il flag applyPrefix a true quando si installano le proprie risorse CSS. Esiste un flag corrispondente nell’interfaccia utente di portal_css. Qualche volta è utile mostrare alcuni CSS di Plone nel sito. Questo si può ottenere usando una regola Diazo <after /> o in modo simile copiare nel tema i CSS dall’<head /> generato da Plone. Si può utilizzare lo strumento portal_css per disattivare i fogli di stile indesiderati. Però, se si vuole che il sito sia usabile anche in modalità senza tema (per esempio in un URL separato), si potrebbe voler abilitare un insieme più ampio di stili quando Diazo non viene utilizzato. Per facilitare questa operazione, è possibile utilizzare le seguenti espressioni come condizioni nello strumento portal_css (ed eventualmente in portal_javascripts), in portal_actions, nei page template, ed in altri posti che usano la sintassi delle espressioni TAL: request/HTTP_X_THEME_ENABLED | nothing L’espressione restituisce True se Diazo è attualmente abilitato, nel qual caso sarà impostato un header HTTP “XTheme-Enabled”. 154 Capitolo 2. Altri manuali
- 159. Documentazione di Plone, Release 4 Se in seguito si distribuisce il tema ad un server Web frontale come per esempio nginx, si può impostare lì lo stesso header della request per ottenere un egual risultato anche se plone.app.theming non è installato. Utilizzare: not: request/HTTP_X_THEME_ENABLED | nothing per ‘nascondere’ un foglio di stile dal sito a cui è applicato il tema. 2.2 ZODB - un database nativo ad oggetti per Python Non schiacciare i tuoi oggetti nelle tabelle: memorizzali in un database ad oggetti Data 29-01-2012 Traduzione Giacomo Spettoli Impaginazione Giacomo Spettoli Revisione 2.2.1 Panoramica I programmi Python sono scritti seguendo il paradigma orientato agli oggetti. Si utilizzano gli oggetti che fanno riferimento l’un l’altro liberamente e possono essere di qualsiasi forma e dimension: nessun oggetto deve aderire ad uno schema specifico e può contenere informazioni arbitrarie. Memorizzare quegli oggetti nei database relazionali richiede di rinunciare alla libertà dei riferimenti e dello schema. I vincoli del modello relazionale riducono la capacità di scrivere codice orientato agli oggetti. Lo ZODB è un database nativo ad oggetti, che memorizza i vostri oggetti e consente di lavorare con qualsiasi paradigma che si può esprimere in Python. In tal modo il vostro codice diventa più semplice, più affidabile e facile da capire. Inoltre, non esiste un divario tra il database e il programma: nessun codice-colla per scrivere, nessuna mappatura da configurare. Date un’occhiata al tutorial per vedere, come è facile. Alcune delle funzionalità che lo ZODB ti dà sono: • persistenza trasparente degli oggetti Python • supporto alle transazioni pienamente compatibile ACID (inclusi i savepoints) • abilità di avere uno storico e la possibilità di annullare • supporto efficiente per oggetti binari di grandi dimensioni (BLOB) • sistemi di storage innestabili • architettura scalabile 2.2.2 Documentazione Tutorial Questo tutorial ha lo scopo di guidare gli sviluppatori con un’introduczione passo-passo allo sviluppo un’applicazione che memorizza i dati nel ZODB. 2.2. ZODB - un database nativo ad oggetti per Python 155
- 160. Documentazione di Plone, Release 4 Introduzione Diamo un’occhiata a un semplice pezzo di codice che vogliamo modificare per poter utilizzare lo ZODB: class Account(object): def __init__(self): self.balance = 0.0 def deposit(self, amount): self.balance += amount def cash(self, amount): assert amount < self.balance self.balance -= amount Questo codice definisce una semplice classe che mantiene il saldo di un conto bancario e fornisce due metodi per manipolare il saldo: deposito e prelievo di contanti. Installazione Prima di poter utilizzare lo ZODB dobbiamo installarlo, usando easy_install. Notare che il vero nome del pacchetto è “ZODB3”: $ easy_install ZODB3 ... $ python >>> import ZODB Ora lo ZODB è ora installato e può essere importato dalla vostra installazione Python. Se non si ha a disposizione easy_install sul proprio sistema, seguire le Istruzioni per l’installazione di EasyInstall. Ci sono altri meccanismi di installazione disponibili per gestire il l’installazione dei pacchetti Python. Questo tutorial assume che si stia utilizzando un’installazione base di Python e che lo ZODB sia installato globalmente. Configurazione Quando un programma vuole utilizzare lo ZODB deve stabilire una connessione, come per qualsiasi altro database. Per lo ZODB abbiamo bisogno di 3 diverse parti: uno storage, un database e infine una connessione: >>> >>> >>> >>> >>> >>> from ZODB.FileStorage import FileStorage from ZODB.DB import DB storage = FileStorage(’Data.fs’) db = DB(storage) connection = db.open() root = connection.root() Creiamo un storage chiamato Filestorage, che è l’attuale standard di memorizzazione usato praticamente da tutti. Esso tiene traccia di tutti i dati in un singolo file, come dichiarato dal primo parametro. Da questo storage creiamo un database e poi apriamo una connessione. Infine, recuperiamo l’oggetto root del database attraverso la connessione che abbiamo aperto. 156 Capitolo 2. Altri manuali
- 161. Documentazione di Plone, Release 4 Memorizzare gli oggetti Per memorizzare un oggetto nello ZODB, lo colleghiamo semplicemente a qualsiasi altro oggetto che è già presente nel database. Quindi, l’oggetto root funziona come un punto di partenza. L’oggetto root è un dizionario e si può iniziare a memorizzare gli oggetti direttamente da lì: >>> root[’account-1’] = Account() >>> root[’account-2’] = Account() I framework come Zope creano solamente un singolo oggetto nella radice dello ZODB che rappresenta l’applicazione stessa e poi referenziano tutti gli altri oggetti da lì. Essi scelgono nomi come ‘app’ per il primo oggetto che posizionano nello ZODB. Transazioni Ora abbiamo due oggetti posizionati nel oggetto root e nel nostro database. Tuttavia, essi non sono ancora memorizzati in modo persistente. Lo ZODB utilizza le transazioni e per rendere permanenti le modifiche, è quindi necessario il commit della transazione: >>> import transaction >>> transaction.commit() >>> root.keys() [’account-1’, ’account-2’] Ora possiamo stoppare e riavviare l’applicazione e guardare di nuovo all’oggetto root. Vedremo che le voci ‘account-1’ e ‘account-2’ sono ancora presenti e sono gli oggetti che abbiamo creato. Gli oggetti che non sono ancora stati memorizzati nello ZODB non vengono rimossi da un abort. Se l’applicazione apporta delle modifiche durante una transazione ma scopre che non vuole fare il commit di quelle modifiche, allora si può annullare la transazione e le modifiche vengono annullate per noi: >>> del root[’account-1’] >>> root.keys() [’account-2’] >>> transaction.abort() >>> root.keys() [’account-1’, ’account-2’] Oggetti persistenti Un ultimo aspetto che dobbiamo coprire sono gli stessi oggetti persistenti. Lo ZODB sarà lieto di memorizzare quasi qualsiasi oggetto Python che gli viene passato (ma non memorizzerà i file per esempio). Ma per capire quali oggetti sono stati modificati, lo ZODB ha bisogno che quegli oggetti collaborino con il database. In generale, per fare ciò basta ereditare da persistent.Persistent. Quindi la nostra classe di esempio sopra andrebbe modificata così: import persistent class Account(persistent.Persistent): # ... same code as above ... Date un’occhiata alla documentazione di riferimento per saperne di più sulle regole di persistenza e sugli oggetti specializzati come i BTrees. 2.2. ZODB - un database nativo ad oggetti per Python 157
- 162. Documentazione di Plone, Release 4 Sommario Abbiamo visto come installare lo ZODB, come aprire un database nella nostra applicazione e come iniziare a memorizzare gli oggetti al suo interno. Abbiamo anche accennato ai due semplici comandi per le transazioni: commit e abort. La documentazione di riferimento contiene le sezione con maggiori informazioni sugli specifici argomenti. Guida alla programmazione dello ZODB Questa guida si basa in gran parte sul lavoro di AM Kuchling che scrisse la guida originale nel 2002 e che fu pubblicata sotto la GNU Free Documentation License, Versione 1.1. Vedere l’appendice intitolata “GNU Free Documentation License” per ulteriori informazioni. Contenuti Introduzione Questa guida spiega come scrivere programmi Python che utilizzano Z Object Database (ZODB) e Zope Enterprise Objects (ZEO). L’ultima versione di questa guida è sempre disponibile su http://www.zope.org/Wikis/ZODB/guide/index.html. Cos’è lo ZODB? Lo ZODB è un sistema di persistenza di oggetti Python. I linguaggi di programmazione persistenti forniscono strutture che scrivono automaticamente gli oggetti sul disco e li rileggono quando sono richiesti durante l’esecuzione del programma. Installando lo ZODB abbiamo aggiunto queste strutture a Python. Certamente è possibile costruire un proprio sistema per rendere gli oggetti Python persistenti. Il punto iniziale di solito è il modulo pickle, per convertire gli oggetti in una rappresentazione di stringa, e vari moduli per i database, come i moduli gdbm o bsddb che forniscono dei modi per scrivere queste stringe sul disco e rileggerle. È semplice combinare il modulo pickle e un modulo per i database per memorizzare e recuperare gli oggetti, e in effetti il modulo shelve, incluso nella libreria standard di Python, fà proprio questo. Lo svantaggio è che il programmatore deve gestire in modo esplicito gli oggetti, la loro lettura quando è necessario e la loro scrittura su disco quando non sono più richiesti. Lo ZODB gestisce gli oggetti per noi, scrivendoli su disco quando vengono modificati, e rimuovendoli dalla cache quando non vengono utilizzati per qualche tempo. OODBs vs. DB Relazionali Un altro modo di vedere le cose è che lo ZODB è un database orientato agli oggetti specifico per Python (OODB). I database ad oggetti commerciali per C++ e Java spesso richiedono di saltare attraverso alcuni cerchi, come dover utilizzare uno speciale preprocessor o essere costretti ad evitare certi tipi di dati. Come vedremo, anche lo ZODB ha alcuni cerchi da saltare ma in confronto la naturalezza dello ZODB è stupefacente. I database relazionali (RDB) sono molto più diffusi degli OODBs. I database relazionali memorizzano le informazioni in tabelle; una tabella è costituita da un numero qualsiasi di righe e ogni riga contiene diverse colonne di informazioni. (Le righe sono più formalmente chiamate relazioni, che è dove il termine “database relazionale” ha origine.) Diamo un’occhiata a un esempio concreto. L’esempio viene dal mio lavoro di giorno per la Borsa MEMS, in una versione molto semplificata. Il lavoro è quello di tracciare le esecuzioni di processi, che sono liste di fasi di produzione da eseguire in un semiconduttore fab. Un’esecuzione appartiene ad un particolare utente, e ha un nome e un numero ID assegnato. Le esecuzioni consistono in un numero di operazioni; un’operazione è un singolo passo da eseguire, come depositare qualcosa su un wafer o incidere qualcosa su di esso. Le operazioni possono avere dei parametri, i quali sono le informazioni aggiuntive richieste per eseguire un’operazione. Per esempio, se si sta depositando qualcosa su un wafer, avrete bisogno di sapere due cose: 1) cosa si sta depositando, e 2) quanto se ne dovrebbe depositare. Si potrebbe depositare 100 micron di ossido di silicio, o 1 micron di rame. Mappare queste strutture in un database relazionale è semplice: 158 Capitolo 2. Altri manuali
- 163. Documentazione di Plone, Release 4 CREATE TABLE runs ( int run_id, varchar owner, varchar title, int acct_num, primary key(run_id) ); CREATE TABLE operations ( int run_id, int step_num, varchar process_id, PRIMARY KEY(run_id, step_num), FOREIGN KEY(run_id) REFERENCES runs(run_id), ); CREATE TABLE parameters ( int run_id, int step_num, varchar param_name, varchar param_value, PRIMARY KEY(run_id, step_num, param_name) FOREIGN KEY(run_id, step_num) REFERENCES operations(run_id, step_num), ); In Python, si dovrebbero scrivere tre classi denominate Run, Operation, e Parameter. Non illustrerò il codice per definire queste classi, poiché non sarebbe interessante a questo punto. Ogni classe dovrebbe avere un singolo metodo con cui inizializzarle, un metodo __init__() che assegna i valori di default, come 0 o None ad ogni attributo della classe. Non è difficile scrivere codice Python che crea una istanza Run e la valorizza con i dati presi dalle tabelle relazionali; con poco sforzo in più si potrebbe costruire un semplice tool, normalmente chiamato object-relational mapper (mappatore oggetto-relazione), per svolgere questo compito automaticamente. (Vedere http://www.amk.ca/python/unmaintained/ordb.html per un trucchetto veloce sui Python object-relational mapper e vedere http://www.python.org/workshops/1997-10/proceedings/shprentz.html per l’implementazione più efficace di Joel Shprentz della stessa idea; A differenza del mio, il sistema di Shprentz è stato utilizzato realmente per un lavoro.) Tuttavia è difficile rendere un object-relational mapper ragionevolmente veloce; un’implementazione da sempliciotto come la mia è abbastanza lenta perché deve fare molte query per accedere a tutti i dati di un oggetto. Gli objectrelational mappers a maggiori prestazioni utilizzano delle cache di oggetti per migliorare le performance, eseguendo le query SQL solo quando veramente necessario. Questo è utile se si vuole accedere all’improvviso all’operazione 123. Ma cosa succede se si vuole trovare tutte le operazioni dove uno step ha un parametro chiamato ‘thickness’ con valore uguale a 2.0? Nella versione relazionale, si hanno due scelte poco attraenti: 1. scrivere una query SQL specializzata per questo caso: SELECT run_id FROM operations WHERE param_name = ’thickness’ AND param_value = 2.0 Se tali query sono comuni, si potrebbe finire per avere moltissime query specializzate. Se le tabelle del database dovessero venire modificate tutte queste query andrebbero riscritte. 2. un object-relational mapper non aiuta molto. Scansionare attraverso le operazioni significa che il mapper deve eseguire le query SQL richieste per leggere l’operazione #1, e poi un semplice ciclo Python dovrebbe verificare se qualcuno dei suoi step ha il parametro che stiamo cercando. Ripetere il tutto per l’operazione #2, #3 e così via. Questo comporta un enorme numero di query SQL, e quindi è incredibilmente lento. 2.2. ZODB - un database nativo ad oggetti per Python 159
- 164. Documentazione di Plone, Release 4 Un database ad oggetti come lo ZODB semplicemente memorizza dei puntatori interni da oggetto a oggetto, per cui la lettura in un unico oggetto è molto più veloce che fare un mucchio di query SQL e assemblare i risultati. Quindi scansionare tutte le operazioni è ancora inefficiente ma non esageratamente inefficiente. Cos’è lo ZEO? Lo ZODB viene fornito con diverse classi che implementano l’interfaccia Storage. Tali classi sono incaricate di gestire il lavoro di scrittura degli oggetti Python in un supporto fisico di archiviazione, che può essere un file sul disco (la classe FileStorage), un file BerkeleyDB (BDBFullStorage), un database relazionale (DCOracleStorage) o qualche altro tipo di supporto. ZEO aggiunge ClientStorage, un nuovo Storage che non scrive su un supporto fisico ma semplicemente inoltra tutte le richieste attraverso la rete ad un server. Il server, che sta eseguendo un’istanza della classe StorageServer, semplicemente si comporta come un front-end per qualche classe fisica Storage. L’idea è abbastanza semplice, ma come vedremo in seguito in questo documento, apre molte possibilità. A proposito di questa guida L’autore principale di questa guida lavora su un progetto che utilizza lo ZODB e ZEO come sua tecnologia principale di storage. Usiamo il ZODB per memorizzare le esecuzioni di processi e le operazioni, un catalogo di processi disponibili, informazioni sugli utenti, informazioni di contabilità e altri dati. Parte dell’obbiettivo di scrivere questo documento è rendere la nostra esperienza più ampiamente disponibile. Qualche volta abbiamo speso ore e persino giorni cercando di capire un problema e questa guida è un tentativo di raccogliere la conoscenza che abbiamo acquisito in modo che altri non debbano rifare gli stessi errori che abbiamo fatto noi durante l’apprendimento. Il progetto ZODB dell’autore è descritto in un articolo disponibile qui: http://www.amk.ca/python/writing/mxarchitecture/ Questo documento sarà sempre un work in progress. Se volete suggerire chiarimenti o altri argomenti, si prega di inviare i commenti a ZODB- dev@zope.org. Riconoscimenti Andrew Kuchling ha scritto la versione originale di questa guida, che ha fornito una tra le prime documentazioni sullo ZODB ai programmatori Python. La sua versione iniziale, è stato aggiornato nel tempo da Jeremy Hylton e Tim Peters. Vorrei ringraziare le persone che hanno segnalato imprecisioni e bug, che hanno offerto suggerimenti sul testo, o proposto nuovi argomenti da coprire: Jeff Bauer, Willem Broekema, Thomas Guettler, Chris McDonough, George Runyan. Programmazione dello ZODB Installare lo ZODB Lo ZODB è pacchettizzato utilizzando gli strumenti standard distutils. Requisiti Avrete bisogno di Python 2.3 o superiore. Dal momento che il codice è pacchettizzato utilizzando distutils, è semplicemente questione di scompattare il pacchetto rilasciato, e poi lanciare il comando python setup.py install. Avrete bisogno di un compilatore C per compilare i pacchetti, perché ci sono vari moduli di estensione scritti in C. Per gli utenti Windows sono disponibili gli installer dei binari. Installare i pacchetti Scaricate il tarball ZODB contenente tutti i pacchetti sia per ZODB sia per ZEO da http://www.zope.org/Products/ZODB3.3 . Vedere il file README.txt nel livello superiore delle directory per i dettagli su come compilare, testare e installare. È possibile trovare informazioni su ZODB e le versioni più recenti dello ZODB nel Wiki su http://www.zope.org/Wikis/ZODB. 160 Capitolo 2. Altri manuali
- 165. Documentazione di Plone, Release 4 Come funziona lo ZODB Lo ZODB è concettualmente semplice. Le classi Python ereditano da una classe persistent.Persistent per diventare ZODB-compatibili. Le istanze di oggetti persistenti vengono caricati da un supporto di memorizzazione permanente, come un file su disco, quando il programma ha bisogno di loro, e rimangono nella cache in RAM. Lo ZODB intercetta le modifiche agli oggetti, in modo che quando uno statement come obj.size =1 viene eseguito, l’oggetto modificato viene segnato come “dirty” (sporco). A richiesta, ogni oggetto sporco viene scritto sullo storage permanente; questo è chiamato committing di una transazione. Le transazioni possono anche essere annullate e ripristinate, il che scarta tutte le modifiche e gli oggetti sporchi vengono ripristinati al loro stato iniziale prima dell’inizio della transazione. Il termine “transazione” ha uno specifico significato tecnico nella computer science. È estremamente importante che i contenuti di un database non vengano corrotti da fallimenti hardware o software, e la maggior parte dei database offrono protezione contro tali tipi di corruzioni supportando 4 utili proprietà: Atomicità, Consistenza, Isolamento e Durabilità. Nel gergo della computer science questi quattro termini sono chiamate collettivamente proprietà ACID, formando un acronimo con i loro nomi. Lo ZODB fornisce tutte le proprietà ACID. Le definizioni delle proprietà ACID sono: Atomicità significa che qualsiasi cambiamento ai dati fatto durante una transazione segue la regola del tutto-o-niente. O vengono applicate tutte le modifiche o nessuna di esse. Se un programma fa un sacco di modifiche e poi va in crash, il database non rimarrà parzialmente modificato, lasciando potenzialmente i dati in uno stato inconsistente; al contrario tutte le modifiche verranno rimosse. Ovviamente questo è un male, ma è meglio che avere delle modifiche parzialmente applicate che mettano il database in uno stato inconsistente. Consistenza significa che ogni transazione esegue una trasformazione valida dello stato del database. Alcuni database, ma non lo ZODB, forniscono una varietà di controlli di consistenza nel database o nel linguaggio; per esempio, un database relazionale costringe le colonne ad essere di un particolare tipo e può forzare delle relazioni tra le tabelle. Più in generale, l’atomicità e l’isolamento rendono possibile alle applicazioni di fornire la consistenza. Isolamento significa che due programmi o thread in esecuzione in due diverse transazioni non possono vedere le modifiche dell’altro fino a che non eseguono il commit delle loro transazioni Durabilità significa che una volta che una transazione è stata committata, un fallimento successivo non causerà nessuna perdita o corruzione dei dati. Apriamo uno ZODB There are 3 main interfaces supplied by the ZODB: Storage, DB, and Connection classes. The DB and Connection interfaces both have single implementations, but there are several different classes that implement the Storage interface. • Storage classes are the lowest layer, and handle storing and retrieving objects from some form of long-term storage. A few different types of Storage have been written, such as FileStorage, which uses regular disk files, and BDBFullStorage, which uses Sleepycat Software’s BerkeleyDB database. You could write a new Storage that stored objects in a relational database, for example, if that would better suit your application. Two example storages, DemoStorage and MappingStorage, are available to use as models if you want to write a new Storage. • The DB class sits on top of a storage, and mediates the interaction between several connections. One DB instance is created per process. • Finally, the Connection class caches objects, and moves them into and out of object storage. A multithreaded program should open a separate Connection instance for each thread. Different threads can then modify objects and commit their modifications independently. Preparing to use a ZODB requires 3 steps: you have to open the Storage, then create a DB instance that uses the Storage, and then get a Connection from the DB instance. All this is only a few lines of code: from ZODB import FileStorage, DB storage = FileStorage.FileStorage(’/tmp/test-filestorage.fs’) 2.2. ZODB - un database nativo ad oggetti per Python 161
- 166. Documentazione di Plone, Release 4 db = DB(storage) conn = db.open() Note that you can use a completely different data storage mechanism by changing the first line that opens a Storage; the above example uses a FileStorage. In section zeo, “How ZEO Works”, you’ll see how ZEO uses this flexibility to good effect. Using a ZODB Configuration File ZODB also supports configuration files written in the ZConfig format. A configuration file can be used to separate the configuration logic from the application logic. The storages classes and the DB class support a variety of keyword arguments; all these options can be specified in a config file. The configuration file is simple. The example in the previous section could use the following example: <zodb> <filestorage> path /tmp/test-filestorage.fs </filestorage> </zodb> The ZODB.config module includes several functions for opening database and storages from configuration files. import ZODB.config db = ZODB.config.databaseFromURL(’/tmp/test.conf’) conn = db.open() The ZConfig documentation, included in the ZODB3 release, explains the format in detail. Each configuration file is described by a schema, by convention stored in a component.xml file. ZODB, ZEO, zLOG, and zdaemon all have schemas. Writing a Persistent Class Making a Python class persistent is quite simple; it simply needs to subclass from the Persistent class, as shown in this example: from persistent import Persistent class User(Persistent): pass The Persistent base class is a new-style class implemented in C. For simplicity, in the examples the User class will simply be used as a holder for a bunch of attributes. Normally the class would define various methods that add functionality, but that has no impact on the ZODB’s treatment of the class. The ZODB uses persistence by reachability; starting from a set of root objects, all the attributes of those objects are made persistent, whether they’re simple Python data types or class instances. There’s no method to explicitly store objects in a ZODB database; simply assign them as an attribute of an object, or store them in a mapping, that’s already in the database. This chain of containment must eventually reach back to the root object of the database. As an example, we’ll create a simple database of users that allows retrieving a User object given the user’s ID. First, we retrieve the primary root object of the ZODB using the root() method of the Connection instance. The root object behaves like a Python dictionary, so you can just add a new key/value pair for your application’s root object. We’ll insert an OOBTree object that will contain all the User objects. (The BTree module is also included as part of Zope.) dbroot = conn.root() # Ensure that a ’userdb’ key is present 162 Capitolo 2. Altri manuali
- 167. Documentazione di Plone, Release 4 # in the root if not dbroot.has_key(’userdb’): from BTrees.OOBTree import OOBTree dbroot[’userdb’] = OOBTree() userdb = dbroot[’userdb’] Inserting a new user is simple: create the User object, fill it with data, insert it into the BTree instance, and commit this transaction. # Create new User instance import transaction newuser = User() # Add whatever attributes you want to track newuser.id = ’amk’ newuser.first_name = ’Andrew’ ; newuser.last_name = ’Kuchling’ ... # Add object to the BTree, keyed on the ID userdb[newuser.id] = newuser # Commit the change transaction.commit() The transaction module defines a few top-level functions for working with transactions. commit() writes any modified objects to disk, making the changes permanent. abort() rolls back any changes that have been made, restoring the original state of the objects. If you’re familiar with database transactional semantics, this is all what you’d expect. get() returns a Transaction object that has additional methods like note(), to add a note to the transaction metadata. More precisely, the transaction module exposes an instance of the ThreadTransactionManager transaction manager class as transaction.manager, and the transaction functions get() and begin() redirect to the same-named methods of transaction.manager. The commit() and abort() functions apply the methods of the same names to the Transaction object returned by transaction.manager.get(). This is for convenience. It’s also possible to create your own transaction manager instances, and to tell DB.open() to use your transaction manager instead. Because the integration with Python is so complete, it’s a lot like having transactional semantics for your program’s variables, and you can experiment with transactions at the Python interpreter’s prompt: >>> newuser <User instance at 81b1f40> >>> newuser.first_name ’Andrew’ >>> newuser.first_name = ’Bob’ >>> newuser.first_name ’Bob’ >>> transaction.abort() >>> newuser.first_name ’Andrew’ # Print initial value # Change first name # Verify the change # Abort transaction # The value has changed back Rules for Writing Persistent Classes Practically all persistent languages impose some restrictions on programming style, warning against constructs they can’t handle or adding subtle semantic changes, and the ZODB is no exception. Happily, the ZODB’s restrictions are fairly simple to understand, and in practice it isn’t too painful to work around them. 2.2. ZODB - un database nativo ad oggetti per Python 163
- 168. Documentazione di Plone, Release 4 The summary of rules is as follows: • If you modify a mutable object that’s the value of an object’s attribute, the ZODB can’t catch that, and won’t mark the object as dirty. The solution is to either set the dirty bit yourself when you modify mutable objects, or use a wrapper for Python’s lists and dictionaries (PersistentList, PersistentMapping) that will set the dirty bit properly. • Recent versions of the ZODB allow writing a class with __setattr__() , __getattr__(), or __delattr__() methods. (Older versions didn’t support this at all.) If you write such a __setattr__() or __delattr__() method, its code has to set the dirty bit manually. • A persistent class should not have a __del__() method. The database moves objects freely between memory and storage. If an object has not been used in a while, it may be released and its contents loaded from storage the next time it is used. Since the Python interpreter is unaware of persistence, it would call __del__() each time the object was freed. Let’s look at each of these rules in detail. Modifying Mutable Objects The ZODB uses various Python hooks to catch attribute accesses, and can trap most of the ways of modifying an object, but not all of them. If you modify a User object by assigning to one of its attributes, as in userobj.first_name = ’Andrew’, the ZODB will mark the object as having been changed, and it’ll be written out on the following commit(). The most common idiom that isn’t caught by the ZODB is mutating a list or dictionary. If User objects have a attribute named friends containing a list, calling userobj.friends.append(otherUser) doesn’t mark userobj as modified; from the ZODB’s point of view, userobj.friends was only read, and its value, which happened to be an ordinary Python list, was returned. The ZODB isn’t aware that the object returned was subsequently modified. This is one of the few quirks you’ll have to remember when using the ZODB; if you modify a mutable attribute of an object in place, you have to manually mark the object as having been modified by setting its dirty bit to true. This is done by setting the _p_changed attribute of the object to true: userobj.friends.append(otherUser) userobj._p_changed = True You can hide the implementation detail of having to mark objects as dirty by designing your class’s API to not use direct attribute access; instead, you can use the Java-style approach of accessor methods for everything, and then set the dirty bit within the accessor method. For example, you might forbid accessing the friends attribute directly, and add a get_friend_list() accessor and an add_friend() modifier method to the class. add_friend() would then look like this: def add_friend(self, friend): self.friends.append(otherUser) self._p_changed = True Alternatively, you could use a ZODB-aware list or mapping type that handles the dirty bit for you. The ZODB comes with a PersistentMapping class, and I’ve contributed a PersistentList class that’s included in my ZODB distribution, and may make it into a future upstream release of Zope. __getattr__(), __delattr__(), and __setattr__() ZODB allows persistent classes to have hook methods like __getattr__() and __setattr__(). There are four special methods that control attribute access; the rules for each are a little different. The __getattr__() method works pretty much the same for persistent classes as it does for other classes. No special handling is needed. If an object is a ghost, then it will be activated before __getattr__() is called. The other methods are more delicate. They will override the hooks provided by Persistent, so user code must call special methods to invoke those hooks anyway. 164 Capitolo 2. Altri manuali
- 169. Documentazione di Plone, Release 4 The __getattribute__() method will be called for all attribute access; it overrides the attribute access support inherited from Persistent. A user-defined __getattribute__() must always give the Persistent base class a chance to handle special attribute, as well as __dict__ or __class__. The user code should call _p_getattr(), passing the name of the attribute as the only argument. If it returns True, the user code should call Persistent‘s __getattribute__() to get the value. If not, the custom user code can run. A __setattr__() hook will also override the Persistent __setattr__() hook. User code must treat it much like __getattribute__(). The user-defined code must call _p_setattr() first to all Persistent to handle special attributes; _p_setattr() takes the attribute name and value. If it returns True, Persistent handled the attribute. If not, the user code can run. If the user code modifies the object’s state, it must assigned to _p_changed. A __delattr__() hooks must be implemented the same was as a the last two hooks. The user code must call _p_delattr(), passing the name of the attribute as an argument. If the call returns True, Persistent handled the attribute; if not, the user code can run. __del__() methods A __del__() method is invoked just before the memory occupied by an unreferenced Python object is freed. Because ZODB may materialize, and dematerialize, a given persistent object in memory any number of times, there isn’t a meaningful relationship between when a persistent object’s __del__() method gets invoked and any natural aspect of a persistent object’s life cycle. For example, it is emphatically not the case that a persistent object’s __del__() method gets invoked only when the object is no longer referenced by other objects in the database. __del__() is only concerned with reachability from objects in memory. Worse, a __del__() method can interfere with the persistence machinery’s goals. For example, some number of persistent objects reside in a Connection‘s memory cache. At various times, to reduce memory burden, objects that haven’t been referenced recently are removed from the cache. If a persistent object with a __del___() method is so removed, and the cache was holding the last memory reference to the object, the object’s __del__() method will be invoked. If the __del__() method then references any attribute of the object, ZODB needs to load the object from the database again, in order to satisfy the attribute reference. This puts the object back into the cache again: such an object is effectively immortal, occupying space in the memory cache forever, as every attempt to remove it from cache puts it back into the cache. In ZODB versions prior to 3.2.2, this could even cause the cache reduction code to fall into an infinite loop. The infinite loop no longer occurs, but such objects continue to live in the memory cache forever. Because __del__() methods don’t make good sense for persistent objects, and can create problems, persistent classes should not define __del__() methods. Writing Persistent Classes Now that we’ve looked at the basics of programming using the ZODB, we’ll turn to some more subtle tasks that are likely to come up for anyone using the ZODB in a production system. Changing Instance Attributes Ideally, before making a class persistent you would get its interface right the first time, so that no attributes would ever need to be added, removed, or have their interpretation change over time. It’s a worthy goal, but also an impractical one unless you’re gifted with perfect knowledge of the future. Such unnatural foresight can’t be required of any person, so you therefore have to be prepared to handle such structural changes gracefully. In object-oriented database terminology, this is a schema update. The ZODB doesn’t have an actual schema specification, but you’re changing the software’s expectations of the data contained by an object, so you’re implicitly changing the schema. One way to handle such a change is to write a one-time conversion program that will loop over every single object in the database and update them to match the new schema. This can be easy if your network of object references is quite structured, making it easy to find all the instances of the class being modified. For example, if all User objects can be found inside a single dictionary or BTree, then it would be a simple matter to loop over every User instance with a for statement. This is more difficult if your object graph is less structured; if User objects can be found as attributes of any number of different class instances, then there’s no longer any easy way to find them all, short of writing a generalized object traversal function that would walk over every single object in a ZODB, checking each one to see if it’s an instance of User. 2.2. ZODB - un database nativo ad oggetti per Python 165
- 170. Documentazione di Plone, Release 4 Some OODBs support a feature called extents, which allow quickly finding all the instances of a given class, no matter where they are in the object graph; unfortunately the ZODB doesn’t offer extents as a feature. Missing parts: zeo.rst transactions.rst modules.rst links.rst gfdl.rst Bugs Per riportare bug generici utilizzare Launchpad bug tracker. Tuttavia, lo ZODB è stato in giro molto più a lungo e quindi ci sono alcune risorse storiche per informazioni relative ai bug: • il collettore Zope (con l’argomento database) su http://collector.zope.org/Collectors/Zope • il tracciatore di bug di ZODB su sourceforge http://sourceforge.net/tracker/?group_id=15628&atid=115628 (molto più vecchio) su Feature requests Le richieste di funzionalità sono attualmente gestite un pò ad-hoc. Sentitevi liberi di scrivere un post sulla mailing list chiedendo di una funzionalità e - se non si vuole venire dimenticati - aggiungere un blueprint in Launchpad Inoltre, in precedenza eravamo soliti gestire le proposte http://wiki.zope.org/ZODB/ListOfProposals/contents#ListOfProposals sul nostro vecchio wiki su • Lo ZODB Book (in corso di stesura) 2.2.3 Downloads Lo ZODB è distribuito come egg Python attraverso il Python Package Index. È possibile installare l’egg con il comando easy_install di setuptools: $ easy_install ZODB3 2.2.4 La communità e i contributi Le discussioni avvengono sulla mailing list degli sviluppatori ZODB. Le segnalazioni di bug, le richieste di funzionalità, e i piani di rilascio sono fatti su Launchpad. Se desideri contribuire, saremo lieti di accettare qualsiasi lavoro di documentazione, aiuto agli altri sviluppatori e agli utenti della mailing list, segnalazione di bug, proposta o scrittura di codice. ZODB è un progetto gestito dalla Fondazione Zope in modo da poter ottenere l’accesso in scrittura per contribuire direttamente - leggi le informazioni per gli sviluppatori della fondazione Zope. 2.3 La guida completa alla Zope Component Architecture Autore Baiju M Versione 0.5.8 Libro stampato http://www.lulu.com/content/1561045 Online PDF (en) http://www.muthukadan.net/docs/zca.pdf 166 Capitolo 2. Altri manuali
- 171. Documentazione di Plone, Release 4 Traduttore Giacomo Spettoli <giacomo.spettoli@gmail.com> Copyright (C) 2007,2008,2009 Baiju M <baiju.m.mail AT gmail.com>. È permessa la copia, la ridistribuzione e/o la modifica di questo documento secondo i termini della «GNU Free Documentation Licence», versione 1.3 o versioni successive pubblicate dalla Free Software Foundation. Il codice presente in questo documento è soggetto alle condizioni della «Zope Public Licence», versione 2.1 (ZPL). THE SOURCE CODE IN THIS DOCUMENT AND THE DOCUMENT ITSELF IS PROVIDED “AS IS” AND ANY AND ALL EXPRESS OR IMPLIED WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE. Ringraziamenti Molte persone mi hanno aiutato nella stesura di questo libro. La bozza iniziale fu revisionata dal mio collega Brad Allen. Quando annunciai questo libro attraverso il mio blog, ricevetti molti commenti di incoraggiamento a procedere con questo lavoro. Kent Tenney modificò numerose parti di questo libro e riscrisse anche l’applicazione di esempio. Molti altri mi hanno inviato correzioni e commenti, inclusi Lorenzo Gil Sanchez, Michael Haubenwallner, Nando Quintana, Stephane Klein, Tim Cook, Kamal Gill and Thomas Herve. Lorenzo ha tradotto questo lavoro in Spagnolo e Stephane in Francese. Grazie a tutti! 2.3.1 Come iniziare Introduzione Sviluppare un sistema software di grandi dimensioni è sempre molto complicato. È stato dimostrato che quando si tratta di grandi sistemi un buon approccio all’analisi, al design e alla programmazione è dato dalla programmazione orientata agli oggetti. Il design basato sui componenti e la programmazione a componenti stanno diventando molto popolari in questi giorni. L’approccio basato sui componenti aiuta a scrivere e a mantenere facilmente testabili con unit-test i sistemi software. Ci sono molti framework per il supporto al design a componenti in diversi linguaggi, alcuni sono persino indipendenti dal linguaggio. Due esempi sono il COM della Microsoft e XPCOM di Mozilla. La Zope Component Architecture (ZCA) è un framework Python per il supporto al design e alla programmazione basati sui componenti. Essa è molto adatta allo sviluppo di sistemi software di grandi dimensioni scritti in Python. La ZCA non è specifica per il web application server Zope: può essere utilizzata per qualsiasi applicazione Python. Forse dovrebbe essere chiamata Python Component Architecture. La ZCA tratta principalmente l’utilizzo efficace degli oggetti Python. I componenti sono oggetti riutilizzabili con interfacce introspezionabili. Un interfaccia è un oggetto che descrive come interagire con un particolare componente. In altre parole: un componente fornisce un interfaccia implementata in una classe (o in qualsiasi altro oggetto chiamabile). Non è tanto importante come un oggetto venga implementato, l’importante è che esso aderisca al contratto della sua interfaccia. Utilizzando la ZCA, è possibile suddividere la complessità di un sistema su molteplici componenti che cooperano tra loro. Essa aiuta a creare due principali tipi di componenti: gli adapter e le utility. I tre pacchetti principali che compongono la ZCA sono: • zope.interface: viene utilizzato per definire l’interfaccia di un componente • zope.event: fornisce un semplice sistema di eventi • zope.component: si occupa della creazione, della registratione e del recupero dei componenti. Notare che la ZCA non è un insieme di componenti, ma più propriamente serve a creare, registrare e recuperare i componenti. È bene ricordare inoltre che un adapter è una normale classe Python (o più in generale una factory) e una utility è un normale oggetto chiamabile Python. 2.3. La guida completa alla Zope Component Architecture 167
- 172. Documentazione di Plone, Release 4 Il framework ZCA fu sviluppato come parte del progetto Zope3. Come già anticipato, è un framework scritto esclusivamente in Python, così da poter essere utilizzato da qualsiasi tipo di applicazione Python. Attualmente i progetti Zope3, Zope2 e Grok utilizzano questo framework in maniera massiccia. Ci sono molti altri progetti che la utilizzano, inclusi progetti non legati al web 1 . Breve storia Il progetto del framework ZCA iniziò nel 2011 come parte del progetto Zope3. Venne sviluppato basandosi sulle lezioni imparate durante lo sviluppo di grandi sistemi software utilizzando Zope2. Jim Fulton fu il project leader di questo progetto. Molte persone contribuirono al design e all’implementazione, inclusi ma non limitati a, Stephan Richter, Philipp von Weitershausen, Guido van Rossum (aka. Python BDFL), Tres Seaver, Phillip J Eby and Martijn Faassen. Inizialmente la ZCA definiva dei componenti aggiuntivi, services e views, ma gli sviluppatori arrivarono alla conclusione che le utility potevano rimpiazzare i service e i multi-adapter potevano rimpiazzare le view. Oggi la ZCA ha un numero molto ridotto di tipi di componenti principali: utility, adapter, subscriber, e handler. In effetti, i subscriber e gli handler sono due particolari tipi di adapter. Durante il ciclo di sviluppo di Zope3.2, Jim Fulton propose una grande semplificazione della ZCA 2 . Con questa semplificazione, fu creata una nuova singola interfaccia (IComponentRegistry) per la registrazione di componenti sia locali sia globali. Il pacchetto zope.component ha una lunga lista di dipendenze, molte delle quali non erano necessarie per applicazioni non basate su Zope3. Durante il PyCon2007, Jim Fulton aggiunse a setuptools la funzionalità extras_require per permettere di separare il nucleo della ZCA dalle funzionalità aggiuntive 3 . Nel marzo del 2009, Tres Seaver rimosse poi le dipendenze da zope.deferredimport e zope.proxy. Oggi, il progetto ZCA è un progetto indipendente con il proprio ciclo di rilasci e il proprio repository Subversion. Questo progetto sta diventando parte del più grande progetto del framework Zope 4 . In ogni caso le segnalazioni e i bug sono ancora tracciati come parte del progetto Zope3 5 , e la mailing list principale zope-dev viene utilizzata per le discussioni sullo sviluppo 6 . C’è anche un’altra user-list generica per Zope3 (zope3-users) che può essere utilizzata per qualsiasi domanda sulla ZCA 7 . Installazione Il pacchetto zope.component insieme ai pacchetti zope.interface e zope.event costituiscono il nucleo della Zope Component architecture. Essi forniscono le strutture per definire, registrare e recuperare i componenti. Il pacchetto zope.component e le sue dipendenze sono disponibili in formato egg sul Python Package Index (PyPI) 8 . È possibile installare zope.component e le sue dipendenze utilizzando easy_install 9 $ easy_install zope.component Questo comando scarica zope.component e le sue dipendenze da PyPI e installa il tutto nel vostro Python path. 1 2 3 4 5 6 7 8 9 http://wiki.zope.org/zope3/ComponentArchitecture http://wiki.zope.org/zope3/LocalComponentManagementSimplification http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies http://docs.zope.org/zopeframework/ https://bugs.launchpad.net/zope3 http://mail.zope.org/mailman/listinfo/zope-dev http://mail.zope.org/mailman/listinfo/zope3-users Repository dei pacchetti Python: http://pypi.python.org/pypi http://peak.telecommunity.com/DevCenter/EasyInstall 168 Capitolo 2. Altri manuali
- 173. Documentazione di Plone, Release 4 In alternativa, è possibile scaricare zope.component e le sue dipendenze da PyPI e poi installarle. Installare i pacchetti nell’ordine indicato sotto. Su sistemi Windows, potrebbero essere necessari i paccheti binari di zope.interface: 1. zope.interface 2. zope.event 3. zope.component Per installare questi pacchetti, dopo averli scaricati, è possibile usare il comando easy_install con gli eggs come argomento. (è possibile passare tutti gli egg come argomenti sulla stessa linea): $ easy_install /path/to/zope.interface-3.x.x.tar.gz $ easy_install /path/to/zope.event-3.x.x.tar.gz $ easy_install /path/to/zope.component-3.x.x.tar.gz È anche possibile installare questi pacchetti dopo averli estratti singolarmente. Ad esempio: $ $ $ $ tar zxvf /path/to/zope.interface-3.x.x.tar.gz cd zope.interface-3.x.x python setup.py build python setup.py install Questi metodi installano la ZCA sul Python di sistema, nella cartella site-packages, ma questo potrebbe creare problemi. In un post sulla mailing list di Zope3, Jim Fulton sconsiglia l’utilizzo del Python di sistema 10 . In alternativa si può utilizzare virtualenv e/o zc.buildout per installare qualsiasi pacchetto Python. Questo metodo è adatto anche per il deploy. Come provare il codice In Python ci sono due approcci per la configurazione di ambienti di lavoro isolati per lo sviluppo di applicazioni. Il primo è virtualenv creato da Ian Biking e l’altro è zc.buildout creato da Jim Fulton. È anche possibile utilizzare questi due pacchetti insieme. Con questi pacchetti è possibile installare zope.component e le altre dipendenze in un ambiente di lavoro isolato. Queste sono le buone pratiche per la sperimentazione di codice Python, e familiarizzare con questi strumenti tornerà utile quando si vorrà sviluppare e fare il deploy delle proprie applicazioni. virtualenv Si può installare virtualenv utilizzando easy_install: $ easy_install virtualenv Poi si può creare un nuovo ambiente in questo modo: $ virtualenv --no-site-packages myve Questo comando crea un nuovo ambiente virtuale nella cartella myve. Ora, dall’interno della cartella myve, è possibile installare zope.component e le sue dipendenze utilizzando il comando easy_install che si trova dentro alla cartella myve/bin: $ cd myve $ ./bin/easy_install zope.component Ora è possibile importare zope.interface e zope.component dal vostro nuovo interprete python disponibile dentro alla cartella myve/bin: 10 http://article.gmane.org/gmane.comp.web.zope.zope3/21045 2.3. La guida completa alla Zope Component Architecture 169
- 174. Documentazione di Plone, Release 4 $ ./bin/python Questo comando fornisce un prompt Python che può essere utilizzato per eseguire il codice di questo libro. zc.buildout Utilizzando zc.buildout con la ricetta zc.recipe.egg, è possibile creare un interprete Python che ha a disposizione gli eggs specificati. Per prima cosa, installare zc.buildout utilizzando il comando easy_install. (è possibile farlo anche dentro all’ambiente virtuale). Per creare un nuovo buildout per fare esperimenti con gli egg Python, per prima cosa creare una cartella e inizializzarla utilizzando il comando buildout init : $ mkdir mybuildout $ cd mybuildout $ buildout init Ora la nuova cartella buildout è un buildout. Il file di configurazione di default per il buildout è buildout.cfg. Dopo l’inizializzazione, avrà questo contenuto: [buildout] parts = Cambiamolo così: [buildout] parts = py [py] recipe = zc.recipe.egg interpreter = python eggs = zope.component Ora lanciamo il comando buildout disponibile dentro alla cartella mybuildout/bin senza argomenti. Questo crea un nuovo interprete Python dentro alla cartella mybuildout/bin: $ ./bin/buildout $ ./bin/python Questo comando farà apparire un prompt Python che può essere utilizzato per eseguire il codice di questo libro. 2.3.2 Un esempio Introduzione Consideriamo come esempio un’applicazione commerciale per la registrazione degli ospiti di un hotel. Python può implementare questa applicazione in vari modi. Inizieremo dando una breve occhiata ad una possibile implementazione procedurale, e poi ci sposteremo verso un semplice approccio orientato agli oggetti. Mentre esamineremo l’approccio orientato agli oggetti, vedremo come potremo trarre beneficio dai pattern di design classici, adapter e interface. Questo ci porterà nel mondo della Zope Component Architecture. Approccio procedurale In qualsiasi applicazione commerciale, una delle parti principali è la conservazione dei dati. Per semplicità, in questo esempio utilizzeremo un dizionario Python come sistema di storage. Creeremo degli id univoci per il dizionario e il valore associato ad ogni chiave sarà a sua volta un dizionario con i dettagli della prenotazione. 170 Capitolo 2. Altri manuali
- 175. Documentazione di Plone, Release 4 >>> bookings_db = {} #key: unique Id, value: details in a dictionary Un’implementazione minimale richiede una funzione che verifichi i dettagli della prenotazione e una funzione di supporto che fornisca gli id univoci per le chiavi del dizionario di storage. Possiamo generare un id univoco in questo modo: >>> def get_next_id(): ... db_keys = bookings_db.keys() ... if db_keys == []: ... next_id = 1 ... else: ... next_id = max(db_keys) + 1 ... return next_id Come si può notare, l’implementazione della funzione get_next_id è molto semplice. La funzione prende una lista di chiavi e controlla una lista vuota. Se la lista è vuota questa è la nostra prima prenotazione, quindi restituiamo 1. Se la lista non è vuota, aggiungiamo 1 al valore massimo della lista e lo restituiamo. Ora utilizzeremo la funzione sopra per inserire degli elementi nel dizionario bookings_db: >>> def book_room(name, place): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: name, ... ’room’: place ... } Un’applicazione per la gestione delle prenotazioni di un hotel ha bisogno di dati supplementari: • numero di telefono • opzioni della camera • metodo di pagamento • ... e ha bisogno di codice per la gestione dei dati: • cancellare una prenotazione • aggiornare una prenotazione • pagare una stanza • rendere i dati persistenti • assicurare la sicurezza dei dati • ... Se dovessimo continuare con l’esempio procedurale, dovremmo creare molte funzioni e dovremmo passare i dati avanti e indietro tra di loro. Man mano che i requisiti cambiano o aumentano, il codice diventa sempre più difficile da manutenere e i bug diventano più difficili da correggere. Possiamo terminare qui la nostra discussione sull’approccio procedurale poichè sarà molto più facile fornire la persistenza dei dati, la flessibilità di design e la testabilità del codice utilizzando gli oggetti. Approccio orientato agli oggetti La nostra discussione sul design orientato agli oggetti ci porta a introdurre la classe. La classe serve ad incapsulare i dati e il codice per gestirli. 2.3. La guida completa alla Zope Component Architecture 171
- 176. Documentazione di Plone, Release 4 La classe principale sarà il FrontDesk. La classe FrontDesk o verso cui delegherà la gestione, saprà come gestire i dati dell’hotel. Andremo a creare delle istanze di FrontDesk per applicare questa conoscenza al mestiere di gestire un hotel. L’esperienza ha mostrato che incapsulare il codice e i dati attraverso gli oggetti porta ad un design più facile da comprendere,testare e modificare. Vediamo i dettagli dell’implementazione di una classe FrontDesk: >>> class FrontDesk(object): ... ... def book_room(self, name, place): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: name, ... ’place’: place ... } In questa implementazione, l’oggetto frontdesk (istanza della classe FrontDesk) è in grado di gestire le prenotazioni. Possiamo usare questa classe così: >>> frontdesk = FrontDesk() >>> frontdesk.book_room("Jack", "Bangalore") Qualsiasi progetto reale sarà soggetto a cambiamenti nei requisiti. In questo caso la gestione dell’hotel ha deciso che ogni ospite deve fornire anche un numero di telefono, quindi siamo costretti a cambiare il codice. Possiamo raggiungere questo requisito aggiungendo un argomento al metodo book_room che verrà aggiunto al dizionario dei valori: >>> class FrontDesk(object): ... ... def book_room(self, name, place, phone): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: name, ... ’place’: place, ... ’phone’: phone ... } Oltre a migrare i dati verso il nuovo schema, ora dobbiamo anche cambiare le chiamate a FrontDesk. Se però noi astraiamo i dettagli dell’ospite in un oggetto e lo usiamo per la registrazione, i cambiamenti al codice vengono minimizzati. Così possiamo applicare i cambiamenti ai dettagli dell’ospite e le chiamate a FrontDesk non avranno bisogno di cambiamenti. Così abbiamo: >>> class FrontDesk(object): ... ... def book_room(self, guest): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } Dobbiamo ancora cambiare il codice per rispondere ai cambiamenti dei requisiti. Sebbene questo sia inevitabile, il nostro obiettivo è quello di minimizzare questi cambiamenti, in modo da aumentare la manutenibilità. 172 Capitolo 2. Altri manuali
- 177. Documentazione di Plone, Release 4 Nota: Quando si aggiunge del codice, è importante sentirsi liberi di apportare i cambiamenti senza paura di rompere l’applicazione. Il modo per avere i riscontri richiesti immediatamente è usare i test automatizzati. Con dei test ben scritti (e un buon sistema di controllo di versione) è possibile fare cambiamenti piccoli o grandi senza conseguenze. Una buona fonte di informazioni sulla filosofia della programmazione è il libro Extreme Programming Explained di Kent Beck. Con l’introduzione dell’oggetto ospite, abbiamo risparmiato un pò di scrittura di codice e , cosa ancora più importante, l’astrazione fornita dall’oggetto ospite ha reso il sistema più semplice e più comprensibile. Come risultato, il codice è più facile da ri-fattorizzare e da mantenere. Il pattern adapter Nelle applicazioni reali, l’oggetto frontdesk dovrebbe eseguire compiti come la cancellazione e l’aggiornamento delle prenotazioni. Nel design attuale dobbiamo passare l’oggetto ospite al frontdesk ogni volta che chiamiamo metodi come cancel_booking e update_booking. Possiamo evitare facilmente questo vincolo se passiamo l’oggetto ospite al metodo FrontDesk.__init__(), rendendolo così un attributo dell’istanza: >>> class FrontDeskNG(object): ... ... def __init__(self, guest): ... self.guest = guest ... ... def book_room(self): ... guest = self.guest ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } In effetti la soluzione che abbiamo raggiunto è un pattern molto conosciuto, l’adapter (adattatore). In generale, un adapter contiene un oggetto adattato: >>> class Adapter(object): ... ... def __init__(self, adaptee): ... self.adaptee = adaptee Questo pattern sarà utile quando si avrà a che fare con i dettagli implementativi che dipendono da considerazioni riguardanti: • il cambio dei requisiti del cliente • requisiti di persistenza dei dati (ZODB, RDBMS, XML...) • requisiti di output (HTML, PDF, testo semplice...) • il linguaggio di markup usato per il rendering (ReST, Markdown, Textile...) Grazie agli adapters e al component registry (registro dei componenti), la ZCA permette di cambiare i dettagli implementativi del codice attraverso la configurazione. Come vedremo in questa sezione sugli adapter della ZCA, la possibilità di configurare i dettagli implementativi fornisce utili abilità: • l’abilità di passare da una implementazione all’altra 2.3. La guida completa alla Zope Component Architecture 173
- 178. Documentazione di Plone, Release 4 • l’abilità di aggiungere implementazioni quando necessario • aumenta il riutilizzo sia del codice precedente sia del codice della ZCA Queste capacità portano il codice ad essere più flessibile, scalabile e riutilizzabile. Tuttavia c’è un costo per tutto ciò poiché il mantenimento del component registry aggiunge un livello di complessità all’applicazione. Se è noto a priori che un’applicazione non avrà mai bisogno di queste funzionalità, la ZCA non è necessaria. Ora siamo pronti per iniziare il nostro studio della Zope Component Architecture, iniziando dalle interfacce. 2.3.3 Interfacce Introduzione Il file README.txt 11 nel percorso path/to/zope/interface definisce le interfacce in questo modo Le interfacce sono oggetti che specificano (documentano) il comportamento verso l’esterno degli oggetti che le "forniscono". Un’interfaccia specifica il suo comportamento attraverso: - la documentazione informale in una doc string. - la definizione degli attributi - le Invariants (invarianti), sono condizioni che devono essere verificate per un oggetto che fornisce l’interfaccia. Il libro classico dell’ingegneria del software «Design Patterns» 12 della Gang of Four raccomanda di “Programmare per interfacce, non per implementazione”. Definire un’interfaccia formale è utile per la comprensione del sistema. In più, le interfacce portano a tutti i benefici della ZCA. Un’interfaccia specifica le caratteristiche di un oggetto, il suo comportamento, le sue capacità. L’interfaccia descrive cosa può fare un oggetto, mentre per capire come lo fa, si dovrà guardare l’implementazione. Due metafore usate comunemente per spiegare le interfacce sono i contratti e le cianografie, termini dei dizionari legale e architetturale per indicare un insieme di specifiche. In alcuni linguaggi moderni come il Java, C#, VB.NET etc. le interfacce sono un aspetto esplicito del linguaggio. Siccome in Python mancano le interfacce, la ZCA le implementa con delle meta-classi da cui ereditare. Di seguito un classico esempio di hello world: >>> class Host(object): ... ... def goodmorning(self, name): ... """Say good morning to guests""" ... ... return "Good morning, %s!" % name Nel classe qui sopra abbiamo definito un metodo goodmorning. Se chiamiamo il metodo goodmorning su un oggetto istanza di questa classe, esso resituirà Good morning, ...! >>> host = Host() >>> host.goodmorning(’Jack’) ’Good morning, Jack!’ 11 12 L’albero del codice di Zope è pieno di file README.txt che offrono una meravigliosa documentazione. http://en.wikipedia.org/wiki/Design_Patterns 174 Capitolo 2. Altri manuali
- 179. Documentazione di Plone, Release 4 Qui host indica l’oggetto attuale utilizzato dal codice. Se si volesse esaminare i dettagli implementativi si dovrebbe accedere alla classe Host, o attraverso il codice sorgente o con uno strumento di documentazione delle API 13 . Ora inizieremo ad utilizzare le interfacce della ZCA. Per la classe sopra si può specificare l’interfaccia così: >>> from zope.interface import Interface >>> class IHost(Interface): ... ... def goodmorning(guest): ... """Say good morning to guest""" Come si può notare, l’interfaccia eredita da zope.interface.Interface. Questo utilizzo (abuso?) dello statement class del Python è come la ZCA definisce le interfacce. Il prefisso “I” per i nomi delle interfacce non è altro che un’utile convenzione. Dichiarazione delle interfacce Abbiamo già visto come dichiarare un interfaccia utilizzando zope.interface nella sezione precedente. Questa sezione spiegherà il concetto più nel dettaglio. Si consideri questa interfaccia di esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> class IHost(Interface): ... """A host object""" ... ... name = Attribute("""Name of host""") ... ... def goodmorning(guest): ... """Say good morning to guest""" L’interfaccia IHost ha due attributi, name e goodmorning. Si ricordi che, in Python, i metodi sono anche attributi delle classi. L’attributo name è definito utilizzando la classe zope.interface.Attribute. Quando si aggiunge un attributo name all’interfaccia IHost, non viene impostato un valore iniziale. Lo scopo di definire l’attributo name qui è puramente per indicare che qualsiasi implementazione di questa interfaccia dovrà fornire un attributo chiamato name. In questo caso, non viene nemmeno indicato di che tipo deve essere l’attributo! Si può passare una stringa di documentazione come primo argomento di Attribute. L’altro attributo, goodmorning, è un metodo definito utilizzando la definizione di funzione. Si noti che self non è richiesto nelle interfacce, perché self è un dettaglio implementativo della classe. Ad esempio, un modulo potrebbe implementare questa interfaccia. Se un modulo implementa questa interfaccia, saranno definiti al suo interno un attributo name e una funzione goodmorning e la funzione goodmorning accetterà un argomento. Ora vedremo come fare la connessione interfaccia-classe-oggetto. Gli oggetti sono la vera parte attiva e sono istanze delle classi. L’interfaccia è la vera definizione dell’oggetto, quindi la classe è solo un dettaglio implementativo. Ecco perché si dovrebbe sempre programmare un’interfaccia e non un’implementazione. Ora si dovrebbe prendere familiarità con due ulteriori termini per comprendere altri concetti. Il primo è provide (fornisce) e l’altro è implement (implementa). Gli oggetti forniscono le interfacce e le classi implementano le interfacce. In altre parole, gli oggetti forniscono le interfacce che le loro classi implementano. Nel esempio sopra host (l’oggetto) fornisce IHost (l’interfaccia) e Host (la classe) implementa IHost (l’interfaccia). Un oggetto può fornire più di una interfaccia e anche una classe può implementare più di una interfaccia. Gli oggetti possono anche fornire delle interfacce direttamente in aggiunta alle interfacce implementate dalle loro classi. 13 http://en.wikipedia.org/wiki/Application_programming_interface 2.3. La guida completa alla Zope Component Architecture 175
- 180. Documentazione di Plone, Release 4 Nota: Le classi sono i dettagli implementativi degli oggetti. In Python, le classi sono oggetti chiamabili, quindi perché altri oggetti chiamabili non possono implementare un’interfaccia? In effetti possono. Per qualsiasi oggetto chiamabile è possibile dichiarare che esso produce oggetti che forniscono una qualche interfaccia dichiarando che l’oggetto chiamabile implementa le interfacce. Gli oggetti chiamabili sono generalmente chiamati factories (fabbriche). Dato che le funzioni sono oggetti chiamabili, una funzione può essere un implementatore di una interfaccia. Implementare le interfacce Per dichiarare che una classe implementa una particolare zope.interface.implements nella definizione della classe. interfaccia, si utilizza la funzione Si consideri questo esempio, qui Host implementa IHost: >>> from zope.interface import implements >>> class Host(object): ... ... implements(IHost) ... ... name = u’’ ... ... def goodmorning(self, guest): ... """Say good morning to guest""" ... ... return "Good morning, %s!" % guest Nota: se ci si chiede come lavori la funzione implements, si faccia riferimento al post del blog di James Henstridge (http://blogs.gnome.org/jamesh/2005/09/08/python-class-advisors/). Nella sezione degli adapter, si potrà vedrà la funzione adapts, che lavora in maniera simile. Siccome Host implementa IHost, le istanze di Host forniscono IHost. C’è qualche metodo di utilità per introspezionare le dichiarazioni. La dichiarazione può essere fatta anche fuori dalla classe. Se si omette interface.implements(IHost) nel esempio sopra, una volta che la classe è già stata definita, è possibile scrivere: >>> from zope.interface import classImplements >>> classImplements(Host, IHost) Esempio rivisitato Ora, ritorniamo all’applicazione di esempio. Qui si vedrà come definire l’interfaccia dell’oggetto frontdesk: >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... Per prima cosa abbiamo importato la classe Interface dal modulo zope.interface. Se si definisce una sottoclasse della classe Interface essa sarà una interfaccia dal punto di vista della Zope component architecture. Un’interfaccia può essere implementata, come abbiamo già visto, in una classe o in qualsiasi oggetto chiamabile. 176 Capitolo 2. Altri manuali
- 181. Documentazione di Plone, Release 4 L’interfaccia frontdesk definita qui è IDesk. La stringa di documentazione dell’interfaccia fornisce un’idea di un possibile oggetto. Nella definizione di un metodo in un’interfaccia, il primo argomento non deve essere self, poiché un’interfaccia non verrà mai istanziata e i suoi metodi non saranno mai chiamati. Al contrario, la classe interfaccia documenta semplicemente come dovrebbero apparire i metodi e gli attributi in qualsiasi classe normale che dichiari di implementarla, e il parametro self è un dettaglio implementativo che non ha bisogno di essere documentato. Come sappiamo, un’interfaccia può anche specificare normali attributi: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> class IGuest(Interface): ... ... name = Attribute("Name of guest") ... place = Attribute("Place of guest") In questa interfaccia, l’oggetto ospite ha due attributi specificati con la documentazione. Un’interfaccia può anche specificare attributi e metodi insieme. Un’interfaccia può essere implementata da una classe, da un modulo o qualsiasi altro oggetto. Per esempio una funzione può creare dinamicamente un componente e restituirlo; in questo caso la funzione è un implementatore dell’interfaccia. Ora sappiamo cos’è un’interfaccia e come definirla e usarla. un’interfaccia per definire un componente adapter. Nel prossimo capitolo vedremo come utilizzare Interfacce marker Un’interfaccia può essere utilizzata per dichiarare che un particolare oggetto appartiene ad uno speciale tipo. Un’interfaccia senza attributi o metodi è chiamata interfaccia marker. Ecco un esempio di interfaccia marker: >>> from zope.interface import Interface >>> class ISpecialGuest(Interface): ... """A special guest""" Questa interfaccia può essere utilizzata per indicare che un oggetto è uno speciale tipo di ospite. Invarianti A volte c’è la necessità di utilizzare alcune regole per un componente che coinvolgono uno o più normali attributi. Questo tipo di regole sono chiamate invariants (invarianti). Si può utilizzare zope.interface.invariant per impostare delle invarianti sulle interfacce degli oggetti. Si consideri un semplice esempio: c’è un oggetto persona con gli attributi name,‘email‘ e phone. Come si potrebbe implementare una regola di validazione che imponga che almeno uno fra gli attributi email e phone debba esistere ma non necessariamente entrambi? Per prima cosa bisogna costruire un oggetto chiamabile, o una semplice funzione o una istanza chiamabile di una classe come questa: >>> def contacts_invariant(obj): ... ... if not (obj.email or obj.phone): ... raise Exception( ... "At least one contact info is required") 2.3. La guida completa alla Zope Component Architecture 177
- 182. Documentazione di Plone, Release 4 Poi si deve definire l’interfaccia dell oggetto person in questo modo. zope.interface.invariant per definire l’invariante: Utilizzare la funzione >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import invariant >>> class IPerson(Interface): ... ... name = Attribute("Name") ... email = Attribute("Email Address") ... phone = Attribute("Phone Number") ... ... invariant(contacts_invariant) Ora utilizzare il metodo validateInvariants dell’interfaccia per la validazione: >>> from zope.interface import implements >>> class Person(object): ... implements(IPerson) ... ... name = None ... email = None ... phone = None >>> jack = Person() >>> jack.email = u"jack@some.address.com" >>> IPerson.validateInvariants(jack) >>> jill = Person() >>> IPerson.validateInvariants(jill) Traceback (most recent call last): ... Exception: At least one contact info is required Come si può vedere l’oggetto jack è validato senza alcuna eccezione mentre l’oggetto jill non è stato validato dal vincolo invariante, così viene sollevata un’eccezione. 2.3.4 Adapters Implementazione In questa sezione verranno descritti gli adapter in dettaglio. La Zope Component Architecture, come abbiamo già visto, aiuta ad utilizzare efficacemente gli oggetti Python. I componenti adapter sono uno dei componenti di base utilizzati dalla ZCA. Gli adapter sono oggetti Python, ma con interfacce ben definite. Per dichiarare che una classe è un adapter si utilizza la funzione adapts definita nel pacchetto zope.component. Ecco il nuovo adattatore FrontDeskNG con una dichiarazione esplicita di interfaccia: >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): 178 Capitolo 2. Altri manuali
- 183. Documentazione di Plone, Release 4 ... ... ... ... ... ... ... ... ... ... self.guest = guest def register(self): guest = self.guest next_id = get_next_id() bookings_db[next_id] = { ’name’: guest.name, ’place’: guest.place, ’phone’: guest.phone } Quello che abbiamo definito qui è un adapter per IDesk, che adatta gli oggetti IGuest. L’interfaccia IDesk è implementata dalla classe FrontDeskNG. Quindi un’istanza di questa classe fornirà l’interfaccia IDesk >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True Il FrontDeskNG è solo uno dei possibili adattatori. È possibile creare anche altri adapter che permettano di gestire le registrazioni degli ospiti diversamente. Registration Per utilizzare questo componente adapter, bisogna registrarlo nel component registry anche conosciuto come site manager. Un site manager normalmente risiede in un sito. Il sito e il suo site manager saranno più importanti quando si svilupperanno applicazioni Zope3. Per ora ci interesseremo solo del global site e del global site manager (o component registry). Il global site manager risiede in memoria mentre un local site manager è persistente. Per registrare il nostro componente, per prima cosa recuperiamo il global site manager: >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng’) Per recuperare il global site manager, bisogna chiamare la funzione getGlobalSiteManager disponibile nel pacchetto zope.component. In effetti, il global site manager è disponibile anche come un attributo (globalSiteManager) del pacchetto zope.component. Quindi è anche possibile utilizzare direttamente l’attributo zope.component.globalSiteManager. Per registrare l’adapter nei componenti, come si può vedere sopra, si utilizza il metodo registerAdapter del component registry. Il primo argomento deve essere un classe/factory adapter. Il secondo argomento è una tupla di oggetti adattati, ad esempio l’oggetto che stiamo adattando. In questo esempio, stiamo adattando solo l’oggetto IGuest. Il terzo argomento è l’interfaccia implementata dal componente adater. Il quarto argomento è opzionale ed è il nome di quel particolare adapter. Dato che abbiamo dato un nome a questo adapter, questo è un named adapter. Se non viene passato alcun nome allora questo sarà automaticamente una stringa vuota (‘’). 2.3. La guida completa alla Zope Component Architecture 179
- 184. Documentazione di Plone, Release 4 Nella registrazione sopra abbiamo passato l’interfaccia adattata e l’interfaccia fornita dall’adapter. Dato che questi dettagli sono già stati specificati nella implementazione dell’adapter, non è necessario specificarli ancora. Infatti, avremmo potuto fare la registrazione così >>> gsm.registerAdapter(FrontDeskNG, name=’ng’) Ci sono alcune vecchie API per fare la registrazione che però andrebbero evitate. Le funzioni delle vecchie API iniziano con provide, ad es. provideAdapter, provideUtility,etc. Durante lo sviluppo di un’applicazione Zope3 è possibile utilizzare lo Zope configuration markup language (ZCML) per la registrazione dei componenti. In Zope3, i local component (o componenti persistenti) possono essere registrati dalla Zope Management Interface (ZMI) o anche in maniera programmatica. Nota: I local component sono componenti persistenti mentre i global component risiedono in memoria. I global component saranno registrati in base alla configurazione dell’applicazione. I local component sono caricati in memoria dal database all’avvio dell’applicazione. Recuperare un adapter Il recupero dei componenti registrati dal component registry può essere effettuato con due funzioni disponibili nel pacchetto zope.component. Una di esse è getAdapter e l’altra è queryAdapter. Entrambe le funzioni accettano gli stessi parametri. Il metodo getAdapter solleverà ComponentLookupError se la ricerca del componente fallisce, mentre queryAdapter restituirà None. Si possono importare i due metodi in questo modo: >>> from zope.component import getAdapter >>> from zope.component import queryAdapter Nella sezione precedente abbiamo registrato un componente per l’oggetto ospite (l’oggetto adattato) che fornisce l’interfaccia IDesk con nome ‘ng’. Nella prima sezione di questo capitolo, abbiamo creato un oggetto ospite di nome jack. Ecco come recuperare un componente che adatta l’interfaccia dell’oggetto jack (IGuest) e fornisce l’interfaccia IDesk e con il nome ‘ng’. Qui sia getAdapter sia queryAdapter lavorano in maniera simile: >>> getAdapter(jack, IDesk, ’ng’) <FrontDeskNG object at ...> >>> queryAdapter(jack, IDesk, ’ng’) <FrontDeskNG object at ...> Come si può vedere il primo argomento è l’oggetto da adattare, poi l’interfaccia che dovrebbe essere fornita dal componente e per ultimo il nome del componente adapter. Se si prova a cercare un componente con un nome non registrato ma per lo stesso oggetto adattato e la stessa interfaccia, la ricerca fallirà. Ecco come si comportano i due metodi in questo caso: Come si può vedere sopra, getAdapter ha sollevato un’eccezione ComponentLookupError mentre queryAdapter ha restituito None quando la ricerca è fallita. Il terzo argomento, il nome di registrazione, è opzionale e se non viene passato il suo valore predefinito sarà una stringa vuota (‘’). Dal momento che non ci sono componenti registrati con una stringa vuota, getAdapter solleverà ComponentLookupError e‘queryAdapter‘ restituirà None: >>> getAdapter(jack, IDesk) Traceback (most recent call last): ... ComponentLookupError: ... 180 Capitolo 2. Altri manuali
- 185. Documentazione di Plone, Release 4 >>> reg = queryAdapter(jack, IDesk) >>> reg is None True In questa sezione abbiamo imparato come registrare un semplice adapter e come recuperarlo dal component registry. Questo tipo di adapter sono chiamati single adapter (adattatore singolo) perché adattano solo un oggetto. Se un adapter adatta più di un oggetto, allora si chiama multi-adapter (multi-adattatore). Recuperare gli adapter tramite le interfacce Gli adapter possono essere recuperati direttamente utilizzando le interfacce, ma questo funziona solo per gli adapter senza nome. Il primo argomento è l’oggetto adattato e il secondo è un argomento keyword. Se la ricerca dell’adapter fallisce, viene restituito il secondo argomento. >>> IDesk(jack, alternate=’default-output’) ’default-output’ Il nome della keyword può anche essere ommesso: >>> IDesk(jack, ’default-output’) ’default-output’ Se il secondo argomento non viene passato allora viene sollevata TypeError: >>> IDesk(jack) Traceback (most recent call last): ... TypeError: (’Could not adapt’, <Guest object at ...>, <InterfaceClass __builtin__.IDesk>) Qui FrontDeskNG viene registrato senza nome: >>> gsm.registerAdapter(FrontDeskNG) Ora la ricerca dell’adapter dovrebbe andare a buon fine: >>> IDesk(jack, ’default-output’) <FrontDeskNG object at ...> Quindi, per casi semplici, si può utilizzare l’interfaccia per recuperare il componente adapter. Il pattern adapter Il concetto di adapter nella Zope Component Architecture è molto simile al classico pattern adapter che viene descritto nel libro «Design Pattern». L’intento degli adapter della ZCA è però più ampio di quello del pattern adapter. L’intento del pattern adapter è quello di convertire l’interfaccia di una classe in un’altra interfaccia che il client si aspetta. Questo permette di poter far lavorare insieme le classi che altrimenti sarebbero incompatibili a causa delle loro interfacce. Ma nella sezione Motivation del libro «Design Pattern», GoF dice: “Spesso l’adapter fornisce delle funzionalità che le classi adattate non forniscono”. L’adapter della ZCA è più incentrato sull’aggiunta di funzionalità che sulla creazione di una nuova interfaccia per un oggetto adattato. L’adapter della ZCA permette alle classi adapter di estendere le funzionalità aggiungendo nuovi metodi. (sarebbe interessante notare che l’Adapter era conosciuto come Feature nelle prime fasi del design della ZCA.) 14 Nel paragrafo sopra c’è una citazione dal libro della “Gang of Four”, che finisce così ”...che le classi adattate non forniscono”. Ma nella frase successiva io ho utilizzato “oggetto adattato” invece di “classe adattata”, poiché Gof descrive 14 Discussione sulla rinomina delle Feature in Adapter: http://mail.zope.org/pipermail/zope3-dev/2001-December/000008.html 2.3. La guida completa alla Zope Component Architecture 181
- 186. Documentazione di Plone, Release 4 due varianti di adapter basati sull’implementazione. La prima è chiamata class adapter e l’altra object adapter. Un class adapter utilizza l’ereditarietà multipla per adattare un’interfaccia all’altra, mentre un object adapter fa affidamento sulla composizione degli oggetti. L’adapter della ZCA segue il pattern object adapter, il quale usa la delega come meccanismo di composizione. Il secondo principio di GoF a proposito del design orientato agli oggetti dice: “Favorite la composizione degli oggetti rispetto all’ereditarietà di classe”. Per maggiori dettagli su questo argomento vi invito a leggere il libro «Design Pattern». La cosa più interessante degli adapter della ZCA sono le interfacce esplicite per i componenti e il component registry. I componenti adapter della ZCA vengono registrati nel component registry e recuperati dagli oggetti client utilizzando le interfacce e il nome quando richiesto. 2.3.5 Utility Introduzione Ora conosciamo i concetti di interfaccia, adapter e component registry. A volte però sarebbe utile poter registrare un oggetto che non adatta nulla. Connessioni a database, parse XML, oggetti che restituiscono Id univoci, etc. sono tutti esempi di questo tipo di oggetti. Questo tipo di componenti forniti dalla ZCA sono chiamati utility. Le utility sono solo oggetti che forniscono un’interfaccia e che vengono ricercati per interfaccia e per nome. Questo approccio crea un global registry attraverso il quale le interfacce possono essere registrate e accedute da diverse parti della nostra applicazione, senza bisogno di passare le istanze avanti e indietro come parametri. Non è però consigliabile registrare tutte le istanze di componenti in questo modo. Si dovrebbero registrare solo i componenti che si vuole rendere rimpiazzabili. Semplici utility Una utility può essere registrata con un nome o senza nome. Una utility registrata con un nome è chiamata named utility, e la vedremo nella prossima sezione. Prima di implementare l’utility, come solito, definiamo la sua interfaccia. Ecco un’interfaccia IGreeter (“salutatore”): >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... ... def greet(name): ... """Say hello""" Come anche un adapter, una utility può avere più di una implementazione. Ecco una possibile implementazione della interfaccia sopra: >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... return "Hello " + name La vera utility sarà un’istanza di questa classe. Per utilizzare questa utility dobbiamo registrarla per poterla richiedere in seguito utilizzando l’API della ZCA. Possiamo registrare un’istanza di questa classe (utility) utilizzando registerUtility: >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() 182 Capitolo 2. Altri manuali
- 187. Documentazione di Plone, Release 4 >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter) In questo esempio abbiamo registrato l’utility che fornisce l’interfaccia IGreeter. Si può ricercare l’interfaccia sia con queryUtility sia con getUtility: >>> from zope.component import queryUtility >>> from zope.component import getUtility >>> queryUtility(IGreeter).greet(’Jack’) ’Hello Jack’ >>> getUtility(IGreeter).greet(’Jack’) ’Hello Jack’ Come si può vedere, gli adapter normalmente sono delle classi mentre le utility normalmente sono istanze di classi. L’istanza della classe utility viene creata solo una volta mentre le istanze dell’adapter vengono create dinamicamente quando vengono richieste. Named utility Quando si registra un componente, come ad esempio un adapter, è possibile assegnargli un nome. Come detto nella precedente sezione, una utility registrata con un particolare nome è chiamata named utility. Ecco come registrare l’utility greeter con un nome: >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter, ’new’) In questo esempio abbiamo registrato l’utility con un nome fornendo l’interfaccia IGreeter. Ecco come ricercare l’interfaccia con queryUtility o con getUtility: >>> from zope.component import queryUtility >>> from zope.component import getUtility >>> queryUtility(IGreeter, ’new’).greet(’Jill’) ’Hello Jill’ >>> getUtility(IGreeter, ’new’).greet(’Jill’) ’Hello Jill’ Come si può vedere qui, quando si fa un’interrogazione è necessario utilizzare il name come secondo argomento. Chiamare la funzione getUtility senza un nome (come secondo argomento) è uguale a chiamare a chiamarla con una stringa vuota come nome poichè il valore predefinito del secondo argomento (keyword) è una stringa vuota. Poi il meccanismo di ricerca dei componenti proverà a trovare il componente il nome uguale alla stringa vuota e fallirà. Quando la ricerca del componente fallisce solleva l’eccezione ComponentLookupError. Si ricordi che non ritornerà un componente a caso con un’altro nome. Le funzioni di ricerca degli adapter, getAdapter e queryAdapter lavorano in maniera simile. Factory Una factory è un componente utility che fornisce l’interfaccia IFactory. Per creare una factory, per prima cosa definiamo l’interfaccia dell’oggetto: 2.3. La guida completa alla Zope Component Architecture 183
- 188. Documentazione di Plone, Release 4 >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IDatabase(Interface): ... ... def getConnection(): ... """Return connection object""" Ecco una finta implementazione dell’interfaccia IDatabase: >>> class FakeDb(object): ... ... implements(IDatabase) ... ... def getConnection(self): ... return "connection" Possiamo creare una factory utilizzando zope.component.factory.Factory: >>> from zope.component.factory import Factory >>> factory = Factory(FakeDb, ’FakeDb’) Ora possiamo registrarla in questo modo: >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> from zope.component.interfaces import IFactory >>> gsm.registerUtility(factory, IFactory, ’fakedb’) Per utilizzare la factory, possiamo fare così: >>> from zope.component import queryUtility >>> queryUtility(IFactory, ’fakedb’)() <FakeDb object at ...> C’è una scorciatoia per utilizzare una factory: >>> from zope.component import createObject >>> createObject(’fakedb’) <FakeDb object at ...> 2.3.6 Adapter avanzati In questo capitolo discuteremo di adapter avanzati come i multi-adapter, i subscription adapter e gli handler. Multi adapter Un semplice adapter normalmente adatta solo un oggetto, ma un adapter può adattare più di un oggetto. Se un adapter adatta più di un oggetto, è chiamato multi-adapter. >>> from zope.interface import Interface >>> from zope.interface import implements >>> from zope.component import adapts 184 Capitolo 2. Altri manuali
- 189. Documentazione di Plone, Release 4 >>> class IAdapteeOne(Interface): ... pass >>> class IAdapteeTwo(Interface): ... pass >>> class IFunctionality(Interface): ... pass >>> class MyFunctionality(object): ... implements(IFunctionality) ... adapts(IAdapteeOne, IAdapteeTwo) ... ... def __init__(self, one, two): ... self.one = one ... self.two = two >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(MyFunctionality) >>> class One(object): ... implements(IAdapteeOne) >>> class Two(object): ... implements(IAdapteeTwo) >>> one = One() >>> two = Two() >>> from zope.component import getMultiAdapter >>> getMultiAdapter((one,two), IFunctionality) <MyFunctionality object at ...> >>> myfunctionality = getMultiAdapter((one,two), IFunctionality) >>> myfunctionality.one <One object at ...> >>> myfunctionality.two <Two object at ...> Subscription adapter A differenza dei normali adapter, i subscription adapter vengono utilizzati quando vogliamo recuperare tutti gli adapter che adattano un oggetto a una particolare interfaccia. Un subscription adapter è anche conosciuto come subscriber. Consideriamo un problema di validazione. Abbiamo degli oggetti e vogliamo verificare se essi aderiscono a qualche tipo di standard. Si definisce un’interfaccia di validazione: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IValidate(Interface): ... ... def validate(ob): 2.3. La guida completa alla Zope Component Architecture 185
- 190. Documentazione di Plone, Release 4 ... ... ... ... ... ... """Determine whether the object is valid Return a string describing a validation problem. An empty string is returned to indicate that the object is valid. """ Magari abbiamo dei documenti: >>> class IDocument(Interface): ... ... summary = Attribute("Document summary") ... body = Attribute("Document text") >>> class Document(object): ... ... implements(IDocument) ... ... def __init__(self, summary, body): ... self.summary, self.body = summary, body Ora, potremmo voler specificare diverse regole di validazione per questi documenti. Per esempio, potremmo richiedere che la descrizione sia una linea singola: >>> from zope.component import adapts >>> class SingleLineSummary: ... ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if ’n’ in self.doc.summary: ... return ’Summary should only have one line’ ... else: ... return ’’ Oppure potremmo richiedere che il corpo del testo sia lungo al massimo 1000 caratteri: >>> class AdequateLength(object): ... ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if len(self.doc.body) < 1000: ... return ’too short’ ... else: ... return ’’ Possiamo registrare queste regole come subscription adapter: 186 Capitolo 2. Altri manuali
- 191. Documentazione di Plone, Release 4 >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerSubscriptionAdapter(SingleLineSummary) >>> gsm.registerSubscriptionAdapter(AdequateLength) In seguito possiamo utilizzare i subscriber per validare gli oggetti: >>> from zope.component import subscribers >>> doc = Document("AnDocument", "blah") >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’Summary should only have one line’, ’too short’] >>> doc = Document("AnDocument", "blah" * 1000) >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’Summary should only have one line’] >>> doc = Document("A Document", "blah") >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’too short’] Handler Gli handler sono delle fabbriche di subscription adapter che non restituiscono nulla. Essi infatti eseguono tutto il loro lavoro quando vengono chiamati. Gli handler tipicamente sono utilizzati per la gestione degli eventi e sono anche conosciuti come event subscribers o event subscription adapter. Gli event subscriber sono diversi dagli altri subscription adapter per il fatto che il chiamante dell’event subscriber non si aspetta di interagire con loro in nessun modo diretto. Per esempio, un generatore di eventi non si aspetta di ricevere alcun valore di ritorno. Poiché i subscribers non hanno bisogno di fornire alcuna API ai loro chiamanti, è più naturale definirli con delle funzioni, piuttosto che con delle classi. Per esempio, in un sistema di gestione documentale potremmo voler registrare le date di creazione dei documenti: >>> import datetime >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() In questo esempio, abbiamo una funzione che prende un evento e svolge qualche operazione e in effetti non restituisce nulla. Questo è un caso speciale di subscription adapter che adatta un evento verso nulla. Tutto il lavoro è svolto quando la “factory” dell’adapter viene chiamata. I subscriber che non restituiscono niente sono chiamati “handler” e per registrarli ci sono delle API specifiche: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IDocumentCreated(Interface): ... ... doc = Attribute("The document that was created") 2.3. La guida completa alla Zope Component Architecture 187
- 192. Documentazione di Plone, Release 4 >>> class DocumentCreated(object): ... ... implements(IDocumentCreated) ... ... def __init__(self, doc): ... self.doc = doc Dovremo anche cambiare la definizione del nostro handler: Questo identifica l’handler come un adapter di eventi di tipo IDocumentCreated. Andiamo a registrare l’handler: >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerHandler(documentCreated) Ora possiamo creare un evento e utilizzare la funzione handle per chiamare gli handler registrati per l’evento: >>> from zope.component import handle >>> handle(DocumentCreated(doc)) >>> doc.created.__class__.__name__ ’datetime’ 2.3.7 Utilizzo della ZCA in Zope La Zope Component Architecture viene utilizzata sia in Zope3 sia in Zope2. Questo capitolo tratterà l’utilizzo della ZCA in Zope. ZCML Lo Zope Configuration Markup Language (ZCML) è un sistema di configurazione basato su XML per la registrazione dei componenti. Così, invece di utilizzare le API Python per la registrazione, è possibile utilizzare lo ZCML. Sfortunatamente però l’utilizzo dello ZCML richiederà l’installazione di più pacchetti di dipendenze. Per installare questi pacchetti lanciare: $ easy_install "zope.component [zcml]" Ecco come registrare un componente: <configure xmlns="http://namespaces.zope.org/zope"> <adapter factory=".company.EmployeeSalary" provides=".interfaces.ISalary" for=".interfaces.IEmployee" /> Gli attributi provides e for sono opzionali, a patto che siano già stati dichiarati nell’implementazione del componente: <configure xmlns="http://namespaces.zope.org/zope"> <adapter factory=".company.EmployeeSalary" /> 188 Capitolo 2. Altri manuali
- 193. Documentazione di Plone, Release 4 Se si vuole registrare il componente come un named adapter, si può fornire un attributo name: <configure xmlns="http://namespaces.zope.org/zope"> <adapter factory=".company.EmployeeSalary" name="salary" /> Anche le utility sono registrate in maniera simile: <configure xmlns="http://namespaces.zope.org/zope"> <utility component=".database.connection" provides=".interfaces.IConnection" /> l’attributo provides è opzionale, a patto che sia stato dichiarato nell’implementazione: <configure xmlns="http://namespaces.zope.org/zope"> <utility component=".database.connection" /> Se si vuole registrare il componente come named utility, si può fornire l’attributo name: <configure xmlns="http://namespaces.zope.org/zope"> <utility component=".database.connection" name="Database Connection" /> Invece di utilizzare direttamente il componente, è possibile anche fornire la factory: <configure xmlns="http://namespaces.zope.org/zope"> <utility factory=".database.Connection" /> Overrides Quando registriamo un componente utilizzando le API Python (i metodi register*), l’ultimo componente registrato rimpiazzerà il componente registrato in precedenza se entrambi sono registrati con gli stessi componenti. Per esempio, consideriamo l’esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IA(Interface): ... pass >>> class IP(Interface): ... pass >>> from zope.interface import implements 2.3. La guida completa alla Zope Component Architecture 189
- 194. Documentazione di Plone, Release 4 >>> from zope.component import adapts >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> class AP(object): ... ... implements(IP) ... adapts(IA) ... ... def __init__(self, context): ... self.context = context >>> class AP2(object): ... ... implements(IP) ... adapts(IA) ... ... def __init__(self, context): ... self.context = context >>> class A(object): ... ... implements(IA) >>> a = A() >>> ap = AP(a) >>> gsm.registerAdapter(AP) >>> getAdapter(a, IP) <AP object at ...> Se registriamo un’altro adapter quello esistente viene rimpiazzato: >>> gsm.registerAdapter(AP2) >>> getAdapter(a, IP) <AP2 object at ...> Ma quando si registrano i componenti utilizzando ZCML, la seconda registrazione solleva un errore di conflitto. Questo è un suggerimento per noi, altrimenti ci sarebbe la possibilità di sovrascrivere le registrazioni per sbaglio e questo potrebbe portare a una maggiore difficoltà nel tracciare i bug nel sistema. Quindi l’utilizzo dello ZCML è una buona cosa per l’applicazione. A volte avremo la necessità di sovrascrivere una registrazione esistente. Per questa evenienza lo ZCML fornisce la direttiva includeOverrides. Con questa direttiva possiamo scrivere le nostre sostituzioni in un file separato: <includeOverrides file="overrides.zcml" /> NameChooser Posizione: zope.app.container.contained.NameChooser Questo è un adapter che permette di scegliere un nome univoco per un oggetto all’interno di un contenitore. La registrazione dell’adapter è simile a questa: 190 Capitolo 2. Altri manuali
- 195. Documentazione di Plone, Release 4 <adapter provides=".interfaces.INameChooser" for="zope.app.container.interfaces.IWriteContainer" factory=".contained.NameChooser" /> Dalla registrazione possiamo vedere che l’oggetto adattato è un IWriteContainer e che l’adapter fornisce INameChooser. Questo adapter fornisce una funzionalità molto comoda per i programmatori Zope. La principale implementazione di IWriteContainer in Zope3 sono zope.app.container.BTreeContainer e zope.app.folder.Folder. Normalmente erediteremo da queste implementazioni per creare le nostre classi contenitori. Se che non ci fosse nessuna interfaccia chiamata INameChooser e il relativo adapter, allora dovremmo implementare questa funzionalità per ogni implementazione separatamente. LocationPhysicallyLocatable Posizione: zope.location.traversing.LocationPhysicallyLocatable Questo adapter viene utilizzato frequentemente nelle applicazioni Zope3 ma normalmente viene chiamato attraverso un API in zope.traversing.api. (Qualche vecchio codice utilizza le funzioni di zope.app.zapi che è solo una redirezione aggiuntiva) La registrazione dell’adapter è simile a questa: <adapter factory="zope.location.traversing.LocationPhysicallyLocatable" /> L’interfaccia fornita e l’interfaccia adattata sono specificate nell’implementazione. Ecco qui l’inizio dell’implementazione: class LocationPhysicallyLocatable(object): """Provide location information for location objects """ zope.component.adapts(ILocation) zope.interface.implements(IPhysicallyLocatable) ... Normalmente, quasi tutti gli oggetti persistenti nell’applicazione Zope3 forniranno l’interfaccia ILocation. Questa interfaccia ha solo due attributi, __parent__ e __name__. Il __parent__ è il contenitore nella gerarchia degli oggetti e __name__ è il nome dell’oggetto all’interno del contenitore. L’interfaccia IPhysicallyLocatable ha 4 metodi: getRoot, getPath, getName, e getNearestSite. • getRoot restituisce l’oggetto radice fisica • getPath restituisce il percorso fisico verso l’oggetto in formato stringa • getName restituisce l’ultimo segmento del percorso fisico • getNearestSite restituisce il sito in cui è contenuto l’oggetto. Se l’oggetto è un sito, viene restituito l’oggetto stesso. Quando si studia Zope3, si capisce che queste sono le cose importanti e quelle che vengono richieste più spesso. Per comprendere la bellezza di questo sistema bisogna vedere come Zope2 recupera l’oggetto radice fisica e come questo è implementato. Esiste un metodo chiamato getPhysicalRoot virtualmente per ogni oggetto contenitore. 2.3. La guida completa alla Zope Component Architecture 191
- 196. Documentazione di Plone, Release 4 DefaultSized Posizione: zope.size.DefaultSized Questo adapter non è che l’implementazione di default dell’interfaccia ISized. Esso è registrato per tutti i tipi di oggetti. Se si vuole registrare questo adapter per una particolare interfaccia si dovrà sovrascrivere questa registrazione nella propria implementazione. La registrazione dell’adapter è simile a questa: <adapter for="*" factory="zope.size.DefaultSized" provides="zope.size.interfaces.ISized" permission="zope.View" /> Come si può vedere, l’interfaccia adattata è “*” quindi può adattare qualsiasi tipo di oggetto. ISized è una semplice interfaccia con due contratti di metodi: class ISized(Interface): def sizeForSorting(): """Returns a tuple (basic_unit, amount) Used for sorting among different kinds of sized objects. ’amount’ need only be sortable among things that share the same basic unit.""" def sizeForDisplay(): """Returns a string giving the size. """ Si può trovare un’altro adapter ISized registrato per IZPTPage nel pacchetto zope.app.zptpage. ZopeVersionUtility Posizione: zope.app.applicationcontrol.ZopeVersionUtility La registrazione è questa: <utility component=".zopeversion.ZopeVersionUtility" provides=".interfaces.IZopeVersion" /> L’interfaccia fornita, IZopeVersion, ha solo un metodo chiamato getZopeVersion. Questo metodo restituisce una stringa contenente la versione di Zope (con eventualmente le informazione di SVN). L’implementazione di default, ZopeVersionUtility, prende le informazioni sull versione da un file version.txt nella cartella zope/app. Se Zope è in esecuzione a partire da un checkout di Subversion, esso mostra l’ultimo numero di revisione. Se nessuno dei metodi sopra funziona allora restituisce Development/Unknown. 2.3.8 Caso di studio Nota: Questo capitolo non è ancora completo. Ogni suggerimento è benvenuto! 192 Capitolo 2. Altri manuali
- 197. Documentazione di Plone, Release 4 Introduzione Questo capitolo è un esempio di creazione di un’applicazione desktop utilizzando la libreria PyGTK per le GUI e la ZCA. Quest’applicazione utilizza anche due diversi tipi di meccanismi per la persistenza dei dati, un database ad oggetti (ZODB) e un altro database relazionale (SQLite). In ogni caso nella pratica solo uno storage può essere utilizzato per una particolare installazione. La ragione di utilizzare due diversi meccanismi di persistenza è la dimostrazione di come usare la ZCA per incollare tra loro i componenti. La maggior parte del codice di questa applicazione è legato a PyGTK. Man mano che l’applicazione crescie si potranno utilizzare i componenti ZCA dovunque si desideri avere modularità e estensibilità. Si utilizzino invece direttamente oggetti Python dove non sono richieste queste due proprietà. Non c’è differenza nell’utilizzo della ZCA per il web o per il desktop o per qualsiasi altro tipo di applicazione o framework. È preferibile seguire una convenzione per posizione dalla quale registrare i componenti. Questa applicazione utilizza una convenzione che permette di essere estesa posizionando delle registrazioni di componenti simili in moduli separati e in seguito importarli dal modulo di registrazione principale. In questa applicazione il modulo principale per la registrazione dei componenti è register.py. Il codice sorgente di questa applicazione può essere scaricato su http://www.muthukadan.net/downloads/zcalib.tar.bz2 Casi d’uso L’applicazione che ora andiamo a discutere è un sistema per la gestione di una biblioteca con funzionalità minimali. I requisiti possono essere riassunti così: • aggiunta dei membri con un numero univoco e un nome • aggiunta dei libri con il codice a barre, autore e titolo • prestito dei libri • restituzione dei libri L’applicazione può essere disegnata in modo che le funzionalità principali possano essere utilizzate da una singola finestra. La finestra principale per accedere a tutte queste funzionalità potrebbe avere questo aspetto: Dalla finestra Member, l’utente dovrebbe poter gestire i membri. Quindi dovrebbe essere possibile aggiungere, modificare e eliminare i membri come in figura sotto 2.3. La guida completa alla Zope Component Architecture 193
- 198. Documentazione di Plone, Release 4 Simile alla finestra dei membri, la finestra del catalogo permette all’utente di aggiungere, modificare e eliminare i libri: La finestra dei movimenti dovrebbe gestire i prestiti e le restituzioni dei libri: Panoramica del codice PyGTK Come si può vedere dal codice, la maggior parte del codice è legato a PyGTK e la sua struttura è molto simile per le diverse finestre. Le finestre di questa applicazione sono disegnate utilizzando il costruttore di GUI Glade. Si dovrebbero assegnare nomi sensati ai widget che si andrà ad utilizzare nel codice. Nella finestra principale, tutte le voci del menu hanno nomi come circulation, catalog, member, quit e about. La classe gtk.glade.XML è utilizzata analizzare il file Glade e quindi creare gli oggetti widget dell’interfaccia grafica. Ecco come analizzare e accedere agli oggetti: import gtk.glade xmlobj = gtk.glade.XML(’/path/to/file.glade’) widget = xmlobj.get_widget(’widget_name’) Nel file mainwindow.py, si può vedere il codice: curdir = os.path.abspath(os.path.dirname(__file__)) xml = os.path.join(curdir, ’glade’, ’mainwindow.glade’) 194 Capitolo 2. Altri manuali
- 199. Documentazione di Plone, Release 4 xmlobj = gtk.glade.XML(xml) self.mainwindow = xmlobj.get_widget(’mainwindow’) Il nome del widget della finestra principale è mainwindow. In maniera simile, gli altri widget vengono recuperati così: circulation = xmlobj.get_widget(’circulation’) member = xmlobj.get_widget(’member’) quit = xmlobj.get_widget(’quit’) catalog = xmlobj.get_widget(’catalog’) about = xmlobj.get_widget(’about’) Poi questi widget vengono connessi a certi eventi: self.mainwindow.connect(’delete_event’, self.delete_event) quit.connect(’activate’, self.delete_event) circulation.connect(’activate’, self.on_circulation_activate) member.connect(’activate’, self.on_member_activate) catalog.connect(’activate’, self.on_catalog_activate) about.connect(’activate’, self.on_about_activate) Il delete_event è l’evento scatenato durante la chiusura della finestra utilizzando l’apposito bottone. L’evento activate è lanciato quando il menu viene selezionato. I widget sono connessi a certe funzioni di callback per certi eventi. Possiamo vedere dal codice sopra che la finestra principale è connessa al metodo on_delete_event per il delete_event. Il widget quit è anche connesso allo stesso metodo per l’evento activate: def on_delete_event(self, *args): gtk.main_quit() La funzione di callback chiama semplicemente la funzione main_quit. Il codice Ecco il file zcalib.py: import registry import mainwindow if __name__ == ’__main__’: registry.initialize() try: mainwindow.main() except KeyboardInterrupt: import sys sys.exit(1) Qui vengono importati due moduli: registry e mainwindow. Poi il registro viene analizzato e viene chiamata la funzione main di mainwindow. Se l’utente sta cercando di uscire dall’applicazione usando Ctrl+C, il sistema uscirà normalmente poiché abbiamo intercettato l’eccezione KeyboardInterrupt. Questo è il modulo registry.py: import sys from zope.component import getGlobalSiteManager from interfaces import IMember 2.3. La guida completa alla Zope Component Architecture 195
- 200. Documentazione di Plone, Release 4 from interfaces import IBook from interfaces import ICirculation from interfaces import IDbOperation def initialize_rdb(): from interfaces import IRelationalDatabase from relationaldatabase import RelationalDatabase from member import MemberRDbOperation from catalog import BookRDbOperation from circulation import CirculationRDbOperation gsm = getGlobalSiteManager() db = RelationalDatabase() gsm.registerUtility(db, IRelationalDatabase) gsm.registerAdapter(MemberRDbOperation, (IMember,), IDbOperation) gsm.registerAdapter(BookRDbOperation, (IBook,), IDbOperation) gsm.registerAdapter(CirculationRDbOperation, (ICirculation,), IDbOperation) def initialize_odb(): from interfaces import IObjectDatabase from objectdatabase import ObjectDatabase from member import MemberODbOperation from catalog import BookODbOperation from circulation import CirculationODbOperation gsm = getGlobalSiteManager() db = ObjectDatabase() gsm.registerUtility(db, IObjectDatabase) gsm.registerAdapter(MemberODbOperation, (IMember,), IDbOperation) gsm.registerAdapter(BookODbOperation, (IBook,), IDbOperation) gsm.registerAdapter(CirculationODbOperation, (ICirculation,), IDbOperation) def check_use_relational_db(): use_rdb = False try: arg = sys.argv[1] if arg == ’-r’: return True except IndexError: 196 Capitolo 2. Altri manuali
- 201. Documentazione di Plone, Release 4 pass return use_rdb def initialize(): use_rdb = check_use_relational_db() if use_rdb: initialize_rdb() else: initialize_odb() Diamo uno sguardo alla funzione initialize che stiamo chiamando dal modulo principale, zcalib.py. La funzione initialize per prima cosa controlla quale db è in uso, il database relazionale (RDB) o il database ad oggetti (ODB) e questo controllo è fatto nella funzione check_use_relational_db. Se è stata passata dalla linea di comando l’opzione -r, la funzione chiamerà initialize_rdb altrimenti initialize_odb. Se la funzione RDB viene chiamata, essa configurerà tutti i componenti legati a RDB altrimenti se viene chiamata la funzione ODB, verranno configurati tutti i componenti legati a ODB. Ecco il file mainwindow.py: import os import gtk import gtk.glade from circulationwindow import circulationwindow from catalogwindow import catalogwindow from memberwindow import memberwindow class MainWindow(object): def __init__(self): curdir = os.path.abspath(os.path.dirname(__file__)) xml = os.path.join(curdir, ’glade’, ’mainwindow.glade’) xmlobj = gtk.glade.XML(xml) self.mainwindow = xmlobj.get_widget(’mainwindow’) circulation = xmlobj.get_widget(’circulation’) member = xmlobj.get_widget(’member’) quit = xmlobj.get_widget(’quit’) catalog = xmlobj.get_widget(’catalog’) about = xmlobj.get_widget(’about’) self.mainwindow.connect(’delete_event’, self.delete_event) quit.connect(’activate’, self.delete_event) circulation.connect(’activate’, self.on_circulation_activate) member.connect(’activate’, self.on_member_activate) catalog.connect(’activate’, self.on_catalog_activate) about.connect(’activate’, self.on_about_activate) def delete_event(self, *args): gtk.main_quit() def on_circulation_activate(self, *args): circulationwindow.show_all() def on_member_activate(self, *args): memberwindow.show_all() def on_catalog_activate(self, *args): 2.3. La guida completa alla Zope Component Architecture 197
- 202. Documentazione di Plone, Release 4 catalogwindow.show_all() def on_about_activate(self, *args): pass def run(self): self.mainwindow.show_all() def main(): mainwindow = MainWindow() mainwindow.run() gtk.main() La funzione main crea un’istanza della classe MainWindow che inizializza tutti i widget. Ecco qui memberwindow.py: import os import gtk import gtk.glade from zope.component import getAdapter from components import Member from interfaces import IDbOperation class MemberWindow(object): def __init__(self): curdir = os.path.abspath(os.path.dirname(__file__)) xml = os.path.join(curdir, ’glade’, ’memberwindow.glade’) xmlobj = gtk.glade.XML(xml) self.memberwindow = xmlobj.get_widget(’memberwindow’) self.number = xmlobj.get_widget(’number’) self.name = xmlobj.get_widget(’name’) add = xmlobj.get_widget(’add’) update = xmlobj.get_widget(’update’) delete = xmlobj.get_widget(’delete’) close = xmlobj.get_widget(’close’) self.treeview = xmlobj.get_widget(’treeview’) self.memberwindow.connect(’delete_event’, self.on_delete_event) add.connect(’clicked’, self.on_add_clicked) update.connect(’clicked’, self.on_update_clicked) delete.connect(’clicked’, self.on_delete_clicked) close.connect(’clicked’, self.on_delete_event) self.initialize_list() def show_all(self): self.populate_list_store() self.memberwindow.show_all() def populate_list_store(self): self.list_store.clear() member = Member() memberdboperation = getAdapter(member, IDbOperation) 198 Capitolo 2. Altri manuali
- 203. Documentazione di Plone, Release 4 members = memberdboperation.get() for member in members: number = member.number name = member.name self.list_store.append((member, number, name,)) def on_delete_event(self, *args): self.memberwindow.hide() return True def initialize_list(self): self.list_store = gtk.ListStore(object, str, str) self.treeview.set_model(self.list_store) tvcolumn = gtk.TreeViewColumn(’Member Number’) self.treeview.append_column(tvcolumn) cell = gtk.CellRendererText() tvcolumn.pack_start(cell, True) tvcolumn.add_attribute(cell, ’text’, 1) tvcolumn = gtk.TreeViewColumn(’Member Name’) self.treeview.append_column(tvcolumn) cell = gtk.CellRendererText() tvcolumn.pack_start(cell, True) tvcolumn.add_attribute(cell, ’text’, 2) def on_add_clicked(self, *args): number = self.number.get_text() name = self.name.get_text() member = Member() member.number = number member.name = name self.add(member) self.list_store.append((member, number, name,)) def add(self, member): memberdboperation = getAdapter(member, IDbOperation) memberdboperation.add() def on_update_clicked(self, *args): number = self.number.get_text() name = self.name.get_text() treeselection = self.treeview.get_selection() model, iter = treeselection.get_selected() if not iter: return member = self.list_store.get_value(iter, 0) member.number = number member.name = name self.update(member) self.list_store.set(iter, 1, number, 2, name) def update(self, member): memberdboperation = getAdapter(member, IDbOperation) memberdboperation.update() def on_delete_clicked(self, *args): 2.3. La guida completa alla Zope Component Architecture 199
- 204. Documentazione di Plone, Release 4 treeselection = self.treeview.get_selection() model, iter = treeselection.get_selected() if not iter: return member = self.list_store.get_value(iter, 0) self.delete(member) self.list_store.remove(iter) def delete(self, member): memberdboperation = getAdapter(member, IDbOperation) memberdboperation.delete() memberwindow = MemberWindow() Ecco qui components.py: from zope.interface import implements from interfaces import IBook from interfaces import IMember from interfaces import ICirculation class Book(object): implements(IBook) barcode = "" title = "" author = "" class Member(object): implements(IMember) number = "" name = "" class Circulation(object): implements(ICirculation) book = Book() member = Member() Ecco qui interfaces.py: from zope.interface import Interface from zope.interface import Attribute class IBook(Interface): barcode = Attribute("Barcode") author = Attribute("Author of book") title = Attribute("Title of book") class IMember(Interface): 200 Capitolo 2. Altri manuali
- 205. Documentazione di Plone, Release 4 number = Attribute("ID number") name = Attribute("Name of member") class ICirculation(Interface): book = Attribute("A book") member = Attribute("A member") class IRelationalDatabase(Interface): def commit(): pass def rollback(): pass def cursor(): pass def get_next_id(): pass class IObjectDatabase(Interface): def commit(): pass def rollback(): pass def container(): pass def get_next_id(): pass class IDbOperation(Interface): def get(): pass def add(): pass def update(): pass def delete(): pass Ecco qui member.py: from zope.interface import implements from zope.component import getUtility 2.3. La guida completa alla Zope Component Architecture 201
- 206. Documentazione di Plone, Release 4 from zope.component import adapts from components import Member from from from from interfaces interfaces interfaces interfaces import import import import IRelationalDatabase IObjectDatabase IMember IDbOperation class MemberRDbOperation(object): implements(IDbOperation) adapts(IMember) def __init__(self, member): self.member = member def get(self): db = getUtility(IRelationalDatabase) cr = db.cursor() number = self.member.number if number: cr.execute("""SELECT id, number, name FROM members WHERE number = ?""", (number,)) else: cr.execute("""SELECT id, number, name FROM members""") rst = cr.fetchall() cr.close() members = [] for record in rst: id = record[’id’] number = record[’number’] name = record[’name’] member = Member() member.id = id member.number = number member.name = name members.append(member) return members def add(self): db = getUtility(IRelationalDatabase) cr = db.cursor() next_id = db.get_next_id("members") number = self.member.number name = self.member.name cr.execute("""INSERT INTO members (id, number, name) 202 Capitolo 2. Altri manuali
- 207. Documentazione di Plone, Release 4 VALUES (?, ?, ?)""", (next_id, number, name)) cr.close() db.commit() self.member.id = next_id def update(self): db = getUtility(IRelationalDatabase) cr = db.cursor() number = self.member.number name = self.member.name id = self.member.id cr.execute("""UPDATE members SET number = ?, name = ? WHERE id = ?""", (number, name, id)) cr.close() db.commit() def delete(self): db = getUtility(IRelationalDatabase) cr = db.cursor() id = self.member.id cr.execute("""DELETE FROM members WHERE id = ?""", (id,)) cr.close() db.commit() class MemberODbOperation(object): implements(IDbOperation) adapts(IMember) def __init__(self, member): self.member = member def get(self): db = getUtility(IObjectDatabase) zcalibdb = db.container() members = zcalibdb[’members’] return members.values() def add(self): db = getUtility(IObjectDatabase) zcalibdb = db.container() members = zcalibdb[’members’] number = self.member.number if number in [x.number for x in members.values()]: db.rollback() raise Exception("Duplicate key") next_id = db.get_next_id(’members’) self.member.id = next_id members[next_id] = self.member db.commit() 2.3. La guida completa alla Zope Component Architecture 203
- 208. Documentazione di Plone, Release 4 def update(self): db = getUtility(IObjectDatabase) zcalibdb = db.container() members = zcalibdb[’members’] id = self.member.id members[id] = self.member db.commit() def delete(self): db = getUtility(IObjectDatabase) zcalibdb = db.container() members = zcalibdb[’members’] id = self.member.id del members[id] db.commit() PySQLite ZODB Conclusions 2.3.9 Riferimenti adaptedBy Questa funzione permette di trovare le interfacce adattate. • Posizione: zope.component • Firma: adaptedBy(object) Esempio: >>> from zope.interface import implements >>> from zope.component import adapts >>> from zope.component import adaptedBy >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest >>> adaptedBy(FrontDeskNG) (<InterfaceClass __builtin__.IGuest>,) adapter Qualsiasi tipo di oggetto può essere un adattatore, è possibile utilizzare il decoratore adapter per dichiarare che un oggetto chiamabile adatta qualche interfaccia (o classe) • Posizione: zope.component 204 Capitolo 2. Altri manuali
- 209. Documentazione di Plone, Release 4 • Firma: adapter(*interfaces) Esempio: >>> >>> >>> >>> >>> from from from from from zope.interface zope.interface zope.interface zope.component zope.interface import import import import import Attribute Interface implementer adapter implements >>> class IJob(Interface): ... """A job""" >>> class Job(object): ... implements(IJob) >>> class IPerson(Interface): ... ... name = Attribute("Name") ... job = Attribute("Job") >>> class Person(object): ... implements(IPerson) ... ... name = None ... job = None >>> @implementer(IJob) ... @adapter(IPerson) ... def personJob(person): ... return person.job >>> jack = Person() >>> jack.name = "Jack" >>> jack.job = Job() >>> personJob(jack) <Job object at ...> adapts Questa funzione permette di dichiarare le interfacce adattate dall’adapter • Posizione: zope.component • Firma: adapts(*interfaces) Esempio: >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... 2.3. La guida completa alla Zope Component Architecture 205
- 210. Documentazione di Plone, Release 4 def register(self): next_id = get_next_id() bookings_db[next_id] = { ’name’: guest.name, ’place’: guest.place, ’phone’: guest.phone } ... ... ... ... ... ... ... alsoProvides Dichiara le interfacce fornite direttamente da un oggetto. Gli argomenti dopo l’oggetto sono una o più interfacce. Le interfacce fornite vengono aggiunte alle interfacce già dichiarate per l’oggetto. • Posizione: zope.interface • Firma: alsoProvides(object, *interfaces) Esempio: >>> >>> >>> >>> from from from from zope.interface zope.interface zope.interface zope.interface import import import import Attribute Interface implements alsoProvides >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class Person(object): ... ... implements(IDesk) ... name = u"" jack = Person() jack.name = "Jack" jack.college = "New College" alsoProvides(jack, IStudent) >>> >>> >>> >>> Si può testare così: >>> from zope.interface import providedBy >>> IStudent in providedBy(jack) True Attribute Con questa classe è possibile definire i normali attributi di una interfaccia. • Posizione: zope.interface • Firma: Attribute(name, doc=’‘) • Vedi anche: Interface 206 Capitolo 2. Altri manuali
- 211. Documentazione di Plone, Release 4 Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IPerson(Interface): ... ... name = Attribute("Name of person") ... email = Attribute("Email Address") classImplements Dichiara le interfacce aggiuntive implementate dalle istanze di una classe. Gli argomenti dopo la classe sono una o più interfacce. Le interfacce fornite vengono aggiunte alle interfacce già dichiarate. • Posizione: zope.interface • Firma: classImplements(cls, *interfaces) Esempio: >>> >>> >>> >>> from from from from zope.interface zope.interface zope.interface zope.interface import import import import Attribute Interface implements classImplements >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class Person(object): ... ... implements(IDesk) ... name = u"" ... college = u"" >>> >>> >>> >>> classImplements(Person, IStudent) jack = Person() jack.name = "Jack" jack.college = "New College" Si può testare così: >>> from zope.interface import providedBy >>> IStudent in providedBy(jack) True classImplementsOnly Dichiara le sole interfacce implementate dalle istanze di una classe. Gli argomenti dopo la classe sono una o più interfacce. Le interfacce fornite rimpiazzano le dichiarazioni precedenti. • Posizione: zope.interface 2.3. La guida completa alla Zope Component Architecture 207
- 212. Documentazione di Plone, Release 4 • Firma: classImplementsOnly(cls, *interfaces) Esempio: >>> >>> >>> >>> from from from from zope.interface zope.interface zope.interface zope.interface import import import import Attribute Interface implements classImplementsOnly >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class Person(object): ... ... implements(IPerson) ... college = u"" >>> classImplementsOnly(Person, IStudent) >>> jack = Person() >>> jack.college = "New College" Si può testare così: >>> from zope.interface import providedBy >>> IPerson in providedBy(jack) False >>> IStudent in providedBy(jack) True classProvides Normalmente se una classe implementa una particolare interfaccia, l’istanza di questa classe fornirà l’interfaccia implementata da questa classe. Se però si vuole che la classe stessa fornisca un’interfaccia, si può utilizzare questa funzione. • Posizione: zope.interface • Firma: classProvides(*interfaces) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import classProvides >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class Person(object): ... ... classProvides(IPerson) ... name = u"Jack" 208 Capitolo 2. Altri manuali
- 213. Documentazione di Plone, Release 4 Si può testare così: >>> from zope.interface import providedBy >>> IPerson in providedBy(Person) True ComponentLookupError Questa è l’eccezione che viene sollevata quando una ricerca di un componente fallisce. Esempio: >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> person = object() >>> getAdapter(person, IPerson, ’not-exists’) Traceback (most recent call last): ... ComponentLookupError: ... createObject Crea un oggetto usando una factory. Cerca la named factory nel sito corrente e la chiama con i parametri forniti. Se non può essere trovata alcuna factory, viene sollevata l’eccezione ComponentLookupError altrimenti restituisce l’oggetto creato. Può essere fornito come argomento keyword un context per forzare la ricerca della factory in una posizione diversa dal sito corrente. Ovviamente questo significa che è impossibile passare un argomento keyword alla factory chiamato “context”. • Posizione: zope.component • Firma: createObject(factory_name, *args, **kwargs) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IDatabase(Interface): ... ... def getConnection(): ... """Return connection object""" >>> class FakeDb(object): ... ... implements(IDatabase) ... ... def getConnection(self): ... return "connection" >>> from zope.component.factory import Factory >>> factory = Factory(FakeDb, ’FakeDb’) 2.3. La guida completa alla Zope Component Architecture 209
- 214. Documentazione di Plone, Release 4 >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> from zope.component.interfaces import IFactory >>> gsm.registerUtility(factory, IFactory, ’fakedb’) >>> from zope.component import createObject >>> createObject(’fakedb’) <FakeDb object at ...> Declaration Non deve essere usata direttamente. directlyProvidedBy Questa funzione restituirà le interfacce fornite direttamente dall’oggetto passato come argomento. • Posizione: zope.interface • Firma: directlyProvidedBy(object) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class ISmartPerson(Interface): ... pass >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> >>> >>> >>> jack = Person() jack.name = u"Jack" jack.college = "New College" alsoProvides(jack, ISmartPerson, IStudent) >>> from zope.interface import directlyProvidedBy >>> jack_dp = directlyProvidedBy(jack) >>> IPerson in jack_dp.interfaces() False >>> IStudent in jack_dp.interfaces() True >>> ISmartPerson in jack_dp.interfaces() True 210 Capitolo 2. Altri manuali
- 215. Documentazione di Plone, Release 4 directlyProvides Dichiara le interfacce fornite direttamente da un oggetto. Gli argomenti dopo l’oggetto sono una o più interfacce. Le interfacce fornite rimpiazzano le interfacce già dichiarate in precedenza dall’oggetto. • Posizione: zope.interface • Firma: directlyProvides(object, *interfaces) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class ISmartPerson(Interface): ... pass >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> >>> >>> >>> jack = Person() jack.name = u"Jack" jack.college = "New College" alsoProvides(jack, ISmartPerson, IStudent) >>> from zope.interface import directlyProvidedBy >>> jack_dp = directlyProvidedBy(jack) >>> ISmartPerson in jack_dp.interfaces() True >>> IPerson in jack_dp.interfaces() False >>> IStudent in jack_dp.interfaces() True >>> from zope.interface import providedBy >>> ISmartPerson in providedBy(jack) True >>> from zope.interface import directlyProvides >>> directlyProvides(jack, IStudent) >>> jack_dp = directlyProvidedBy(jack) >>> ISmartPerson in jack_dp.interfaces() False >>> IPerson in jack_dp.interfaces() False >>> IStudent in jack_dp.interfaces() True 2.3. La guida completa alla Zope Component Architecture 211
- 216. Documentazione di Plone, Release 4 >>> ISmartPerson in providedBy(jack) False getAdapter Recupera un adapter per un oggetto verso una specifica interfaccia. Restituisce un adapter che può adattare l’oggetto all’interfaccia. Se non può essere trovato alcun adapter, solleva ComponentLookupError. • Posizione: zope.interface • Firma: getAdapter(object, interface=Interface, name=u’‘, context=None) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager 212 Capitolo 2. Altri manuali
- 217. Documentazione di Plone, Release 4 >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng’) >>> getAdapter(jack, IDesk, ’ng’) <FrontDeskNG object at ...> getAdapterInContext Al posto di questa funzione, utilizzare l’argomento context della funzione getAdapter. • Posizione: zope.component • Firma: getAdapterInContext(object, interface, context) • Vedi anche: queryAdapterInContext Esempio: >>> from zope.component.globalregistry import BaseGlobalComponents >>> from zope.component import IComponentLookup >>> sm = BaseGlobalComponents() >>> class Context(object): ... def __init__(self, sm): ... self.sm = sm ... def __conform__(self, interface): ... if interface.isOrExtends(IComponentLookup): ... return self.sm >>> context = Context(sm) >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, 2.3. La guida completa alla Zope Component Architecture 213
- 218. Documentazione di Plone, Release 4 ’phone’: guest.phone } ... ... >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> sm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk) >>> from zope.component import getAdapterInContext >>> getAdapterInContext(jack, IDesk, sm) <FrontDeskNG object at ...> getAdapters Cerca tutti gli adapter corrispondenti per degli oggetti e per una interfaccia fornita. Restituisce una lista di adapter che corrispondono. Se un adapter ha un nome, viene restituito solo l’adapter più specifico. • Posizione: zope.component • Firma: getAdapters(objects, provided, context=None) Esempio: >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } >>> jack = Guest("Jack", "Bangalore") 214 Capitolo 2. Altri manuali
- 219. Documentazione di Plone, Release 4 >>> jack_frontdesk = FrontDeskNG(jack) >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, name=’ng’) >>> from zope.component import getAdapters >>> list(getAdapters((jack,), IDesk)) [(u’ng’, <FrontDeskNG object at ...>)] getAllUtilitiesRegisteredFor Restituisce tutte le utility registrate per un’interfaccia. Questo include anche le utility sovrascritte. Il valore di ritorno è un iterabile di istanze di utility. • Posizione: zope.component • Firma: getAllUtilitiesRegisteredFor(interface) Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... print "Hello", name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter) >>> from zope.component import getAllUtilitiesRegisteredFor >>> getAllUtilitiesRegisteredFor(IGreeter) [<Greeter object at ...>] getFactoriesFor Restituisce una tupla (nome, factory) delle factory registrate che creano oggetti che implementano l’interfaccia fornita. • Posizione: zope.component • Firma: getFactoriesFor(interface, context=None) Esempio: 2.3. La guida completa alla Zope Component Architecture 215
- 220. Documentazione di Plone, Release 4 >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IDatabase(Interface): ... ... def getConnection(): ... """Return connection object""" >>> class FakeDb(object): ... ... implements(IDatabase) ... ... def getConnection(self): ... return "connection" >>> from zope.component.factory import Factory >>> factory = Factory(FakeDb, ’FakeDb’) >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> from zope.component.interfaces import IFactory >>> gsm.registerUtility(factory, IFactory, ’fakedb’) >>> from zope.component import getFactoriesFor >>> list(getFactoriesFor(IDatabase)) [(u’fakedb’, <Factory for <class ’FakeDb’>>)] getFactoryInterfaces Trova le interfacce implementate da una factory. Trova la factory più vicina al contesto con il nome specificato e restituisce l’interfaccia o la tupla dell’interfaccia che gli oggetti istanza creati forniranno. • Posizione: zope.component • Firma: getFactoryInterfaces(name, context=None) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IDatabase(Interface): ... ... def getConnection(): ... """Return connection object""" >>> class FakeDb(object): ... ... implements(IDatabase) ... ... def getConnection(self): ... return "connection" 216 Capitolo 2. Altri manuali
- 221. Documentazione di Plone, Release 4 >>> from zope.component.factory import Factory >>> factory = Factory(FakeDb, ’FakeDb’) >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> from zope.component.interfaces import IFactory >>> gsm.registerUtility(factory, IFactory, ’fakedb’) >>> from zope.component import getFactoryInterfaces >>> getFactoryInterfaces(’fakedb’) <implementedBy __builtin__.FakeDb> getGlobalSiteManager Restituisce il global site manager. Questa funzione non dovrebbe mai fallire e dovrebbe sempre restituire un oggetto che fornisce IGlobalSiteManager • Posizione: zope.component • Firma: getGlobalSiteManager() Esempio: >>> from zope.component import getGlobalSiteManager >>> from zope.component import globalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm is globalSiteManager True getMultiAdapter Cerca e restituisce un multi-adapter che può adattare degli oggetti ad una certa interfaccia. Se non può essere trovato alcun adapter, solleva ComponentLookupError. La stringa vuota come nome è riservata per gli adapter senza nome. I metodi per gli adapter senza nome spesso chiamano i metodi per i named adapter con una stringa vuota come nome. • Posizione: zope.component • Firma: getMultiAdapter(objects, interface=Interface, name=’‘, context=None) • Vedi anche: queryMultiAdapter Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> from zope.component import adapts >>> class IAdapteeOne(Interface): ... pass >>> class IAdapteeTwo(Interface): ... pass >>> class IFunctionality(Interface): 2.3. La guida completa alla Zope Component Architecture 217
- 222. Documentazione di Plone, Release 4 ... pass >>> class MyFunctionality(object): ... implements(IFunctionality) ... adapts(IAdapteeOne, IAdapteeTwo) ... ... def __init__(self, one, two): ... self.one = one ... self.two = two >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(MyFunctionality) >>> class One(object): ... implements(IAdapteeOne) >>> class Two(object): ... implements(IAdapteeTwo) >>> one = One() >>> two = Two() >>> from zope.component import getMultiAdapter >>> getMultiAdapter((one,two), IFunctionality) <MyFunctionality object at ...> >>> myfunctionality = getMultiAdapter((one,two), IFunctionality) >>> myfunctionality.one <One object at ...> >>> myfunctionality.two <Two object at ...> getSiteManager Prende il site manager più vicino al contesto dato. Se il context è None, restituisce il global site manager. Se il context non è None, ci si aspetta di poter trovare un adapter dal context a IComponentLookup. Se non viene trovato alcun adapter, viene sollevato ComponentLookupError. • Posizione: zope.component • Firma: getSiteManager(context=None) Esempio 1: >>> from zope.component.globalregistry import BaseGlobalComponents >>> from zope.component import IComponentLookup >>> sm = BaseGlobalComponents() >>> class Context(object): ... def __init__(self, sm): ... self.sm = sm ... def __conform__(self, interface): ... if interface.isOrExtends(IComponentLookup): ... return self.sm 218 Capitolo 2. Altri manuali
- 223. Documentazione di Plone, Release 4 >>> context = Context(sm) >>> from zope.component import getSiteManager >>> lsm = getSiteManager(context) >>> lsm is sm True Esempio 2: >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> sm = getSiteManager() >>> gsm is sm True getUtilitiesFor Ricerca le utility registrate che forniscono un’interfaccia. Restituisce un iterabile delle coppie nome-utility. • Posizione: zope.component • Firma: getUtilitiesFor(interface) Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... print "Hello", name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter) >>> from zope.component import getUtilitiesFor >>> list(getUtilitiesFor(IGreeter)) [(u’’, <Greeter object at ...>)] getUtility Recupera l’utility che fornisce l’interfaccia. Restituisce l’utility più vicina al contesto e che implementa una una specifica interfaccia. Se non nè vengono trovate, viene sollevata ComponentLookupError. • Posizione: zope.component 2.3. La guida completa alla Zope Component Architecture 219
- 224. Documentazione di Plone, Release 4 • Firma: getUtility(interface, name=’‘, context=None) Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... return "Hello " + name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter) >>> from zope.component import getUtility >>> getUtility(IGreeter).greet(’Jack’) ’Hello Jack’ handle Chiama tutti gli handler per gli oggetti dati. Gli handler sono fabbriche di subscription adapter che non restituiscono nulla. Essi fanno tutto il loro lavoro quando vengono chiamati. Gli handler sono tipicamente utilizzati per gestire gli eventi. • Posizione: zope.component • Firma: handle(*objects) Esempio: >>> import datetime >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IDocumentCreated(Interface): ... doc = Attribute("The document that was created") >>> class DocumentCreated(object): ... implements(IDocumentCreated) ... ... def __init__(self, doc): ... self.doc = doc 220 Capitolo 2. Altri manuali
- 225. Documentazione di Plone, Release 4 >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import adapter >>> @adapter(IDocumentCreated) ... def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerHandler(documentCreated) >>> from zope.component import handle >>> handle(DocumentCreated(doc)) >>> doc.created.__class__.__name__ ’datetime’ implementedBy Restituisce le interfacce implementate dalle istanze di una certa classe. • Posizione: zope.interface • Firma: implementedBy(class_) Esempio 1: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... print "Hello", name >>> from zope.interface import implementedBy >>> implementedBy(Greeter) <implementedBy __builtin__.Greeter> Esempio 2: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IPerson(Interface): ... name = Attribute("Name of person") 2.3. La guida completa alla Zope Component Architecture 221
- 226. Documentazione di Plone, Release 4 >>> class ISpecial(Interface): ... pass >>> class Person(object): ... implements(IPerson) ... name = u"" >>> from zope.interface import classImplements >>> classImplements(Person, ISpecial) >>> from zope.interface import implementedBy To get a list of all interfaces implemented by that class:: >>> [x.__name__ for x in implementedBy(Person)] [’IPerson’, ’ISpecial’] implementer Crea un decoratore per dichiarare le interfacce implementate da una factory. Viene restituito un oggetto chiamabile che fa una dichiarazione di implementazione sugli oggetti che gli vengono passati. • Posizione: zope.interface • Firma: implementer(*interfaces) Esempio: >>> from zope.interface import implementer >>> class IFoo(Interface): ... pass >>> class Foo(object): ... implements(IFoo) >>> @implementer(IFoo) ... def foocreator(): ... foo = Foo() ... return foo >>> list(implementedBy(foocreator)) [<InterfaceClass __builtin__.IFoo>] implements Dichiara le interfacce implementate dalle istanze di una classe. Questa funzione è chiamata all’interno di una definizione di una classe. Gli argomenti sono una o più interfacce. Le interfacce fornite sono aggiunte a quelle già dichiarate in precedenza. Le dichiarazioni precedenti, incluse le dichiarazioni delle classi base, vengono preservate, a meno che non sia stata utilizzata implementsOnly. • Posizione: zope.interface • Firma: implements(*interfaces) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements 222 Capitolo 2. Altri manuali
- 227. Documentazione di Plone, Release 4 >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> jack = Person() >>> jack.name = "Jack" Si può testare così: >>> from zope.interface import providedBy >>> IPerson in providedBy(jack) True implementsOnly Dichiara le sole interfacce implementate dalle istanze di una classe. Questa funzione è chiamata all’interno di una definizione di classe. Gli argomenti sono una o più interfacce. Le dichiarazioni precedenti, incluse le dichiarazioni delle classi base, vengono sovrascritte. • Posizione: zope.interface • Firma: implementsOnly(*interfaces) Esempio: >>> >>> >>> >>> from from from from zope.interface zope.interface zope.interface zope.interface import import import import Attribute Interface implements implementsOnly >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> class NewPerson(Person): ... implementsOnly(IStudent) ... college = u"" >>> jack = NewPerson() >>> jack.college = "New College" Si può testare così: >>> from zope.interface import providedBy 2.3. La guida completa alla Zope Component Architecture 223
- 228. Documentazione di Plone, Release 4 >>> IPerson in providedBy(jack) False >>> IStudent in providedBy(jack) True Interface Con questa classe si possono definire le interfacce. Interface. Per definire un’interfaccia, basta ereditare dalla classe • Posizione: zope.interface • Firma: Interface(name, doc=’‘) Esempio 1: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IPerson(Interface): ... ... name = Attribute("Name of person") ... email = Attribute("Email Address") Esempio 2: >>> from zope.interface import Interface >>> class IHost(Interface): ... ... def goodmorning(guest): ... """Say good morning to guest""" moduleProvides Dichiara le interfacce fornite da un modulo. Questa funzione è utilizzata nella definizione di un modulo. Gli argomenti sono una o più interfacce. Le interfacce fornite vengono utilizzate per creare la definizione di interfaccia degli oggetti diretti del modulo. Verrà sollevato un errore se il modulo ha già una dichiarazione di interfaccia. In altre parole, è un errore chiamare questa funzione più di una volta nella definizione di un modulo. Questa funzione è fornita per comodità. Essa fornisce un modo più conveniente per chiamare directlyProvides su un modulo. • Posizione: zope.interface • Firma: moduleProvides(*interfaces) • Vedi anche: directlyProvides You can see an example usage in zope.component source itself. The __init__.py file has a statement like this: moduleProvides(IComponentArchitecture, IComponentRegistrationConvenience) So, the zope.component provides two interfaces: IComponentArchitecture and IComponentRegistrationConvenience. 224 Capitolo 2. Altri manuali
- 229. Documentazione di Plone, Release 4 noLongerProvides Rimuove un’interfaccia dalla lista delle interfacce fornite direttamente da un oggetto. • Posizione: zope.interface • Firma: noLongerProvides(object, interface) Esempio: >>> >>> >>> >>> from from from from zope.interface zope.interface zope.interface zope.interface import import import import Attribute Interface implements classImplements >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class IStudent(Interface): ... ... college = Attribute("Name of college") >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> >>> >>> >>> jack = Person() jack.name = "Jack" jack.college = "New College" directlyProvides(jack, IStudent) Si può testare così: >>> from zope.interface import providedBy >>> IPerson in providedBy(jack) True >>> IStudent in providedBy(jack) True >>> from zope.interface import noLongerProvides >>> noLongerProvides(jack, IStudent) >>> IPerson in providedBy(jack) True >>> IStudent in providedBy(jack) False provideAdapter Si raccomanda di utilizzare registerAdapter al posto di questa funzione. provideHandler Si raccomanda di utilizzare registerHandler al posto di questa funzione. 2.3. La guida completa alla Zope Component Architecture 225
- 230. Documentazione di Plone, Release 4 provideSubscriptionAdapter Si raccomanda di utilizzare registerSubscriptionAdapter al posto di questa funzione. provideUtility Si raccomanda di utilizzare registerUtility al posto di questa funzione. providedBy Verifica se l’interfaccia è fornita dall’oggetto dato. Restituisce true se l’oggetto dichiara di fornire l’interfaccia, anche se dichiara di fornire un’interfaccia che estende l’interfaccia data. • Posizione: zope.interface • Firma: providedBy(object) Esempio 1: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IPerson(Interface): ... ... name = Attribute("Name of person") >>> class Person(object): ... ... implements(IPerson) ... name = u"" >>> jack = Person() >>> jack.name = "Jack" Si può testare così: >>> from zope.interface import providedBy >>> IPerson in providedBy(jack) True Esempio 2: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IPerson(Interface): ... name = Attribute("Name of person") >>> class ISpecial(Interface): ... pass >>> class Person(object): ... implements(IPerson) ... name = u"" >>> from zope.interface import classImplements 226 Capitolo 2. Altri manuali
- 231. Documentazione di Plone, Release 4 >>> >>> >>> >>> classImplements(Person, ISpecial) from zope.interface import providedBy jack = Person() jack.name = "Jack" Ecco come vere la lista di tutte le interfacce fornite da questo oggetto:: >>> [x.__name__ for x in providedBy(jack)] [’IPerson’, ’ISpecial’] queryAdapter Cerca e restituisce un named adapter che può adattare un oggetto ad un’interfaccia. Se non può essere trovato alcun adapter restituisce il default. • Posizione: zope.component • Firma: queryAdapter(object, interface=Interface, name=u’‘, default=None, context=None) Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place 2.3. La guida completa alla Zope Component Architecture 227
- 232. Documentazione di Plone, Release 4 >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng’) >>> queryAdapter(jack, IDesk, ’ng’) <FrontDeskNG object at ...> queryAdapterInContext Cerca uno speciale adapter per adattare un oggetto a un’interfaccia. Nota: Questo metodo dovrebbe essere utilizzato solo se è necessario fornire un context personalizzato per fornire una ricerca personalizzata. Altrimenti, chiamare l’interfaccia come in: interface(object, default) Restituisce un adapter che può adattare un oggetto a un’interfaccia. Se non può essere trovato alcun adapter, restituisce il default. Il context viene adattato a IServiceService, e viene utilizzato il servizio ‘Adapters’ di questo adapter. Se l’oggetto ha un metodo __conform__, questo metodo viene chiamato con l’interfaccia richiesta. Se il metodo restituisce un valore diverso da None, questo valore viene restituito. Altrimenti, se l’oggetto implementa già l’interfaccia, viene restituito l’oggetto. • Posizione: zope.component • Firma: queryAdapterInContext(object, interface, context, default=None) • Vedi anche: getAdapterInContext Esempio: >>> from zope.component.globalregistry import BaseGlobalComponents >>> from zope.component import IComponentLookup >>> sm = BaseGlobalComponents() >>> class Context(object): ... def __init__(self, sm): ... self.sm = sm ... def __conform__(self, interface): ... if interface.isOrExtends(IComponentLookup): ... return self.sm >>> context = Context(sm) >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... 228 Capitolo 2. Altri manuali
- 233. Documentazione di Plone, Release 4 ... ... ... def register(): """Register object’s details""" >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> sm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk) >>> from zope.component import queryAdapterInContext >>> queryAdapterInContext(jack, IDesk, sm) <FrontDeskNG object at ...> queryMultiAdapter Cerca e restituisce un multi-adapter per adattare degli oggetti a un’interfaccia. Se non può essere trovato alcun adapter, restituisce il default. Il nome costituito dalla stringa vuota è riservato per gli adapters senza nome. I metodi per gli unnamed adapter spesso chiamano i metodi per i named adapter con una stringa vuota come nome. • Posizione: zope.component • Firma: queryMultiAdapter(objects, interface=Interface, name=u’‘, default=None, context=None) • Vedi anche: getMultiAdapter 2.3. La guida completa alla Zope Component Architecture 229
- 234. Documentazione di Plone, Release 4 Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> from zope.component import adapts >>> class IAdapteeOne(Interface): ... pass >>> class IAdapteeTwo(Interface): ... pass >>> class IFunctionality(Interface): ... pass >>> class MyFunctionality(object): ... implements(IFunctionality) ... adapts(IAdapteeOne, IAdapteeTwo) ... ... def __init__(self, one, two): ... self.one = one ... self.two = two >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(MyFunctionality) >>> class One(object): ... implements(IAdapteeOne) >>> class Two(object): ... implements(IAdapteeTwo) >>> one = One() >>> two = Two() >>> from zope.component import queryMultiAdapter >>> getMultiAdapter((one,two), IFunctionality) <MyFunctionality object at ...> >>> myfunctionality = queryMultiAdapter((one,two), IFunctionality) >>> myfunctionality.one <One object at ...> >>> myfunctionality.two <Two object at ...> queryUtility Questa funzione è utilizzata per cercare una utility che fornisce una certa interfaccia. Se non trova alcuna utility, restituisce il default. • Posizione: zope.component • Firma: queryUtility(interface, name=’‘, default=None) Esempio: 230 Capitolo 2. Altri manuali
- 235. Documentazione di Plone, Release 4 >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... return "Hello " + name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet, IGreeter) >>> from zope.component import queryUtility >>> queryUtility(IGreeter).greet(’Jack’) ’Hello Jack’ registerAdapter Questa funzione registra una factory di adapter. • Posizione: zope.component - IComponentRegistry • Firma: registerAdapter(factory, required=None, provided=None, name=u’‘, info=u’‘) • Vedi anche: unregisterAdapter Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): 2.3. La guida completa alla Zope Component Architecture 231
- 236. Documentazione di Plone, Release 4 next_id = get_next_id() bookings_db[next_id] = { ’name’: guest.name, ’place’: guest.place, ’phone’: guest.phone } ... ... ... ... ... ... >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng’) Si può testare così: >>> queryAdapter(jack, IDesk, ’ng’) <FrontDeskNG object at ...> registeredAdapters Restituisce un iterabile di IAdapterRegistrations. Queste registrazioni descrivono le attuali registrazioni degli adapter per l’oggetto. • Posizione: zope.component - IComponentRegistry • Firma: registeredAdapters() Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) 232 Capitolo 2. Altri manuali
- 237. Documentazione di Plone, Release 4 adapts(IGuest) ... ... ... ... ... ... ... ... ... ... ... ... def __init__(self, guest): self.guest = guest def register(self): next_id = get_next_id() bookings_db[next_id] = { ’name’: guest.name, ’place’: guest.place, ’phone’: guest.phone } >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng2’) >>> reg_adapter = list(gsm.registeredAdapters()) >>> ’ng2’ in [x.name for x in reg_adapter] True registeredHandlers Restituisce un iterabile di IHandlerRegistrations. Queste registrazioni descrivono le attuali registrazioni degli handler per l’oggetto. • Posizione: zope.component - IComponentRegistry • Firma: registeredHandlers() Esempio: >>> import datetime >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IDocumentCreated(Interface): 2.3. La guida completa alla Zope Component Architecture 233
- 238. Documentazione di Plone, Release 4 doc = Attribute("The document that was created") ... >>> class DocumentCreated(object): ... implements(IDocumentCreated) ... ... def __init__(self, doc): ... self.doc = doc >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import adapter >>> @adapter(IDocumentCreated) ... def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerHandler(documentCreated, info=’ng3’) >>> reg_adapter = list(gsm.registeredHandlers()) >>> ’ng3’ in [x.info for x in reg_adapter] True >>> gsm.registerHandler(documentCreated, name=’ng4’) Traceback (most recent call last): ... TypeError: Named handlers are not yet supported registeredSubscriptionAdapters Restituisce un iterabile di ISubscriptionAdapterRegistrations. Queste registrazioni descrivono le attuali registrazioni dei subscription adapter per l’oggetto. • Posizione: zope.component - IComponentRegistry • Firma: registeredSubscriptionAdapters() Esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IValidate(Interface): ... def validate(ob): ... """Determine whether the object is valid ... ... Return a string describing a validation problem. ... An empty string is returned to indicate that the ... object is valid. ... """ >>> class IDocument(Interface): 234 Capitolo 2. Altri manuali
- 239. Documentazione di Plone, Release 4 summary = Attribute("Document summary") body = Attribute("Document text") ... ... >>> class Document(object): ... implements(IDocument) ... def __init__(self, summary, body): ... self.summary, self.body = summary, body >>> from zope.component import adapts >>> class AdequateLength(object): ... ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if len(self.doc.body) < 1000: ... return ’too short’ ... else: ... return ’’ >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerSubscriptionAdapter(AdequateLength, info=’ng4’) >>> reg_adapter = list(gsm.registeredSubscriptionAdapters()) >>> ’ng4’ in [x.info for x in reg_adapter] True registeredUtilities Restituisce un iterabile di IUtilityRegistrations. Queste registrazioni descrivono le attuali registrazioni delle utility per l’oggetto. • Posizione: zope.component - IComponentRegistry • Firma: registeredUtilities() Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... print "Hello", name 2.3. La guida completa alla Zope Component Architecture 235
- 240. Documentazione di Plone, Release 4 >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet, info=’ng5’) >>> reg_adapter = list(gsm.registeredUtilities()) >>> ’ng5’ in [x.info for x in reg_adapter] True registerHandler Questa funzione registra un handler. Un handler è un subscriber che non calcola un adapter ma svolge qualche funzione quando viene chiamato. • Posizione: zope.component - IComponentRegistry • Firma: registerHandler(handler, required=None, name=u’‘, info=’‘) • Vedi anche: unregisterHandler Note: In the current implementation of zope.component doesn’t support name attribute. Esempio: >>> import datetime >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IDocumentCreated(Interface): ... doc = Attribute("The document that was created") >>> class DocumentCreated(object): ... implements(IDocumentCreated) ... ... def __init__(self, doc): ... self.doc = doc >>> def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import adapter >>> @adapter(IDocumentCreated) ... def documentCreated(event): ... event.doc.created = datetime.datetime.utcnow() >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerHandler(documentCreated) 236 Capitolo 2. Altri manuali
- 241. Documentazione di Plone, Release 4 >>> from zope.component import handle >>> handle(DocumentCreated(doc)) >>> doc.created.__class__.__name__ ’datetime’ registerSubscriptionAdapter Questa funzione serve a registrare una factory di subscribers. • Posizione: zope.component - IComponentRegistry • Firma: registerSubscriptionAdapter(factory, required=None, provides=None, name=u’‘, info=’‘) • Vedi anche: unregisterSubscriptionAdapter Esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IValidate(Interface): ... def validate(ob): ... """Determine whether the object is valid ... ... Return a string describing a validation problem. ... An empty string is returned to indicate that the ... object is valid. ... """ >>> class IDocument(Interface): ... summary = Attribute("Document summary") ... body = Attribute("Document text") >>> class Document(object): ... implements(IDocument) ... def __init__(self, summary, body): ... self.summary, self.body = summary, body >>> from zope.component import adapts >>> class AdequateLength(object): ... ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if len(self.doc.body) < 1000: ... return ’too short’ ... else: ... return ’’ >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() 2.3. La guida completa alla Zope Component Architecture 237
- 242. Documentazione di Plone, Release 4 >>> gsm.registerSubscriptionAdapter(AdequateLength) registerUtility Questa funzione serve a registrare una utility. • Posizione: zope.component - IComponentRegistry • Firma: registerUtility(component, provided=None, name=u’‘, info=u’‘) • Vedi anche: unregisterUtility Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... print "Hello", name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet) subscribers Questa funzione serve a recuperare i subscribers. Vengono restituiti i subscribers che forniscono l’interfaccia passata e che dipendono e sono calcolati dalla sequenza di oggetti richiesti. • Posizione: zope.component - IComponentRegistry • Firma: subscribers(required, provided, context=None) Esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IValidate(Interface): ... def validate(ob): ... """Determine whether the object is valid ... ... Return a string describing a validation problem. ... An empty string is returned to indicate that the ... object is valid. ... """ 238 Capitolo 2. Altri manuali
- 243. Documentazione di Plone, Release 4 >>> class IDocument(Interface): ... summary = Attribute("Document summary") ... body = Attribute("Document text") >>> class Document(object): ... implements(IDocument) ... def __init__(self, summary, body): ... self.summary, self.body = summary, body >>> from zope.component import adapts >>> class SingleLineSummary: ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if ’n’ in self.doc.summary: ... return ’Summary should only have one line’ ... else: ... return ’’ >>> class AdequateLength(object): ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if len(self.doc.body) < 1000: ... return ’too short’ ... else: ... return ’’ >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerSubscriptionAdapter(SingleLineSummary) >>> gsm.registerSubscriptionAdapter(AdequateLength) >>> from zope.component import subscribers >>> doc = Document("AnDocument", "blah") >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’Summary should only have one line’, ’too short’] >>> doc = Document("AnDocument", "blah" * 1000) >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’Summary should only have one line’] >>> doc = Document("A Document", "blah") 2.3. La guida completa alla Zope Component Architecture 239
- 244. Documentazione di Plone, Release 4 >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’too short’] unregisterAdapter Questa funzione serve a de-registrare una factory di adapter. Viene restituito un booleano che indica se il registro è stato modificato o meno. La funzione restituisce False se il componente dato è None e non ci sono componenti registrati, o se il componente dato non è None e non è registrato, altrimenti restituisce True. • Posizione: zope.component - IComponentRegistry • Firma: unregisterAdapter(factory=None, required=None, provided=None, name=u’‘) • Vedi anche: registerAdapter Esempio: >>> from zope.interface import Attribute >>> from zope.interface import Interface >>> class IDesk(Interface): ... """A frontdesk will register object’s details""" ... ... def register(): ... """Register object’s details""" ... >>> from zope.interface import implements >>> from zope.component import adapts >>> class FrontDeskNG(object): ... ... implements(IDesk) ... adapts(IGuest) ... ... def __init__(self, guest): ... self.guest = guest ... ... def register(self): ... next_id = get_next_id() ... bookings_db[next_id] = { ... ’name’: guest.name, ... ’place’: guest.place, ... ’phone’: guest.phone ... } >>> class Guest(object): ... ... implements(IGuest) ... ... def __init__(self, name, place): ... self.name = name ... self.place = place >>> jack = Guest("Jack", "Bangalore") >>> jack_frontdesk = FrontDeskNG(jack) 240 Capitolo 2. Altri manuali
- 245. Documentazione di Plone, Release 4 >>> IDesk.providedBy(jack_frontdesk) True >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerAdapter(FrontDeskNG, ... (IGuest,), IDesk, ’ng6’) Si può testare così: >>> queryAdapter(jack, IDesk, ’ng6’) <FrontDeskNG object at ...> Ora de-registriamo l’adapter: >>> gsm.unregisterAdapter(FrontDeskNG, name=’ng6’) True Dopo la de-registrazione si ha che: >>> print queryAdapter(jack, IDesk, ’ng6’) None unregisterHandler Questa funzione serve a de-registrare un handler. Un handler è un subscriber che non calcola un adapter ma svolge qualche funzione quando viene chiamato. Viene restituito un booleano che indica se il registro è stato modificato o meno. • Posizione: zope.component - IComponentRegistry • Firma: unregisterHandler(handler=None, required=None, name=u’‘) • Vedi anche: registerHandler Esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IDocument(Interface): ... ... summary = Attribute("Document summary") ... body = Attribute("Document text") >>> class Document(object): ... ... implements(IDocument) ... def __init__(self, summary, body): ... self.summary, self.body = summary, body >>> doc = Document("AnDocument", "blah") >>> class IDocumentAccessed(Interface): ... doc = Attribute("The document that was accessed") >>> class DocumentAccessed(object): 2.3. La guida completa alla Zope Component Architecture 241
- 246. Documentazione di Plone, Release 4 implements(IDocumentAccessed) ... ... ... ... ... def __init__(self, doc): self.doc = doc self.doc.count = 0 >>> from zope.component import adapter >>> @adapter(IDocumentAccessed) ... def documentAccessed(event): ... event.doc.count = event.doc.count + 1 >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerHandler(documentAccessed) >>> from zope.component import handle >>> handle(DocumentAccessed(doc)) >>> doc.count 1 Ora de-registriamo l’handler: >>> gsm.unregisterHandler(documentAccessed) True Dopo la de-registrazione si ha: >>> handle(DocumentAccessed(doc)) >>> doc.count 0 unregisterSubscriptionAdapter Questa funzione serve a de-registrare una factory di subscriber. Viene restituito un booleano che indica se il registro è stato modificato o meno. La funzione restituisce False se il componente dato è None e non ci sono componenti registrati, o se il componente dato non è None e non è registrato, altrimenti restituisce True. • Posizione: zope.component - IComponentRegistry • Firma: unregisterSubscriptionAdapter(factory=None, required=None, provides=None, name=u’‘) • Vedi anche: registerSubscriptionAdapter Esempio: >>> from zope.interface import Interface >>> from zope.interface import Attribute >>> from zope.interface import implements >>> class IValidate(Interface): ... def validate(ob): ... """Determine whether the object is valid ... ... Return a string describing a validation problem. ... An empty string is returned to indicate that the 242 Capitolo 2. Altri manuali
- 247. Documentazione di Plone, Release 4 ... ... object is valid. """ >>> class IDocument(Interface): ... summary = Attribute("Document summary") ... body = Attribute("Document text") >>> class Document(object): ... implements(IDocument) ... def __init__(self, summary, body): ... self.summary, self.body = summary, body >>> from zope.component import adapts >>> class AdequateLength(object): ... ... adapts(IDocument) ... implements(IValidate) ... ... def __init__(self, doc): ... self.doc = doc ... ... def validate(self): ... if len(self.doc.body) < 1000: ... return ’too short’ ... else: ... return ’’ >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> gsm.registerSubscriptionAdapter(AdequateLength) >>> from zope.component import subscribers >>> doc = Document("AnDocument", "blah") >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [’too short’] Ora de-registriamo il componente: >>> gsm.unregisterSubscriptionAdapter(AdequateLength) True Dopo la de-registrazione si ha: >>> [adapter.validate() ... for adapter in subscribers([doc], IValidate) ... if adapter.validate()] [] unregisterUtility Questa funzione serve a de-registrare una utility. Viene restituito un booleano che indica se il registro è stato modificato o meno. La funzione restituisce False se il componente dato è None e non ci sono componenti registrati, o se il 2.3. La guida completa alla Zope Component Architecture 243
- 248. Documentazione di Plone, Release 4 componente dato non è None e non è registrato, altrimenti restituisce True. • Posizione: zope.component - IComponentRegistry • Firma: unregisterUtility(component=None, provided=None, name=u’‘) • Vedi anche: registerUtility Esempio: >>> from zope.interface import Interface >>> from zope.interface import implements >>> class IGreeter(Interface): ... def greet(name): ... "say hello" >>> class Greeter(object): ... ... implements(IGreeter) ... ... def greet(self, name): ... return "Hello " + name >>> from zope.component import getGlobalSiteManager >>> gsm = getGlobalSiteManager() >>> greet = Greeter() >>> gsm.registerUtility(greet) >>> queryUtility(IGreeter).greet(’Jack’) ’Hello Jack’ Now unregister: >>> gsm.unregisterUtility(greet) True After unregistration: >>> print queryUtility(IGreeter) None 244 Capitolo 2. Altri manuali
- 249. CAPITOLO 3 Contributori Si ringraziano per il loro contributo a questa documentazione: • Giacomo Spettoli (coordinatore/traduttore/motivatore) • Maurizio Delmonte (ideatore/motivatore) • Massimo Azzolini (motivatore/traduttore) • Federica D’Elia (traduttore) • Giampiero Lago • Alex Sani • Luciano Naldesi 245