Allora, io ci provo...
Quella che segue è solo una bozza, riguardante soltanto la creazione di un nuovo modulo di blocco nella piattaforma CMS. Le convenzioni che indico sono solo una proposta, da integrare e correggere.
Spero sia utile.
*************************************************
LINEE GUIDA PER LO SVILUPPO DI MODULI IN DOCEBO
(bozza non ufficiale)
*************************************************
CMS - MODULO PER BLOCCHI
========================
Una pagina del CMS è composta da uno o più blocchi, posizionati secondo una
certa disposizione.
Per realizzare un nuovo tipo di blocco è necessario definire una parte che
riguarda la configurazione del blocco ed una che riguarda la sua
visualizzazione.
CONFIGURAZIONE DEL BLOCCO
-------------------------
* Convenzioni sui nomi dei blocchi:
I nuovi moduli per la gestione dei blocchi devono avere un nome nel formato
"ext_xxx", dove il prefisso "ext_" sta ad indicare una estensione esterna al
codice di Docebo e "xxx" indica il nome desiderato per il blocco.
* Inserimento del nuovo tipo di blocco:
Per rendere visibile il nuovo blocco nell'apposita pagina di scelta è
necessario inserire i valori opportuni nella tabella "cms_blocktype":
INSERT INTO cms_blocktype ( name, folder, label )
VALUES ( 'ext_xxx', '', '_BLK_EXT_XXX');
Il campo "name" indica il nome del nuovo blocco, che sarà del tipo "ext_xxx".
Il campo "folder" indica la directory dove trovare il codice del blocco:
se si lascia in bianco viene utilizzato il nome del blocco stesso. Questa
opzione è utilizzata per blocchi che si differenziano poco tra di loro, per
cui è opportuno ragruppare il codice (es. il blocco "Notizie" ed il blocco
"Notizie (specifico)" ).
Il campo "label" indica la chiave del linguaggio che contiene il nome del
blocco da visualizzare: deve essere nel formato "_BLK_EXT_XXX".
* Codice per la configurazione del blocco:
Una volta inserito un blocco all'interno di una pagina è possibile
configurarne i parametri di visualizzazione.
Il codice che si occupa della gestione dei parametri di configurazione si
trova nella directory:
doceboCms/admin/modules/block_ext_xxx/
All'interno di questa directory deve trovarsi il file "util.ext_xxx.php".
Questo file deve a sua volta contenere la definizione delle funzioni:
function ext_xxxBlockEdit(& $out, & $lang, & $form, $block_id, $sub_id)
Questa funzione visualizza il form che contiene tutte le opzioni
configurabili per il blocco.
function ext_xxxBlockAdd($block_id, $sub_id)
Questa funzione permette di definire i valori di default per i parametri
del blocco.
function ext_xxxBlockSave($block_id, $sub_id)
Questa funzione permette di memorizzare i valori specificati per i
parametri del blocco.
function ext_xxxBlockDel($block_id, $sub_id)
Questa funzione è opzionale (può non essere presente) e viene
richiamata al momento della rimozione del blocco: è pensata per
gestire delle operazioni di cancellazione non standard, come può
essere il caso della eliminazione di valori da tabelle non
appartenenti a Docebo.
Utilizzando un modulo esistente come esempio non è difficile scrivere il
codice desiderato per il nuovo blocco.
In caso sia necessario definire funzioni di utilità, bisogna nominarle
secondo questo standard: "ext_xxxYyy", dove Yyy è il nome che caratterizza
la funzione.
Se le funzioni di utilità possono essere utilizzate in più parti
dell'applicazione (come ad esempio al momento della visualizzazione del
blocco), è opportuno inserirle in un apposito file presente nella stessa
directory e chiamato "functions.php", che sarà richiamato con l'istruzione
"require_once" del PHP.
* Definizione delle chiavi del linguaggio:
Per rendere visibile il nuovo blocco nell'apposita pagina di scelta è
necessario definire 2 chiavi di linguaggio, entrambe appartenenti alla
piattaforma "CMS" ed al modulo di gestione "admin_manpage":
_BLK_EXT_XXX che contiene il nome del blocco;
_BLK_EXT_XXX_DESC che contiene una breve descrizione delle funzionalità
del blocco.
Tutti gli altri messaggi necessari per la gestione dei parametri del
blocco devono essere definiti come chiavi di linguaggio, appartenenti alla
piattaforma "CMS" ed al modulo di gestione "admin_manpage", usando la
convenzione "_EXT_XXX_YYY", dove YYY è il nome desiderato per la chiave del
linguaggio.
Nel caso di messaggi già presenti come chiavi di linguaggio, onde evitare
ogni possibile conflitto con gli aggiornamenti di Docebo, è senz'altro
preferibile creare nuove chiavi.
VISUALIZZAZIONE DEL BLOCCO
--------------------------
* Codice per la visualizzazione iniziale del blocco:
Il codice che si occupa della visualizzazione del blocco si trova nella
directory:
doceboCms/modules/ext_xxx/
All'interno di questa directory deve trovarsi il file "block.ext_xxx.php".
Questo file deve a sua volta contenere la definizione della funzione:
function ext_xxx_showMain($idBlock, $title, $block_op)
Questa funzione visualizza il blocco all'interno della pagina del CMS.
Utilizzando un modulo esistente come esempio non è difficile scrivere il
codice desiderato per il nuovo blocco.
In caso sia necessario definire funzioni di utilità, bisogna nominarle
secondo questo standard: "ext_xxx_Yyy", dove Yyy è il nome che caratterizza
la funzione.
Se le funzioni di utilità possono essere utilizzate in più parti
dell'applicazione è opportuno inserirle in un apposito file presente nella
stessa directory e chiamato "functions.php". Se invece di funzioni si vuole
definire una classe, è opportuno assegnare al file un nome del tipo
"class.ext_xxx_yyy.php" e chiamare la classe "ext_xxx_yyy", dove "yyy" è il
nome che la caratterizza.
* Codice per la visualizzazione delle sottopagine del blocco:
Alcuni blocchi si limitano a mostrare un solo contenuto, come ad esempio il
blocco "Menu", altri invece permetto di mostrare anche delle sottopagine.
Per gestire le sottopagine è necessario inserire nella directory indicata
in precedenza anche il file "index.php".
Questo file contiene del codice che permette di selezionare la sottopagina
da mostrare, mandando in esecuzione la funzione corrispondente.
Si può prendere come esempio il blocco "news" per scrivere il codice
necessario per il proprio blocco.
In caso sia necessario definire funzioni di utilità, bisogna nominarle
sempre secondo lo standard: "ext_xxx_Yyy", dove Yyy è il nome che
caratterizza la funzione.
E' opportuno creare delle funzioni di utilità che possono essere richiamate
sia dalla pagina principale (file "block.ext_xxx.php") che dalle sottopagine
(file "index.php") e raggrupparle nel file "functions.php".
* Definizione delle chiavi del linguaggio:
Ogni testo costante che si vuole visualizzare sulle pagine deve essere
sempre deinito come chiave di linguaggio: in questo modo si rende
semplice la traduzione in altre lingue.
Le nuove chiavi di linguaggio vanno definite all'interno della
piattaforma "CMS" e del modulo che si sta creando.
Nel caso di messaggi già presenti come chiavi di linguaggio, onde evitare
ogni possibile conflitto con gli aggiornamenti di Docebo, è senz'altro
preferibile creare nuove chiavi.
