Creazione di moduli personalizzati per Drupal: Una guida completa

Drupal è un sistema di gestione dei contenuti (CMS) estremamente flessibile e scalabile, grazie alla sua architettura modulare. Ciò significa che gli sviluppatori possono creare moduli personalizzati per soddisfare le esigenze specifiche delle loro applicazioni. In questo articolo, ti guideremo attraverso il processo di creazione di moduli personalizzati per Drupal, fornendoti informazioni dettagliate e best practice per aiutarti a creare moduli efficienti e funzionali.

Prima di iniziare, è importante capire cosa sono i moduli di Drupal. I moduli sono piccole applicazioni che si integrano con il core di Drupal, consentendoti di estendere la funzionalità del sistema e di creare contenuti più complessi. I moduli possono essere utilizzati per aggiungere nuove funzionalità, come ad esempio la gestione dei membri o la creazione di forme di pagamento, oppure per integrare Drupal con altre applicazioni o servizi.

Per creare un modulo personalizzato per Drupal, è altamente consigliato installare il toolkit di sviluppo di Drupal, noto come "Drush". Drush è uno strumento di lin guaggio che ti consente di eseguire comandi e di creare script per gestire il tuo sito Drupal. Puoi scaricare Drush dal sito ufficiale di Drupal.

Creazione di un nuovo modulo

Una volta installato Drush, il passo successivo è procedere con la creazione di un nuovo modulo personalizzato, che chiameremo ad esempio "my_module" (puoi ovviamente scegliere qualsiasi nome significativo per il tuo progetto). Per farlo, naviga all’interno della directory principale del tuo sito Drupal e crea una nuova cartella all’interno del percorso /modules/custom/. Questa posizione è importante perché Drupal riconosce automaticamente come “custom” tutti i moduli presenti in questa directory, distinguendoli da quelli core o contribuiti. La cartella deve avere lo stesso nome del modulo per evitare conflitti di caricamento e facilitare la manutenzione del codice, ad esempio /modules/custom/my_module. Al suo interno andrai a inserire tutti i file che compongono il modulo: dal file di informazioni al codice PHP con le logiche del modulo, fino ai file di routing e ai controller, se necessari.

Il primo file da creare è my_module.info.yml, un file chiave senza il quale Drupal non riconoscerà il tuo modulo. Questo file contiene i metadati fondamentali che descrivono il modulo al sistema, come nome, descrizione, tipo, pacchetto, versione, e soprattutto le dipendenze da altri moduli. In questa fase è consigliabile includere anche la compatibilità con la versione di Drupal in uso, per evitare problemi durante aggiornamenti futuri. Un esempio completo di come potrebbe apparire il file è il seguente:

name: My Module
type: module
description: Aggiunge funzionalità personalizzate al sito Drupal.
package: Custom
core_version_requirement: ^10 || ^11
version: 1.0.0
dependencies:
  - drupal:node
  - drupal:user

In questo modo Drupal saprà come identificare e gestire il modulo nel pannello di amministrazione, consentendoti di attivarlo e disattivarlo facilmente. Dopo aver creato il file .info.yml, puoi verificare se il modulo è stato correttamente rilevato eseguendo il comando drush cr per svuotare la cache e aggiornare l’elenco dei moduli disponibili. Nel file abbiamo specificato le seguenti informazioni:

• name: Il nome leggibile del modulo.
• type: Specifica che si tratta di un modulo.
• description: Una breve descrizione del modulo e della sua funzione.
• core_version_requirement: Indica la versione di Drupal con cui il modulo è compatibile.
• package: Organizza il modulo sotto un gruppo nel menu di amministrazione dei moduli.
• version: La versione del modulo.
• dependencies: Elenca i moduli di cui il tuo modulo dipende, ad esempio, drupal:node.

Definizione degli assets statici

Le librerie in Drupal possono includere file CSS e JavaScript necessari per il modulo. Questi vengono definiti in un file .libraries.yml e poi richiamati in due modi

• nel codice del modulo
• aggiungendo una voce nel file precedente

Io preferisco il secondo metodo

name: 'My Module'
type: module
description: 'A custom module for specific functionality.'
core_version_requirement: ^8 || ^9
package: Custom
version: 1.0
dependencies:
  - drupal:node
libraries:
  - my_module/nome1

In questo esempio, abbiamo aggiunto la sezione libraries che include una libreria.

Adesso creiamo il file my_module.libraries.yml. Qui specifichiamo i file CSS e JavaScript da includere, oltre alle dipendenze necessarie.

nome1:
  version: 1.x
  header: false
  css:
    theme:
      css/animate.min.css: {}
  js:
    js/wow.js: {}
    js/about_me.js: {}

Nel contesto delle librerie di Drupal, i livelli indicano dove verranno caricati gli asset specificati, come file CSS e JavaScript.

Theme: Indica che gli asset verranno caricati nel tema del sito. Questo significa che i file CSS e JavaScript definiti sotto questo livello saranno disponibili per il tema attivo del sito, e saranno quindi visibili su tutte le pagine che utilizzano quel tema.

Definire gli asset al livello "theme" è utile quando si desidera che questi asset siano disponibili su tutte le pagine del sito, indipendentemente dal modulo o dalla funzionalità che li utilizza. Ad esempio, se hai degli effetti di animazione che vuoi applicare globalmente al tuo sito, definire quegli asset a livello "theme" assicurerà che siano disponibili ovunque sul sito.

In Drupal, il concetto di "livello theme" si applica principalmente ai file CSS e non ai file JavaScript nel contesto delle librerie. Ciò è dovuto al fatto che i file CSS spesso sono strettamente legati all'aspetto e alla presentazione del sito, e quindi è logico includerli nel tema del sito.

D'altra parte, i file JavaScript possono essere utilizzati per molteplici scopi, non solo per l'aspetto visivo del sito, ma anche per funzionalità interattive, logica di business e altro ancora. Pertanto, non sempre ha senso includere automaticamente tutti i file JavaScript nel tema del sito.

Drupal fornisce un meccanismo per includere i file JavaScript dove sono necessari utilizzando hook e altri metodi di programmazione. Ad esempio, è comune utilizzare hook per includere file JavaScript solo nelle pagine che richiedono determinate funzionalità o interazioni.

Creazione del modulo vero e proprio

Dopo aver creato il file .info.yml, potresti voler aggiungere anche un file .module, che conterrà i hook e le funzioni personalizzate del modulo. Puoi creare un file chiamato my_module.module nella stessa directory. Anche se inizialmente il file può essere vuoto, sarà il luogo dove aggiungerai il codice PHP specifico del modulo.

Esempi di Utilizzo

Ecco alcuni esempi di ciò che potresti includere nel tuo file .module:

/**
 * Implements hook_menu().
 */
function my_module_menu() {
  $items['my-custom-page'] = array(
    'title' => 'My Custom Page',
    'page callback' => 'my_module_custom_page_callback',
    'access callback' => TRUE,
  );
  return $items;
}

/**
 * Callback function for the custom page.
 */
function my_module_custom_page_callback() {
  return 'Hello from my custom page!';
}

Dopo aver creato il file .module e definito il codice del tuo modulo, puoi andare alla pagina di amministrazione dei moduli nel backend di Drupal e abilitare il nuovo modulo. Da qui, il modulo sarà attivo sul tuo sito e il codice in esso contenuto sarà eseguito quando richiesto.

Nelle prossime lezioni vedremo come interagire con il CORE di Drupal, per adesso ci fermiamo qui con la parte tecnica.

Best practice per la creazione di moduli personalizzati

• Utilizza un nome univoco e descrittivo per il tuo modulo, ad esempio "my_module".
• Segui le guide di sviluppo di Drupal per creare moduli sicuri e stabili.
• Utilizza la sintassi corretta per definire le dipendenze nel file "info".
• Testa il tuo modulo regolarmente per assicurti che funzioni correttamente.
• Documenta il tuo modulo con informazioni dettagliate sulla sua configurazione e utilizzo.

In conclusione, la creazione di moduli personalizzati per Drupal è un processo relativamente semplice che richiede solo un po' di conoscenza di PHP e delle best practice di sviluppo. Seguendo i passaggi e le best practice descritte in questo articolo, puoi creare moduli personalizzati funzionali e stabili per estendere la funzionalità del tuo sito Drupal.