LE ESTENSIONI PER TYPO3: REALIZZAZIONE DI UN PLUGIN D’ESEMPIO

Lo sviluppo di una nuova estensione per TYPO3 può avvenire “manualmente”, ovvero creando tutti i file necessari con le dovute strutture dati, oppure può essere agevolato mediante l’utilizzo di un wizard che consente di definire le proprietà che dovrà avere la nostra estensione (tabelle e campi nel db, plugin di FE, moduli di BE e molto altro) e che si occupa di creare i relativi file e le relative strutture dati. Tale wizard è disponibile, guarda caso, come estensione di TYPO3 e può essere facilmente installato. Il nome del wizard è Kickstarter.

Per iniziare la realizzazione della nostra estensione dobbiamo quindi installare il Kickstarter mediante l’Extension Manager. Dopo l’installazione comparirà una nuova voce di menu tra quelle disponibili nell’Extension Manager, tale voce consentirà di iniziare lo sviluppo di una nuova estensione (si veda la Figura 1).

Selezionando quindi la nuova voce “Make new extension” viene avviato il wizard (Figura 2). La prima operazione da fare è quella di determinare una extension key, ovvero una stringa formata dai caratteri a-z, 0-9, _. Si possono distinguere due casi: le estensioni specifiche per un progetto e le estensioni di utilità comune e che quindi saranno rilasciate. Nel primo caso la chiave dell’estensione, per convenzione, inizierà col prefisso user_. Nel caso di estensioni che verranno inserite nel repository pubblico la chiave dovrà essere registrata attraverso il sito [6], al fine di essere certi della sua univocità e non potrà iniziare col prefisso visto sopra. Nel nostro caso possiamo definire la chiave user_guestbook.

A questo punto possiamo passare a definire le informazioni generali della nostra estensione quali il titolo, una breve descrizione, la categoria (nel nostro caso Front-end Plugin), stato (possiamo settare lo stato di “Test”), dipendenze da altre estensioni, autore e mail dell’autore.

Subito dopo è conveniente passare all’ultima delle opzioni disponibili: quella riguardante la localizzazione dell’estensione. Dobbiamo infatti attivare anche la lingua italiana oltre a quella inglese di default. Per far questo è sufficiente cliccare sul pulsante “+” che compare a fianco della voce “Setup languages” e, nella form che compare, spuntare la lingua italiana.

Passiamo ora a definire la tabella necessaria per contenere i messaggi lasciati dai visitatori. Sempre con il pulsante “+” aggiungiamo una nuova tabella nel database e completiamo il nome che dovrà avere (come potete vedere in Figura 3 il nome della tabella avrà come prefisso user_guestbook_, ovvero la chiave dell’estensione). Di seguito diamo anche un titolo alla tabella, sia in lingua inglese che in lingua italiana. Tale titolo costituirà il nome della tipologia di record contenuti in questa tabella.

A questo punto possiamo passare a definire di quali campi sarà composta questa tabella. Scorrendo la form possiamo selezionare alcuni campi già disponibili, come il campo deleted e il campo hidden. Il primo serve ad evitare che un record cancellato venga completamente rimosso dalla tabella (verrà invece settato un flag che permetterà a TYPO3 di ignorare il record e a noi di recuperarlo nel caso di una cancellazione errata). Il secondo invece permetterà di nascondere un record dalla sua presentazione a FE. Gli altri campi proposti sono i campi necessari per settare un inizio e una fine di validità del record e un campo per settare una restrizione dell’accesso ai soli utenti loggati. Nessuno di questi tre campi è richiesto nel nostro caso.

Continuando a scendere troviamo numerose opzioni che per la nostra estensione non sono richieste ma che, se vi interessano per altri progetti, trovate commentate nelle letture proposte in bibliografia. Per il nostro scopo sarà sufficiente settare l’opzione “Descending” per l’ordinamento (in questo modo i messaggi saranno automaticamente ordinati dal più recente al meno recente) e l’opzione “Allowed on pages” per permettere la creazione dei messaggi in normali pagine nel BE.

Non ci resta che definire i campi specifici per la nostra estensione. Il primo di questi sarà un campo dove l’utente dovrà inserire il proprio nome. In Figura 4 vediamo come dovrà essere impostato questo campo. Il secondo sarà un campo in cui l’utente potrà inserire il messaggio (Figura 5). Questi due campi si differenziano principalmente per il tipo di input che possono accettare. Nel primo caso l’input sarà costituito da una stringa semplice, di lunghezza massima di 50 caratteri, e sarà obbligatorio. Nel secondo caso sarà un testo e l’utente (di BE) avrà a disposizione un editor WYSIWYG per scriverlo. I tipi di input possibili sono molteplici:

• Stringa semplice;

• Stringa evoluta per la creazione di campi password, numerici, di data, di colori, di link e altro;

• Textarea con o senza editor WYSIWYG;

• Checkbox;

• Link;

• Date;

• Selectorbox;

• Radio buttons;

• Database relations, con la possibilità di specificare la tabella con cui è possibile effettuare la relazione;

• Files, con relativo modulo di upload;

• Non editabili, campi solo visualizzati;

• Passthrough, campi nascosti.

Il wizard non si occuperà solamente di creare i campi nel database ma, come vedremo, creerà anche la necessaria struttura dati per permettere a TYPO3 di generare la form per l’inserimento di tali dati dal BE.

Nei due campi precedenti, però, vorrei farvi notare un’ulteriore differenza: il campo del messaggio è impostato come “Exclude field” mentre il primo non lo è. Un campo “escludibile” è un campo che è possibile nascondere ad un utente di BE non admin. In questo caso è possibile nascondere il campo del messaggio mentre non è possibile nascondere il campo dell’autore in quanto obbligatorio e, quindi, se un utente non potesse accedervi, non sarebbe in grado di creare dei record di questo tipo.

Per la nostra estensione non rimane che impostare correttamente il Front-end Plugin. È quindi necessario creare un nuovo Front-end Plugin, dare un titolo e selezionare entrambe le opzioni. La prima serve per dire a TYPO3 che i contenuti generati da questo plugin non dovranno essere messi in cache, il secondo serve per importare automaticamente il codice TypoScript di configurazione dell’estensione, qualora presente. Al momento non definiremo alcun codice Typoscript ma, quando creeremo la logica dell’estensione, introdurremo anche questo livello di personalizzazione. A seguire selezioniamo la prima voce e impostiamo i valori come in Figura 6.

A questo punto siamo pronti per salvare la nostra estensione. Sulla sinistra si può trovare il pulsante “View result”. Una volta premuto, il wizard ci mostra tutti i file che andrà a creare e il loro contenuto. Qui è possibile anche evitare di scrivere dei file. Questa possibilità è molto importante nel caso si stia modificando un’estensione precedentemente creata mediante questo wizard. Se infatti abbiamo apportato delle modifiche manuali ai file, tipico il caso del file contenente la logica per la visualizzazione dell’estensione da FE, e lasciando selezionato questo file il wizard lo sovrascriverà causando la perdita di tutte le nostre modifiche. Passiamo quindi alla generazione dei file semplicemente cliccando sul pulsante “write”.

Una volta salvata l’estensione sarà già possibile installarla, come una qualsiasi altra estensione. Durante l’installazione verrà automaticamente creata la tabella nel database e una cartella sul server per il salvataggio di eventuali immagini caricate attraverso l’editor di testo. Dopo l’installazione sarà già possibile includere il plugin in una pagina come un qualsiasi altro contenuto di pagina. L’output generato da FE, ovviamente, sarà solamente un output d’esempio. Nel prossimo articolo andremo a scrivere il codice necessario alla visualizzazione della lista dei messaggi e della form per il loro inserimento.

Nel frattempo, però, gli utenti di BE possono già inserire dei messaggi attraverso il modulo generato automaticamente da TYPO3. Per creare messaggi per il guestbook è sufficiente andare nella pagina contenente il nostro plugin, cliccare su “Create new record” e selezionare un nuovo “Visitor’s Message”, se lavoriamo in lingua inglese, o un nuovo “Messaggi dei Visitatori”, se lavoriamo in lingua italiana. Come possiamo vedere in Figura 7, la form generata contiene esattamente i campi da noi specificati in precedenza.

Se ora passiamo a vedere la tabella generata, direttamente nel database, mediante phpmyadmin o uno strumento simile, però, ci accorgiamo che ci sono numerosi altri campi oltre a quelli da noi specificati. Tali campi sono l’uid, un identificatore univoco del record, il pid, ovvero l’uid della pagina che contiene questo record, il tstamp, un timestamp riportante la data di ultima modifica del record, il crdate, il timestamp di creazione del record, e il cruser_id, ovvero l’uid dell’utente di BE che ha creato questo record. Tali campi vengono generati automaticamente e sono necessari al corretto funzionamento di TYPO3 e di questa estensione.

In ultimo vediamo quali file sono stati generati dal Kickstarter. Elencando i file presenti nella radice della nostra estensione, il primo che incontriamo è il file ext_emconf.php. Questo file contiene le informazioni generali dell’estensione, dal titolo all’autore, inoltre contiene delle informazioni relative alla versione dell’estensione (gestite automaticamente al momento dell’upload nel repository pubblico) e dei file contenuti nell’estensione (ad ogni file è associato un codice md5 per poter risalire ai quelli modificati). Il file ext_localconf.php contiene la configurazione necessaria per integrare l’estensione nel framework mentre il file ext_tables.php contiene le configurazioni necessarie ad integrare le tabelle nel database, i plugin di FE e i moduli di BE. Il file ext_tables.sql contiene invece il codice SQL per la generazione delle tabelle nel database. Il file ext_typoscript_editorcfg.txt contiene del codice TypoScript che viene integrato. I file locallang.xml e locallang_db.xml contengono i testi in diverse lingue per la localizzazione del plugin e di tutti i campi del database. Infine il file tca.php contiene la struttura dati che permette a TYPO3 di generare correttamente la form per l’inserimento dei messaggi da BE. Di seguito è presente un estratto di tale file dove è possibile notare come viene descritto il campo per l’inserimento del nome dell’autore:

"nome" => Array (

"exclude" => 0,

"label" => “LLL:EXT:user_guestbook/locallang_db.xml:user_guestbook_messaggi.nome",

"config" => Array (

"type" => "input",

"size" => "30",

"max" => "50",

"eval" => "required",

)

),

Per ogni campo della form sarà presente una descrizione simile. Questa struttura dati è facilmente modificabile per aggiungere nuovi campi (in questi casi bisogna ricordarsi però di aggiornare anche il file ext_tables.sql) o di modificare il comportamento di un campo (in questo esempio si potrebbe togliere l’obbligatorietà del campo rimuovendo la riga “eval”=>”required”).

Nella cartella doc/ si trovano due file che sono inutili per l’estensione ma necessari al kickstarter per poter ricreare il wizard con i giusti parametri nel caso si cerchi di modificare l’estensione attraverso di esso. A questo punto dovrebbe essere chiaro come le modifiche apportate manualmente ad uno qualsiasi dei file dell’estensione non vengano presentate aggiornate dal kickstarter. Questi due file possono essere liberamente cancellati prima della pubblicazione dell’estensione (il mio consiglio comunque è di cancellarli non appena viene apportata una modifica ad uno dei file visti sopra per evitare di utilizzare il wizard per eventuali nuove modifiche rischiando di perdere quelle fatte manualmente). In questa cartella dovrà essere inserito il manuale dell’estensione.

Infine, nella cartella pi1/ troviamo i file necessari al funzionamento del Front-end Plugin (se avessimo attivato più plugin avremmo avuto anche le cartelle pi2/, pi3/ e così via). Il file principale è il file class.user_guestbook_pi1.php che viene richiamato da TYPO3 nel caso debba presentare a FE il nostro plugin e che pertanto deve generare l’output voluto. Se provate ad editarlo noterete come genera l’output d’esempio. Il file class.user_guestbook_pi1_wizicon.php contiene delle istruzioni necessarie a TYPO3 per presentare il nostro plugin nella lista di quelli disponibili durante la creazione di un nuovo elemento di contenuto (Figura 8). Il file locallang.xml è il file che dovrà contenere tutti i testi visualizzati a FE dall’estensione nelle varie lingue attivate.