Il CMS Plone è molto potente. È capace di svolgere molti compiti, e li svolge in modo efficace. Ma uno dei più grandi vantaggi di Plone sta nella sua vasta e sempre crescente libreria di moduli aggiuntivi, chiamati "add-on products", che estendono Plone a diversi livelli. Molte delle componenti del nucleo di Plone sono nate proprio come moduli aggiuntivi, e questi ultimi rappresentano anche la maniera più usata per condividere e riutilizzare il codice nella community di Plone.

Questa guida è stata creata per aiutare gli sviluppatori che si avvicinano alla progettazione di nuovi prodotti add-on e che vogliono rendere i loro programmi di alta qualità, usabili e utili all'intera comunità. Sarà anche utile a quegli sviluppatori che vogliono conoscere buone norme per migliorare le loro tecniche di programmazione.

Hai realmente bisogno di scrivere un nuovo prodotto?

A volte il prodotto ideale non è ancora stato scritto perchè ci si concentra spesso sulle proprie esigenze, partendo a scrivere da zero senza considerare l'aiuto che può dare il lavoro fatto in precedenza da altri. Prima di iniziare a creare un prodotto da zero, è quindi sempre consigliabile impegnare un po' di tempo ad esplorare la sezione Prodotti di Plone.org e la Plone Collective (un repository SVN di codice per Plone condiviso), per controllare che nessun altro abbia già risolto lo stesso problema.

Avere a disposizione pochi moduli aggiuntivi di altissima qualità è uno degli obiettivi a lungo termine della community di Plone, piuttosto che molti prodotti che risolvono problemi molto simili in maniera leggermente differente. La maggior parte degli sviluppatori Plone sono molto aperti e ben disposti verso nuovi collaboratori, e accoglierebbero molto volentieri un aiuto volto a migliorare un prodotto esistente!

La mailing list degli sviluppatori (Product-Developers Email List)

http://plone.org/support#product-developers

È una lista per gli sviluppatori che scrivono prodotti Plone, utilissima per ottenere consigli e aiuto per i propri progetti, aggiornamenti per nuove versioni di Plone, migrazioni e informazioni generali sullo sviluppo di moduli aggiuntivi.

Caratteristiche generali dei prodotti Plone di alta qualità

Possono essere prodotti molto semplici o estremamente complessi, ciò che rende un prodotto di altissima qualità varia molto in base alle esigenze che risolve. Detto ciò, i moduli aggiuntivi per Plone dovrebbero avere le seguenti caratteristiche:

• Equilibrio tra estendibilità e semplicità

  Un buon prodotto aggiuntivo è disegnato in modo da essere personalizzabile, estendibile, adattabile, quando è necessario. Dovrebbe essere facile definire diversi tipi di contenuto che magari usano logiche o strumenti particolari nel proprio prodotto. Dovrebbe essere facile subclassare qualsiasi tipo di contenuto personalizzato.

  Allo stesso tempo, la semplicità è una virtù. Un prodotto ben progettato risolve i problemi per cui è stato creato, senza aggiungere troppi nuovi meccanismi o rendere ogni singolo elemento el prodotto personalizzabile, ma usando un numero minimo di metodi; in altre parole, dovrebbe fare una cosa e farla bene.

• Utilizzo di tecniche di sviluppo Zope 3 

  Con l'arrivo di Zope 3 e della sua tecnologia particolare, la community di Plone dà ora molta importanza alla "componentizzazione". Prodotti complessi dovrebbero essere divisibili in sottoprodotti, librerie, metodi e classi, diventando componenti Zope 3 (interfacce, visualizzazioni, annotazioni, ecc.) che possono essere riutilizzati da altri prodotti.

  Buoni punti di partenza per imparare come applicare le tecnologie di sviluppo Zope 3 per prodotti add-on possono essere:

  • b-org: un tutorial molto tecnico di Martin Aspeli. Il video della presentazione di b-org della Plone conference 2006 tratta circa lo stesso argomento
  • Il tutorial di Rocky Burt's intitolato "Developing Plone Products Using Zope 3 Technologies" della Plone conference 2006 può anche essere un valido aiuto. Si può leggere la documentazione o guardare il video.

• Utilizzo di buone pratiche di sviluppo con Archetypes

  Archetypes è il framework che Plone usa per costruire gli oggetti principali che lo compongono, e molti prodotti aggiuntivi riguardano la creazione di nuovi tipi di contenuto con Archetypes. Usando questa tecnologia correttamente si renderanno i propri progetti molto più robusti, affidabili e facili da usare.

  Buoni punti di partenza per imparare a conoscere meglio Archetypes sono:

  • The Archetypes Developer Manual
  • La breve guida di Upfront System per sviluppare un tipo di contenuto personalizzato
Tutttavia, potrebbe non essere necessario un tipo di contenuto personalizzato basato su Archetypes. Se si ha solo bisogno di estendere lo schema generale di un contenuto esistente in Plone, si dovrebbe usare archetypes.schemaextender. Ciò permetterà di sfruttare i punti di forza di ATContentTypes (o altri tipi di contenuto basati su Archetypes esistenti) senza essere invasivi e senza subclassare. Per maggiori informazioni su Schema Extender:

• "Customize the fields of the content types" how-to
• "SchemaExtender Extends Your Mind" presentazione
• archetypes.schemaextender su pypi

• Interfaccia utente ben progettata

  Plone è orgoglioso di essere il content management system più usabile e accessibile. Gli sviluppatori di prodotti aggiuntivi dovrebbero fare molto attenzione all'interfaccia utente dei propri prodotti. Per esempio:

  • A partire da Plone 3.0, i prodotti add-on possono trarre vantaggio dal KSS javascript framework. Un uso efficiente di javascript può aiutare a costruire un'interfaccia molto più completa e interattiva. Tuttavia, le interfacce dovrebbero poter essere usate da browser che non usano javascript, senza perdere funzionalità.
  • I prodotti dovrebbero usare appropriate widgets di Archetypes o formlib per editare le interfacce. si può consultare:
    • The Archetypes Widgets Reference
    • Altri campi e widgets dal SVN repository di Archtypes
  • È sempre buona norma introdurre le opzioni di configurazione nel pannello di controllo di Plone, cosicché gli amministratori del sito vi possano facilmente accedere. Meglio evitare di costringere gli utenti ad usare la ZMI o il filesystem per configurare un prodotto.

• Sicurezza

  Grazie a Zope, Plone è un sistema molto sicuro, ed è generalmente piuttosto resistente alla maggior parte dei problemi di sicurezza più comuni che spesso affliggono, per esempio, CMS basati su PHP/MySQL. Ma ogni prodotto è una potenziale fonte di problemi di questo tipo, bisogna quindi dedicare molta attenzione alla sicurezza quando se ne sviluppa uno.

  Utili punti di partenza sulla sicurezza in Plone sono:

  • Talk sulla sicurezza di Andy McKay
  • J Cameron Cooper parla di sicurezza
  • Mikko Ohaatma parla di sicurezza
  • Martin Aspeli parla di permessi e workflow

• Internazionalizzazione (i18n)

  Gli utilizzatori di Plone provengono da tutto il mondo, e il framework di internazionalizzazione di Plone è una delle funzionalità più forti e utili. Ma non può essere molto efficace a meno che gli autori di prodotti add-on non si assicurino che le loro creazioni siano conformi all'i18n (nessun problema per gli sviluppatori che non parlano lingue straniere, non è necessaria nessuna competenza linguistica!).

  Utili punti di partenza:

  • L'how-to "i18n for Developers"

• La guida di Upfront Systems sull'internazionalizzazione in Plone

Dare un nome al proprio prodotto

Scegliere un buon nome per il proprio prodotto può essere di grande aiuto agli utenti per capire di cosa si tratta e a cosa serve. Sfortunatamente la storia di Plone non dà un gran buon esempio da questo punto di vista, e rinominare un prodotto è complicato a causa dell'inconveniente delle migrazioni per successive versioni; quindi meglio scegliere subito un nome significativo. Ecco qualche raccomandazione:

• Scegliere un nome che sia unico, memorabile e non troppo simile a quello di altri prodotti esistenti.
• Un buon nome descrive o suggerisce la funzione del prodotto.
• Per quanto riguarda le eggs per la distribuzione del prodotto, è importante ricordare che il namespace non è il prodotto
• Evitare la parola "Plone" nel nome del prodotto - normalmente è ovvio che si tratta di un prodotto per Plone. Se si sente proprio la necessità di inserire la parola "Plone", è meglio scegliere un nome tipo "XYZ per Plone" ("XYZ for Plone"). Plone® e un marchio registrato della Plone Foundation, e molti pensano che prodotti che contengono questa parola siano sotto la responsabilità di quest'ultima,  ma ciò confonde inutilmente.
• Evitare acronimi gergali come "AT", "CMF", "NG" ecc. e nomi basati sulla tecnologia che sta dietro al proprio prodotto.
• Evitare prefissi che contengano il nome della propria azienda, o di quella per cui è stato sviluppato.
• Non usare solo caratteri minuscoli nel nome che vedranno gli utenti solo perché la convenzione in Zope 3 lo prevede nel codice.

Correndo il rischio di incorrere in qualche polemica, questi sono alcuni buoni nomi per prodotti add-on e altri nomi "meno buoni" (mai si direbbe qualcosa su nessuno degli sviluppatori di prodotti Plone, solo non si considerano ottimali tutti i nomi che sono stati dati ai prodotti...)

Norme generali

Il tutorial di Joel Burton, intitolato Best Practices for Plone Development è un punto di partenza essenziale per chi vuole iniziare a sviluppare moduli per Plone. Spiega le nozioni base per scrivere codice sorgente, per gestirlo, per gestire la configurazione, scrivere la documentazione, eseguire operazioni di debug e di test. Alcune parti incominciano ad avere bisogno di un aggiornamento, ma in generale è uno dei migliori modi in cui iniziare a sviluppare.

Gli standard per scrivere codice

• La maggior parte della logica in un prodotto add-on per Plone è scritta in Python. Seguire le buone norme per la programmazione in Python aiuterà a rendere il proprio prodotto comprensibile e facile da mantenere.
• Con la diffusione di zc.buildout, si incoraggia fortemente la distribuzione dei prodotti sotto forma di eggs. Inoltre, le convenzioni nate con Zope 3 scoraggiano l'uso della directory "magica" Products, anche se è incoraggiata la conversione di prodotti basati su Zope 2 in pacchetti usando il namespace Products.*.
• La community di Plone valuta molto gli standard di usabilità e accessibilità, quindi si dovrebbero usare appropriate sintassi XHTML, TALES e CSS. È quindi buona norma controllare che i propri HTML, CSS e RSS siano in linea con gli standard W3C.

• Evitare di usare DTML nel proprio prodotto add-on per Plone. Nonostante Zope contenga il supporto per il linguaggio di scrittura DTML, DTML è stato soppiantato da TAL per creare template e da Python per la logica sottostante.

Pensa alla compatibilità

Plone supporta entrambe le più recenti versioni di Zope (2). Questo è in genere un buon modello che i prodotto dovrebbero ereditare: supportare le due più recenti versioni (principali) di Plone; ad esempio Plone 2.5 e Plone 3.x. Ciò richiederà magari del lavoro aggiuntivo, ma rende il proprio contributo accessibile a molti più utenti.

Come fare a conoscere bene le API

Una delle cose più efficienti di Plone sono le sue API. Tutto ciò che si può fare attraverso l'interfaccia web, lo si può gestire via codice filesystem, manipolando le API di Plone. Ovviamente ciò fa scaturire una domanda: come scoprire quale metodo API richiamare? I seguenti prodotti possono aiutare:

DocFinderTab

DocFinderTab fornisce un'istantaneo accesso online alla API per ogni oggetto della ZMI. È spesso più utile che cercare nel codice sorgente, dato che si possono vedere tutti i metodi delle classi base, ed è anche più utile che guardare nel debugger. Questo prodotto è facilissimo da installare ed usare. non ci sono scuse per non provarlo subito.

Clouseau

Clouseau è un prompt interattivo Zope/Python basato su AJAX che permette di interagire con Zope e Python direttamente dall'interno di Plone. È molto facile da usare, non ha dipendenze ed è molto maneggevole.

I file Install.py di altri prodotti

Un buon modo di capire come muoversi è guardare come sono stati fatti altri prodotti. Si può ad esempio guardare il file Install.py del proprio prodotto preferito. Per esempio, per imparare come installare nuovi tipi di workflow da disco, si può vedere come è stato fatto in PloneHelpCenter.

Per un'ottima introduzione su come usare le API di Plone, consultare:

• ifPeople's Plone API tutorial

Fasi di test e DocTest

Plone ha una solida cultura per quanto riguarda i test in fase di sviluppo. Infatti, molti sviluppatori della community spesso giudicano la qualità di un prodotto dai test effettuati. Dei buoni test possono garantire il buon funzionamento di un prodotto, e aiutano ad evitare che ci siano problemi anche nella fase stessa di sviluppo.

Lo sviluppatore di Plone/Zope 3 Phillip von Weitershausen (PhiliKON) offre i seguenti consigli per quanto riguarda le fasi di test:

• I testi *.txt in primo piano dovrebbero riguardare test di unità se si sta scrivendo un componente di base in stile Zope 3. Se si parla di unit test vuol dire che si dovrebbero usare DocTestSuite/DocFileSuite da zope.testing.doctest, e nessuna delle contorte suite per fasi di test di tipo ZopeTestCase. Se il proprio test ha bisogno di impostazioni, meglio caricare il limite indispensabile. Evitare di caricare ZCML in uno unit test.
• Scrivere un resoconto in cui si coinvolge il lettore, usando la prima persona plurale (il "noi"). Creare il componente, passare in rassegna le sue API, spiegare i casi limiti e perché è necessario stare attenti ad essi (e testarli accuratamente), anche se ciò richiede del tempo.
• Se si stanno scrivendo test funzionali, interagire con l'applicazione usando il browser per i test (Products.Five.testbrowser.Browser, docs in zope.testbrowser/README.txt). È un ottimo modo di testare interfacce utente interattive in un doctest, il risultato sarà di facile comprensione.

Phillip conclude dicendo:

Solo perchè state scrivendo dei doctests non significa che abbiate scritto anche della documentazione. Testare e documentare è difficile e fare queste due operazioni allo stesso tempo può essere un modo di unire le energie, ma significa anche che bisogna concentrarsi molto. Scrivere dei buoni test, e specialmente scrivere dei buoni doctests, può essere molto più impegnativo che programmare. Siate preparati a impiegare molto tempo in queste operazioni, più che nelle vere e proprie fasi di scritura del codice.

Molte altre informazioni utili sulle fasi di test si trovano nel tutorial di Martin Aspeli intitolato "Testing in Plone."

Merita anche una lettura: Agile Documentation with doctest and epydoc

I seguenti prodotti possono aiutare nel generare documentazione per i propri prodotti add-on:

Alla Plone Conference 2006, Stefan Holek ("lurker") ha presentato un applaudito seminario intitolato "Top Twenty Plone Pitfalls". Si può  leggere l'intera presentazione o guardarla online. 

Alcuni dei trabocchetti da lui suggeriti sono molto utili agli sviluppatori di prodotti Plone, in questa pagina sono stati adattati in una serie di "cattive norme" di programmazione, o cose da evitare.

Non sviluppare la logica dell'applicazione in TALES.

I template sono progettati per presentare, e solo per questo. Tutta la logica della propria applicazione dovrebbe essere scritta in Python (script, tool, ecc.). Se ci si trova a creare complicate strutture nei propri template, è meglio fermarsi un attimo e pensare a come fare in modo di far funzionare tutto grazie a uno script scritto in Python. Con espressioni scritte in TALES sarà difficile eseguire operazioni di manutenzione e di debug, oltre a rendere il prodotto poco comprensibile per gli altri.

Stefan suggerisce scherzando di fare una piccola donazione alla Plone Foundation ogni qual volta si usa codice Python in un Page Template. ;-)

Non imporre un modello relazionale ad un database ad oggetti.

Non ci si deve aspettare che lo ZODB lavori come MySQL.  Non è così. Lo ZODB è un database ad oggetti, non un database relazionale. Quindi è bene progettare la propria applicazione ad oggetti, piuttosto che come righe di dati in una tabella. Viceversa, non c'è nulla di sbagliato nell'utilizzare un RDBMS con Plone, se i propri dati lo richiedono. Il modo più comune per far ciò è usare un connettore di database e metodi ZSQL per leggere/scrivere dati dal proprio RDBMS

Utili fonti su come fare queste operazioni sono:

• http://www.plope.com/Books/2_7Edition/RelationalDatabases.stx
• http://plone.org/documentation/how-to/add-file-system-zsql-method
• http://plone.org/documentation/how-to/mysql-connectivity-in-zope-plone

Non controllare i ruoli, ma i permessi.

• Perché gli oggetti e i metodi sono protetti dai permessi, e non dai ruoli
• Usare portal_membership.checkPermission.

Non usare REQUEST.AUTHENTICATED_USER.

• AUTHENTICATED_USER non è sicuro, da molto lo si sa e si cerca di non usarlo mai
• Usare portal_membership.getAuthenticatedMember

Non usare il ruolo "Autenticato" per configurare la sicurezza del proprio sito.

• Il ruolo "Autenticato" ("Authenticated") è un ruolo che serve al sistema, ma non a gestire la sicurezza.
• Aggiungere i propri ruoli personalizzati.

Non usare ruoli proxy.

• I ruoli di tipo "proxy" ("Proxy roles") sono simili agli script SUID in *nix.
• Fare molta attenzione ai propri script basati su Proxy; si stanno probabilmente creando buchi nella sicurezza del proprio sito.

Non dimenticare di aggiungere dichiarazioni di sicurezza ai propri metodi, di default sono (!) pubblici.

• Perchè Item, che è la classe fondamentale per la maggior parte degli oggetti in Zope2, permette di accedere ad attributi non protetti.
• Essere sempre particolarmente attenti con i tool. I metodi potrebbero richiedere di essere pubblici e di dover eseguire propri controlli di sicurezza.

Non richiamare getObject in risultati da catalog.

• getObject usa internamente restrictedTraverse.
• Aggiungere tutto ciò che serve come metadati in catalog.

Non usare né contentValues né objectValues.

• contentValues/objectValues "risveglia" subobjects, per esempio, caricarli dal disco nella memoria.
• objectIds può essere usato, eventualmente, ma non contentIds.

Non ritornare oggetti dagli scripts, ritornare (liste di) dizionari.

• Gli oggetti non possono essere messi nella RAM-cache.
• La sicurezza degli oggetti verrà controllata.
• Gli script Python sono i primi obiettivi della RAM-cache.

Non elaborare nulla al volo mentre si sta visualizzando.

• Elaborare solo al momento giusto, quando i dati vengono inseriti, e salvare tutto.

Non "toccare" gli oggetti mentre li si sta visualizzando.

• Visualizzare un oggetto non deve causare una modifica dei dati del database.
• È facile causare accidentalmente una modifica; usare il tab Undo per controllare.

Rilasciare il proprio prodotto non deve essere solo rendere disponibile un po' di codice per il download. Prima di rilasciare pubblicamente un prodotto e caricarlo su plone.org, meglio assicurarsi di essere davvero pronti per questo passo! Ecco qualche suggerimento su come procedere per aiutare la community di Plone a trovare il proprio prodotto, ad imparare ed iniziare ad usarlo e a capire come aiutare a migliorarlo.

Mettersi in contatto con altri sviluppatori di prodotti add-on

Questa può essere un ottimo modo per trovare consigli, aiuto, supporto ed entusiasmo! Gli sviluppatori Plone si trovano sulla loro mailing list dedicata: product-developers mailing list. Unisciti anche tu!

Condividi il codice nel Plone Collective

Ogni prodotto Plone dovrebbe avere un repository SVN pubblico, preferibilmente nel Plone Collective, a meno che non ci sia una ragione particolare per metterlo da qualche altra parte. Senza un repository SVN pubblico la Plone community non potrà aiutare a testare il prodotto o contribuire al suo sviluppo. Il Collective è il luogo più "accessibile" per il codice nella community. Assicurarsi sempre di aver "taggato" tutte le versioni nel Collective (ovvero, copiare il codice nella directory "tags"), e non modificare o cancellare mai qualcosa che è stato taggato - alcune persone potrebbero utilizzarlo per accedere a quel codice in zc.buildouts!

Pubblicare la scheda del proprio prodotto su Plone.org

Ogni prodotto add-on per Plone dovrebbe avere una propria voce in plone.org/products con informazioni accurate e aggiornate sulla versione corrente e su quelle passate. Non c'è nessun bisogno, ovviamente, di pubblicare una scheda del prodotto in questa sezione prima che questo venga rilasciato. Dato che la community di Plone tende a standardizzare verso l'uso di zc.buildout, è importantissimo non rimuovere o rinominare nessuna versione che si è creata su plone.org!

Il Plone Software Center (che gestisce plone.org/products) offre anche alcune funzioni utilissime per aiutare a mantenere e migliorare il proprio codice. È quindi importante sfruttare le seguenti risorse:

• Issue tracker: ogni prodotto dovrebbe avere un proprio issue tracker, ovvero un luogo in cui poter segnalare eventuali bug e problemi; dovrebbe trovarsi preferibilmente su Plone.org/products almeno che non ci sia una particolare ragione per metterlo da qualche altra parte. Ciò aiuta gli utenti del proprio prodotto a segnalare i problemi e a scoprire quando sono stati risolti.
• Roadmap: i prodotti in uso dovrebbero avere una roadmap per i miglioramenti futuri e per proposte.

Suggerimento: la maggior parte degli utenti apprezza molto il poter vedere un prodotto in azione prima di decidere effettivamente di usarlo. Se è appropriato e possibile, è sempre bene includere nella descrizione del prodotto un paio di URL che mostrano il prodotto in azione.

Consultare http://plone.org/documentation/tutorial/plone-software-center per altri suggerimenti su come sfruttare al meglio il Plone Software Center.

Se il proprio codice è distribuito come egg, assicurarsi di rilasciare ogni versione nel Python Package Index (alias PyPI; conosciuto anche come Cheese Shop) per mettere a disposizione il proprio codice per il zc.buildout con solo qualche riga di configurazione.

• Scopri come avere accesso al Collective.

Documentazione

I prodotti che si occupano di funzionalità dedicate agli utenti finali di Plone dovrebbero fornire anche documentazione per utenti finali, possibilmente su plone.org, in modo che sia accessibile anche da chi non può entrare nel filesystem.

• Ogni prodotto dovrebbe avere un documento INSTALL o README che descriva chiaramente come installare e disinstallare il prodotto ed elenchi tutte le dipendenze.
• Per alcuni prodotti dovrebbe essere anche fornita documentazione per integratori su come customizzarli o estenderli.
• Il prodotto dovrebbe includere una licenza open source (preferibilmente GPL), credits ed appropriati numeri di versione.
• Dovrebbe essere mantenuto un file HISTORY.txt che elenchi i cambiamenti importanti apportati ad ogni versione, ovvero una chiara lista dei bug risolti, nuove funzioni, migliorie.

Coinvolgere la Community

L'aspetto più importante di Plone è la sua forte, varia e disponibile comunità di utenti e sviluppatori. I prodotti per Plone di maggior successo sono progetti che hanno coinvolto l'intera community; ciò aiuterà ogni sviluppatore a migliorare sempre più. È questo lo spirito di ogni community open source, entità che sono in genere sostenute da capitale umano e reputazione. È quindi anche importante farsi conoscere e guadagnare la fiducia degli altri membri, in modo che dall'altra parte la community sia sempre disposta ad aiutare e collaborare ai propri progetti.

• È sempre bene annunciare la realizzazione di nuovi prodotti sulla mailling list degli sviluppatori e degli utenti Plone.
• Il luogo migliore in cui chiedere aiuto per lo sviluppo di un prodotto è la lista degli sviluppatori Plone.

Consulta http://plone.org/support/lists

Continuare a coordinare il progetto

Una volta che un prodotto è stato rilasciato, è bene che il suo sviluppatore rimanga sempre il coordinatore del progetto, in modo da organizzarne i futuri sviluppi, continuare il suo miglioramento e dare continuo supporto agli utenti. Ciò significa:

• Indicare il proprio indirizzo email nella pagina del Plone Software Center relativa al proprio prodotto
• Rispondere sempre ai report dei bug e consultare continuativamente il bug tracker
• Trovare un nuovo coordinatore del progetto se si decide di abbandonarlo

Questo documento è stato realizzato da:

• Alice Narduzzo

Fonti e contributi:

Questo how-to è una libera traduzione del testo originale Add-on Products Developer Manual.