Creare un Modulo Custom

Ritratto di Vanni

Drupal 7 mette a disposizione dei webmaster migliaia di moduli diversi per le più disparate necessità. A volte però non bastano. La stragrande maggioranza delle volte ci basta modificare un modulo già esistente per “piegarlo” alle nostre esigenze (vedi un semplice esempio di modifica ad un modulo), in altre occasioni si deve, però, costruirlo da zero.

Quando si costruisce un modulo nuovo, lo si definisce modulo custom, e se abbiamo fatto un buon lavoro lo possiamo rendere pubblico  in modo che altre persone possano utilizzarlo. Tutto ciò che riguarda lo sviluppo di Drupal lo trovate qui.

Costruire un modulo personalizzato è utile anche per capire come funziona la logica di Drupal. Quindi anche se non siamo dei programmatori, provare a creare un semplicissimo modulo, può essere molto utile proprio per comprendere il suo “modus operandi”.

In questa pagina andrò ad elencare le procedure più importanti da seguire per sviluppare un modulo ed infine riporterò un semplicissimo esempio. Non essendo un programmatore potrei scrivere qualcosa di sbagliato o in maniera poco tecnica, il mio solo intento è di dare una prima idea generale su come funziona un modulo di Drupal, per qualsiasi approfondimento rimando alla guida ufficiale e alla pagina delle API.

A chi si avvicina allo sviluppo di moduli, consiglio l’uso di Examples.

Cosa serve per sviluppare un modulo custom?

Per sviluppare un modulo personalizzato si devono avere delle conoscenze e dei requisiti di base:

  • PHP (sintassi e programmazione ad oggetti), eventualmente anche JavaScript
  • MySql (o comunque altro ambiente per database) e SQL
  • Un’installazione di Drupal funzionante

Come si sviluppa un modulo custom?

Chi è già molto ferrato nella programmazione con PHP non dovrebbe avere grosse problematiche, superata la fase iniziale nel capire in che modo opera Drupal, poi troverà la strada tutta in discesa. Però è bene fin da subito familiarizzare con alcuni “standard di codifica” che si utilizzano per convenzione. All’interno della comunità di sviluppatori si seguono delle apposite regole per rendere il codice leggibile e usufruibile da chiunque. Tutte le “regole” da seguire sono descritte qui, ma vediamo quali sono le principali:

  • Commenti - Per inserire un commento di una funzione, classe, costante ecc.. si usa lo stile Doxigen doc-block che si effettuta inserendo un doppio asterisco all’inizio (es: /**commento*/). Per gli altri commenti si usa il classico doppio slash (es: //commento)
  • Inizio script – Gli script iniziano con il classico tag (es: <?php) ma non devono essere chiusi, questo per vari motivi (per maggiori info vedi qui)
  • Spazi – Normalmente si lascia uno spazio prima e dopo gli “operatori”, si lascia uno spazio anche tra il nome di una struttura (ad es una funzione) e la parentesi graffa
  • Nomi – I nomi di funzioni e variabili si scrivono in lettere minuscole e se sono formati da più parole, le si separano con un under score

Doxigen doc-block

Si fa un ampio ricorso ai commenti quando si costruisce un modulo, in maniera che tutte le persone che poi prendono in mano tale codice, possano, in poco tempo, capire a cosa fanno riferimento i vari script.

Per Drupal si usa lo stile Doxigen doc block (la documentazione si trova qui e qui). Questo genere di commento contiene un’informazione all’API ( vedi API Drupal) che si andrà ad utilizzare e che potrà, così, essere estratta dagli altri sviluppatori.

Il primo commento da inserire è quello che dichiara che quel “doc-block” si riferisce all’intero file del modulo e contiene il testo “@file” e inoltre descrive lo scopo del modulo, ecco un esempio estratto dal modulo del core “blog”:

/**
  * @file
  * Enables multi-user blogs.
  */

Poi di prassi si inserire un commento in precedenza ad ogni funzione che richiama un hook, in cui si descrive il tipo di hook che si và ad usare, ad esempio:

/**
  * Implements hook_node_info().
  * Eventuali altre informazioni…
  */

Gli Hook

Al suo interno, Drupal, ha già una lunga lista di strutture codificate in PHP (funzioni, classi ecc..), questo permette di richiamarle ed utilizzarle in maniera molto veloce dall’interno dei moduli. Tutto ciò è possibile grazie all’utilizzo di hook (per maggiori info). Ad esempio se dobbiamo andare ad interagire con un menu, andremo a richiamare, all’interno del file del nostro modulo, la funzione hook_cron() che si trova descritta qui e basterà sostituire alla parola “hook” il nome del nostro modulo (es: “nome_mio_modulo_cron()”).

La  maggior parte degli hook si trova all’interno del core, ma ogni modulo può avere degli hook propri e che possono venire utilizzati da altri, questa è una delle ragioni del perché alcuni moduli richiedono l’attivazione di altri.

La funzione t()

Drupal permette la gestione di siti in moltissime lingue diverse (vedi costruire sito multilingua e tradurre interfaccia sito), quindi molto spesso quando si guarda il codice di un modulo, si vedono delle stringhe di testo (o anche altri parametri) inserite all’interno della funzione t()

Esempio :  t('Use for multi-user blogs. Every user gets a personal blog.')

Se il sito è in lingua inglese, non succederà niente, verrà visualizzata all’utente il testo così com’è scritto; viceversa, se il sito è in un’altra lingua quel testo verrà tradotto.

Ciclo Switch e $delta

Il ciclo switch è molto usato dai sviluppatori di Drupal soprattutto quando si sviluppano moduli che riguardano i blocchi. Spesso lo si trova associato all’argomento $delta. Questo argomento si usa per ragioni storiche ma ultimamente si è cominciato a sostituirlo con il nome del blocco stesso e serve ad identificare il blocco che dovrà essere ritornato.

Ad esempio è facile trovare una funzione del genere:

function nome_modulo_block_view($delta = '') {
  switch ($delta) {
    // codice da esguire
   }
return $block;
}

Ma la stessa funzione può essere riscritta:

function nome_modulo_block_view($block_name = '') {
  if ($block_name == 'nome_del_blocco') {
    // codice da eseguire
}
return $block;
}

Esempio di come costruire un modulo custom

Il modulo che andrò a costruire è estremamente semplice e banale, ma serve solo a dare un’idea di come si possa crearne uno personalizzato.

La finalità del modulo che andrò ad ideare è creare un link nel menu navigazionale che colleghi ad una pagina di saluto.

  • Creo una cartella con il nome del modulo, ad esempio “Il Mio Modulo”, e la inserisco all’interno di sites/all/modules o sites/default/modules (nel secondo caso si deve creare anche la cartella “modules”, per convenzione i moduli custom non si inseriscono in mezzo agli altri moduli scaricabili)
  • Con un editor di testo creo 2 file da inserire all’interno della cartella, un file lo chiamo ilmiomodulo.info e l’altro ilmiomodulo.module (questo è il numero minimo di file che compongono un modulo), il primo serve a dare a Drupal le informazioni riguardanti il modulo e il secondo contiene il codice PHP
  • Apro con l’editor il miomodulo.info e vado ad inserire le varie informazioni utili a Drupal per gestire il modulo:
name = Il Mio Modulo
description = Questo modulo crea una pagina di saluto
core = 7.x
package = Moduli Custom

dependencies[]= blog

Le prime 3 righe sono obbligatorie e rappresentano il nome, la descrizione e per quale core è stato progettato. Qui la lista completa di ciò che può essere scritto.

Anche se per questo modulo non serve assolutamente a niente, ho inserito anche  una dipendenza dal modulo “blog” (giusto per dare un esempio) la quale ne imporrà l’attivazione.

pagina di abilitazione del nuovo modulo custom

  • Apro il secondo file e dopo l’inserimento dei tag <?php comincio a scrivere il codice per far funzionare il modulo
  • Inserisco il commento riguardante il @file
/**
 * @file
 * Il file del modulo per ilmiomodulo_module.
 */
  • Inserisco il commento per hook_help() (questo hook crea una pagina di aiuto per l’utente ed è buona norma inserirlo, per maggiori info)
/**
 * Implementa hook_help().
 *
 * Implementa una pagina di aiuto per l'utente
 *
 * @see hook_help()
 */

visualizzazione del link per la pagina di aiuto

  • Inserisco la mia prima funzione che andrà a chiamare hook_help()
function ilmiomodulo_help($path, $arg) {
  switch ($path) {
    case 'admin/help#ilmiomodulo':
      return '<p><strong>' . t('This is help text for Il Mio Modulo.') . '</strong></p>';
  }
}

Come si può vedere ho sostituito la parola hook con il nome del mio modulo, ho inserito l’Url (path) dove visualizzare la pagina di aiuto e ho inserito il testo da ritornare

visualizzazione della pagina di aiuto

  • Inserisco il commento per hook_menu() (per maggiori info) e poi ho inserisco la funzione che lo utilizza
/**
 * Implementa hook_menu().
 *
 * Inserisce un link nel menu
 *
 * @see hook_menu()
 */

function ilmiomodulo_menu() {
  $items['pagina/ilmiomodulo'] = array(
    'title' => 'Pagina di saluto',
    'page callback' => 'ilmiomodulo_saluto',
    'access arguments' => array('accesso ad una nuova pagina'),
  );
  return $items;
}

L’array $items contine l’Url che avrà la pagina, poi creo un array con il titolo che dovrà essere dato al link (title), la funzione che dovrà richiamare (page callback) e un array di argomenti per accedere alla funzione di call back (access arguments)

  • Creo la funzione ilmiomodulo_saluto richiamata dalla funzione precedente
/**
 * Inserisce il costrutto della pagina
 */

function ilmiomodulo_saluto() {
  return array('#markup' => '<p>' . t('Say Hello to the world') . '</p>');
}

visualizzazione della pagina creata dal modulo custom

Questo è il codice completo del file ilmiomodulo.module (da notare che non ho chiuso con ?>):

<?php

/**
 * @file
 * Il file del modulo per ilmiomodulo_module.
 */

/**
 * Implementa hook_help().
 *
 * Implementa una pagina di aiuto per l'utente
 *
 * @see hook_help()
 */

function ilmiomodulo_help($path, $arg) {
  switch ($path) {
    case 'admin/help#ilmiomodulo':
      return '<p><strong>' . t('This is help text for Il Mio Modulo.') . '</strong></p>';
  }
}

/**
 * Implementa hook_menu().
 *
 * Inserisce un link nel menu
 *
 * @see hook_menu()
 */

function ilmiomodulo_menu() {
  $items['pagina/ilmiomodulo'] = array(
    'title' => 'Pagina di saluto',
    'page callback' => 'ilmiomodulo_saluto',
    'access arguments' => array('accesso ad una nuova pagina'),
  );
  return $items;
}

/**
 * Inserisce il costrutto della pagina
 */

function ilmiomodulo_saluto() {
  return array('#markup' => '<p>' . t('Say Hello to the world') . '</p>');
}

Aggiungi un commento

Filtered HTML

  • Indirizzi web o e-mail vengono trasformati in link automaticamente
  • Elementi HTML permessi: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Linee e paragrafi vanno a capo automaticamente.

Comment

  • Elementi HTML permessi: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Linee e paragrafi vanno a capo automaticamente.
  • Indirizzi web o e-mail vengono trasformati in link automaticamente

Plain text

  • Nessun tag HTML consentito.
  • Indirizzi web o e-mail vengono trasformati in link automaticamente
  • Linee e paragrafi vanno a capo automaticamente.
Per tutelare la vostra privacy suggerisco l'uso di un nickname o lasciare anonimo...
CAPTCHA
Questa domanda e' per testare se sei un visitatore persona e non un software che genera spam
3 + 3 =
Risolvi la semplice domanda di matematica e inserisci il risultato. Es. se e' 1 + 3 inserisci 4.