9.3. Crea un modulo Drupal personalizzato. Visualizza la pagina tramite codice.
Iniziamo a creare il nostro modulo con un po' di ordine. Continuiamo a separare i moduli personalizzati (custom) da quelli contribuiti (contributed). In Drupal i moduli si trovano nella cartella /modules. Ora non è più necessario metterli in profondità dentro /sites/all/modules, anche se il file readme dice che dovrebbe funzionare, è comunque consigliato usare la cartella /modules. All’interno della cartella /modules, creeremo due sottocartelle: custom e contrib. Nella cartella contrib verranno archiviati i moduli aggiuntivi scaricati da drupal.org, mentre i nostri moduli personalizzati verranno conservati nella cartella custom.
Sottotitoli in inglese:
Gli esempi di codice possono essere visualizzati su GitHub:
https://github.com/levmyshkin/drupalbook8
Un dettaglio apparentemente insignificante come dividere i moduli nelle cartelle contrib e custom può sembrare superfluo, ma credimi, quando sul tuo sito avrai 200 moduli esterni e 30 moduli personalizzati, capirai quanto è difficile trovare tutto il codice personalizzato. Inoltre, se modifichi del codice in un modulo contrib (cosa che andrebbe fatta solo se strettamente necessario), sarebbe anche opportuno spostarlo nella cartella custom per evitare di sovrascrivere le modifiche durante un aggiornamento (o che un altro sviluppatore le sovrascriva, o addirittura tu stesso, senza rendertene conto).
Ora creiamo il nostro modulo personalizzato. Crea la cartella /modules/custom/drupalbook. In questa cartella dovremo creare il file drupalbook.info.yml:
name: DrupalBook
description: Modulo personalizzato per imparare Drupal 8
type: module
core: 8.x
core_version_requirement: ^8 || ^9
package: DrupalBook
Il file *.info.yml è responsabile della descrizione del modulo. Le informazioni che contiene verranno visualizzate nella pagina “Extend”. Il nome del file stesso è composto dal nome del modulo + .info.yml.
I file YML in Drupal sono il formato standard per configurazioni e impostazioni. I campi e i valori nei file YML sono separati da due punti, e ogni nuova linea deve avere un rientro di due spazi. La formattazione è molto importante: se c’è un errore, come uno spazio in più o un due punti mancante, Drupal potrebbe generare un errore o non riuscire a leggere correttamente il file YML.
Vai alla pagina “Extend” e abilita il tuo modulo:
Ora che il modulo è incluso, possiamo aggiungere funzionalità e farlo funzionare sul nostro sito. Per cominciare, visualizzeremo del testo semplice su una pagina. Per farlo, dobbiamo creare un altro file YML chiamato drupalbook.routing.yml:
drupalbook.first_page:
path: '/first-page'
defaults:
_controller: '\Drupal\drupalbook\Controller\FirstPageController::content'
_title: 'Hello World!'
requirements:
_permission: 'access content'
Vediamo più da vicino cosa contiene questo file YML.
drupalbook.first_page: – è il nome della nostra rotta, il percorso che Drupal userà per raccogliere tutte le rotte. Questo nome deve essere univoco; è consigliato usare il formato module_name.route_name, poiché è possibile avere più rotte in un singolo modulo: ad esempio drupalbook.first_page, drupalbook.second_page, ecc.
path: '/first-page' – il percorso della rotta. Presta attenzione al rientro di due spazi: è obbligatorio. Se usi un editor che inserisce tabulazioni invece di spazi, ti conviene modificare questa impostazione per usare due spazi al posto del tab.
defaults: – definisce le impostazioni predefinite della rotta e come deve essere creata. Esistono vari modi per creare una rotta; uno di questi è tramite una classe Controller, ma è possibile anche usare altre classi per creare rotte dinamicamente. Più avanti analizzeremo altre possibilità, ma per ora ci concentreremo su un semplice esempio con un Controller. Il sistema di routing di Drupal deriva da Symfony e utilizza le sue librerie. Symfony è un framework MVC, molto pulito, utilizzato anche in altri progetti come Laravel. MVC significa Model, View, Controller (in questo caso, View non è il modulo Views, ma un semplice template di visualizzazione, Model rappresenta le entità che interagiscono con il database, come l’Entity API di Drupal). Il Controller nell’architettura MVC serve proprio per il routing, che è ciò che stiamo facendo in questa lezione.
_controller: '\Drupal\drupalbook\Controller\FirstPageController::content' – in questo parametro indichiamo quale classe PHP visualizzerà la nostra pagina. Dopo il nome della classe (::) specifichiamo quale metodo della classe verrà usato per generare il contenuto. Il numero di backslash serve per indicare a Drupal in quale cartella si trova la classe PHP.
_title: 'Hello World!' – il titolo della nostra pagina.
_permission: 'access content' – i permessi necessari per visualizzare la pagina; l’utente deve avere un ruolo con questi diritti.
Dopo aver aggiunto il file YML per il routing, dobbiamo aggiungere la classe PHP che visualizzerà la nostra pagina. Prima, però, dobbiamo capire come funziona il caricamento automatico delle classi dai nostri moduli. In Drupal esistono moltissime classi, ma non tutte sono necessarie per ogni pagina, quindi vengono caricate solo quelle richieste. Drupal utilizza l’autoloading PSR-4 di PHP:
https://www.php-fig.org/psr/psr-4/
Osserviamo la riga nel file di rotta dove abbiamo indicato la classe PHP:
\Drupal\drupalbook\Controller\FirstPageController
\Drupal – indica che la classe è caricata tramite la libreria di Drupal. Drupal è ora anche una libreria a sé stante, abbastanza grande, che può essere inclusa tramite packagist:
https://packagist.org/packages/drupal/drupal
Successivamente indichiamo quale modulo vogliamo utilizzare:
\drupalbook
Dopodiché specifichiamo il nome della cartella o la struttura delle sottocartelle dentro la cartella src del modulo. Se abbiamo indicato la cartella Controller, essa si troverà qui:
/modules/custom/drupalbook/src/Controller
Presta attenzione alle maiuscole e minuscole: PHP fa distinzione tra “controller” e “Controller”.
Infine, specifichiamo il nome del file, che deve terminare con .php:
/modules/custom/drupalbook/src/Controller/FirstPageController.php
Creiamo questo file:
/**
* @return
* Contiene \Drupal\drupalbook\Controller\FirstPageController.
*/
namespace Drupal\drupalbook\Controller;
/**
* Fornisce le risposte alle rotte per il modulo DrupalBook.
*/
class FirstPageController {
/**
* Restituisce una semplice pagina.
*
* @return array
* Un semplice array renderizzabile.
*/
public function content() {
$element = array(
'#markup' => 'Hello World!',
);
return $element;
}
}
Questa dovrebbe essere la struttura dei file:
Ora dobbiamo svuotare la cache affinché la nuova rotta venga riconosciuta. La pagina sarà disponibile su http://drupalbook/first-page:
Ora esaminiamo la classe PHP che visualizza questa pagina.
/**
* @return
* Contiene \Drupal\drupalbook\Controller\FirstPageController.
*/
Qui indichiamo il percorso, lo stesso che si trova nel file di routing YML, specificando a Drupal da dove deve caricare la classe.
namespace Drupal\drupalbook\Controller;
namespace indica il percorso verso il file della tua classe. Fai attenzione quando copi codice da altri siti: quando copi un namespace, devi cambiare il nome del modulo con il tuo. Nel mio caso è drupalbook, ma nel tuo potrebbe essere diverso.
class FirstPageController {
/**
* Restituisce una semplice pagina.
*
* @return array
* Un semplice array renderizzabile.
*/
public function content() {
$element = array(
'#markup' => 'Hello World!',
);
return $element;
}
}
Questa è la nostra classe che visualizza la pagina. Ha un metodo content() che abbiamo specificato nel file drupalbook.routing.yml. In questo metodo restituiamo un array con l’elemento #markup, nel quale inseriamo l’HTML da mostrare in output. Restituiamo un array, non una stringa, perché tramite una rotta è possibile visualizzare non solo HTML, ma anche endpoint JSON per API, file XML o CSV.
Il codice del modulo può essere visualizzato su GitHub:
https://github.com/levmyshkin/drupalbook8
Questo è tutto! Nella prossima lezione continueremo ad ampliare le funzionalità del nostro modulo.