Creare un tema in Drupal

Hello world! Essendo Tecnomeme realizzato interamente con il popolare sistema di gestione contenuti (aka CMS - Content Management System) Drupal, ho pensato di inaugurare il sito proprio con un post dedicato a questa potente e flessibile piattaforma.

Nel particolare vedremo come realizzare quello che in gergo drupalese viene chiamato un tema, altrimenti conosciuto in altri sistemi come "skin" o "template". Bene, avanti allora.

Conoscenze necessarie

un poco di PHP
CSS
(X)HTML di base

Concetti di base del funzionamento dei templates in Drupal

Tema: l'equivalente di "template" o "skin" ("theme" è la parola magica qualora desideriate approfondire la ricerca su Drupal.org ;)
PHPTemplate: il motore di rendering ufficiale di Drupal.
Blocco: un blocco è un insieme definito di contenuti di un certo tipo che viene posizionato in un'area precisa della pagina
Regione: sono le aree della pagina definite a priori, dove è possibile inserire i blocchi di contenuti. Le regioni di default in Drupal sono 5:
- header
- left sidebar
- right sidebar
- content
- footer

Files di un template Drupal

Un buon punto di partenza è il tema Zen. Zen è stato pensato come un tema semplice per chi vuole creare un proprio template. Per questo mette a disposizione un'ampia documentazione sotto forma di commenti nel PHP, nel CSS e nell'HTML. Questa è una lista dei files contenuti nel tema Zen:

I file essenziali che troverete praticamente in qualsiasi tema sono i seguenti:

page.tpl.php: il template principale che definisce il contenuto di ogni pagina.
node.tpl.php: questo file definisce il contenuto di ogni singolo nodo.
block.tpl.php: definisce il contenuto dei blocchi.
comment.tpl.php: definisce il contenuto dei commenti.
box.tpl.php: aggiunge un box attorno ad alcuni elementi, ad esempio ai commenti (raramente usato).
screenshot.png: uno screenshot del tema, utilizzato nelle pagine di amministrazione e nelle pagine personali di ogni utente se volete dare la possibilità ai vostri visitatori di scegliere tra più temi.
logo.png: il logo grafico se ne usate uno.
style.css: il foglio di stile principale del tema.
favicon.ico: quella piccola icona che viene visualizzata nella barra dell'indirizzo dei moderni browsers accanto all'URL
template.php: questo file permette di intervenire più a fondo nel tema, ad esempio aggiungendo ulteriori regioni, riscrivendo le variabili di default e altro.

In pratica, ciascun file di tipo .tpl.php contiene un insieme di codice HTML, PHP e CSS necessario a definire rispettivamente la struttura, il contenuto e l'aspetto di ciascuna porzione della pagina. Il ruolo e la gerarchia dei tre principali templates è illustrato nella figura qui sotto:

Drupal Template files

Immagine tratta da "Pro Drupal Development"

Creare il nostro tema Drupal

Ciascun file di template (.tpl.php) può invocare determinate variabili per mostrare determinati contenuti e informazioni (es: il titolo della pagina, la data, il contenuto principale, l'utente che l'ha creata,...). Vediamo quali sono singolarmente, e vediamo anche un modello di base per ciascun file del template (clicca per dipanare i contenuti):

page.tpl.php

$base_path: Restituisce l'URL di base dell'installazione Drupal (di default porta a / ).
$breadcrumb: Questa variabile permette di stampare i breadcrumbs trails (es: home > sezione > nodo) in cima alla pagina.
$closure: Deve essere inserita in fondo pagina per chiamare gli eventuali javascript dinamici una volta che il contenuto della pagina è stato caricato.
$content: Il contenuto HTML principale di una pagina generato da Drupal.
$css: Un array contenente tutti i file CSS della pagina corrente.
$directory: La directory in cui si trova il tema utilizzato, es:; themes/garland o sites/default/themes/zen.
$feed_icons: Una stringa con tutte le icone degli RSS feeds disponibili per la pagina corrente.
$footer_message: Il messaggio del footer definito nei settings delle pagine di amministrazione.
$head: HTML generato da drupal_get_html_head().
$head_title: Il testo mostrato nell'header della pagina.
$help: Testo di help dinamico, utilizzato nelle pagine di amministrazione.
$is_front: Questa variabile è vera (TRUE) se ci si trova nella homepage. Viene solitamente usata per mostrare la mission solo in homepage.
$language: La lingua con cui si sta mostrando il sito.
$layout: Permette di configurare diversi tipi di layout ('none', 'left', 'right' o 'both') a seconda di quante sidebar vengono abilitate.
$logo: Il path del logo, come definito nella configurazione del tema (admin).
$messages: HTML per i messaggi di stato e di errore che vengono mostrati in cima al contenuto della pagina.
$mission: Il testo della mission del sito, che viene mostrato se la mission è abilitata nei settings del tema (admin).
$node: (5.x e successivi) Per mostrare un intero nodo nel template page.tpl.php.
$onload_attribute: (4.7 e precedenti) Onload tags da aggiungere nella head della pagina, per permettere l'esecuzione automatica degli script.
$primary_links (array): Un array contenente i links di navigazione primari.
$scripts: (5.x e successivi) HTML per caricare i files JavaScript e i settings JS. I files javascript devono essere inseriti manualmente nel template della pagina (page.tpl.php).
$search_box: Mostra il campo di ricerca se la ricerca (search box) è abilitata nella configurazione del tema (admin).
$search_button_text: (4.7 e precedenti) Il testo tradotto del bottone di ricerca.
$search_description: (4.7 e precedenti) Il tsto tradotto della descrizione del bottone di ricerca.
$search_url: (4.7 e precedenti) URL al quale viene inviata la form di ricerca.
$secondary_links (array): Un array contenente i links di navigazione secondari.
$sidebar_left: L'HTML per la sidebar di sinistra.
$sidebar_right: L'HTML per la sidebar di destra.
$site_name: Mostra il nome del sito, a meno che non sia disabilitato nei settings del tema (admin).
$site_slogan: Lo slogan del sito, a meno che non sia disabilitato nei settings del tema (admin).
$styles: Necessario per far funzionare i fogli di stile: restituisce i file .css richiesti dalla pagina.
$tabs: HTML per mostrare i tabs in cima alla pagina.
$title: Il titolo della pagina (diverso dal titolo dell'header head_title), solitamente il titolo del nodo o della sezione che viene mostrato sopra al contenuto.

Page template di default (Drupal 5)

	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" lang="<?php print $language ?>" xml:lang="<?php print $language ?>">

	<head>
	  <title><?php print $head_title ?></title>
	  <?php print $head ?>
	  <?php print $styles ?>
	  <?php print $scripts ?>
	  <script type="text/javascript"><?php /* Needed to avoid Flash of Unstyle Content in IE */ ?> </script>
	</head>

	<body>

	<table border="0" cellpadding="0" cellspacing="0" id="header">
	  <tr>
	    <td id="logo">
	      <?php if ($logo) { ?><a href="<?php print $base_path ?>" title="<?php print t('Home') ?>">
	<img src="<?php print $logo ?>" alt="<?php print t('Home') ?>" /></a><?php } ?>
	      <?php if ($site_name) { ?><h1 class='site-name'><a href="<?php print $base_path ?>" 
	title="<?php print t('Home') ?>"><?php print $site_name ?></a></h1><?php } ?>
	      <?php if ($site_slogan) { ?><div class='site-slogan'><?php print $site_slogan ?></div><?php } ?>
	    </td>
	    <td id="menu">
	      <?php if (isset($secondary_links)) { ?><?php print theme('links', $secondary_links, 
    array('class' =>'links', 'id' => 'subnavlist')) ?><?php } ?>
	      <?php if (isset($primary_links)) { ?><?php print theme('links', $primary_links, 
    array('class' =>'links', 'id' => 'navlist')) ?><?php } ?>
	      <?php print $search_box ?>
	    </td>
	  </tr>
	  <tr>
	    <td colspan="2"><div><?php print $header ?></div></td>
	  </tr>
	</table>

	<table border="0" cellpadding="0" cellspacing="0" id="content">
	  <tr>
	    <?php if ($sidebar_left) { ?><td id="sidebar-left">
	      <?php print $sidebar_left ?>
	    </td><?php } ?>
	    <td valign="top">
	      <?php if ($mission) { ?><div id="mission"><?php print $mission ?></div><?php } ?>
	      <div id="main">
	        <?php print $breadcrumb ?>
	        <h1 class="title"><?php print $title ?></h1>
	        <div class="tabs"><?php print $tabs ?></div>
	        <?php print $help ?>
	        <?php print $messages ?>
	        <?php print $content; ?>
	        <?php print $feed_icons; ?>
	      </div>
	    </td>
	    <?php if ($sidebar_right) { ?><td id="sidebar-right">
	      <?php print $sidebar_right ?>
	    </td><?php } ?>
	  </tr>
	</table>

	<div id="footer">
	  <?php print $footer_message ?>
	</div>
	<?php print $closure ?>
	</body>
	</html>
	

node.tpl.php

$content: Il contenuto del nodo, o il suo teaser se si tratta di un sommario di più nodi.
$date: La data di creazione del nodo.
$directory: La directory in cui si trova il tema utilizzato, es: themes/garland o sites/default/themes/zen.
$id: L'ID sequenziale del nodo che viene mostrato in una lista.
$is_front: Questa variabile è vera (TRUE) se ci si trova nella homepage.
$links: I links del nodo.
$name: Il nome dell'autore del nodo.
$node (object): Un determinato oggetto del nodo. Per vedere tutte le proprietà degli oggetti di un nodo, inserisci questo codice nel file node.tpl.php del tema utilizzato: <pre><?php print_r($node); ?></pre>
$node_url: Link al nodo.
$page: Questa variabile è vera (TRUE) se il nodo viene mostrato da solo nella pagina.
$picture: L'HTML che mostra la foto (avatar) dell'autore, se abilitato nei settings del tema.
$sticky: Questa variabile è vera (TRUE) se il nodo è "sticky" (fisso in cima alla lista).
$submitted: Autore e data di creazione del nodo, se questa informazione è abilitata per il tipo di contenuto in questione nei settings di configurazione del tema.
$taxonomy (array): Un array contenente i links ai taxonomy terms con i quali è classificato il nodo.
$teaser: Restituisce il teaser (sommario) del nodo anzichè l'intero contenuto
$terms: L'HTML dei taxonomy terms con i quali è classificato il nodo.
$title: Il titolo del nodo.
$zebra: Questa variabile assume il valore alternato odd/even in una lista. E' utile per dare uno stile "zebrato" ad una lista.

Node template di default

<div id="node-<?php print $node->nid; ?>" class="node<?php if ($sticky) { print ' sticky'; } ?><?php if (!$status) 
{ print ' node-unpublished'; } ?> clear-block">

<?php print $picture ?>

<?php if ($page == 0): ?>
  <h2><a href="<?php print $node_url ?>" title="<?php print $title ?>"><?php print $title ?></a></h2>
<?php endif; ?>

  <div class="meta">
  <?php if ($submitted): ?>
    <span class="submitted"><?php print $submitted ?></span>
  <?php endif; ?>

  <?php if ($terms): ?>
    <span class="terms"><?php print $terms ?></span>
  <?php endif;?>
  </div>

  <div class="content">
    <?php print $content ?>
  </div>

<?php
  if ($links) {
    print $links;
  }
?>

</div>

block.tpl.php

$block->module: Il nome del modulo che ha generato un blocco.
$block->delta: Il numero del blocco di un certo modulo.
$block->subject: Il titolo del blocco.
$block->content: Il contenuto HTML del blocco.
$block->status: Lo stato del blocco (0 o 1).
$block->region: Il nome della regione. Di default le regioni disponibili sono 'left', 'right', 'header' and 'footer'.
$block->throttle:: Setta il Throttle dei blocchi.
$directory: La directory in cui si trova il tema utilizzato, es: themes/garland o sites/default/themes/zen.
$is_front: Questa variabile è vera (TRUE) se ci si trova nella homepage. Viene solitamente usata per mostrare la mission solo in homepage.
$id: L'ID sequenziale del blocco (primo blocco: 1, secondo blocco: 2, etc.).
$block_id: Lo stesso di $id, ma questa variabile viene resettata per ciascuna sidebar (left e right).
$zebra: Questa variabile assume il valore alternato odd/even in una sequenza di blocchi. E' utile per dare uno stile "zebrato" con i fogli stile .css.
$block_zebra: Lo stesso di $zebra, ma questa variabile viene resettata per ciascuna sidebar (left e right).

Block template di default

<div id="block-<?php print $block->module .'-'. $block->delta; ?>" class="block block-<?php print 
$block->module ?>">

<?php if ($block->subject): ?>
  <h2><?php print $block->subject ?></h2>
<?php endif;?>

  <div class="content"><?php print $block->content ?></div>
</div>

comment.tpl.php

$author: nome dell'autore collegato al suo profilo se ne ha uno.
$comment: l'oggetto del commento contenente tutti i suoi attributi.
$content: il corpo del commento.
$date: la data di creazione del commento.
$directory: la directory in cui si trova il tema corrente, es. themes/garland or themes/garland/minelli.
$id: l'ID numerico del commento.
$is_front: questa variabile è vera (true) se ci si trova nell'homepage.
$links: links contestuali al commento.
$new: se il commento è nuovo, mostra il testo "New".
$picture: Foto o avatar dell'utente linkata al profilo dell'utente stesso. La funzione deve essere abilitata nei settings del tema e degli users, e l'utente deve prima inserire un'immagine.
$submitted: "scritto da" + nome dell'autore e data di creazione.
$title: titolo ipertestuale del commento.
$zebra: questa variabile alterna even/odd di commento in commento (utile per theming avanzato).

Comment template di default

<div class="comment<?php print ($comment->new) ? ' comment-new' : ''; print ($comment->status == 
COMMENT_NOT_PUBLISHED) ? ' comment-unpublished' : ''; ?> clear-block">
  <?php print $picture ?>

<?php if ($comment->new) : ?>
  <a id="new"></a>
  <span class="new"><?php print $new ?></span>
<?php endif; ?>

  <h3><?php print $title ?></h3>

  <div class="submitted">
    <?php print $submitted ?>
  </div>

  <div class="content">
    <?php print $content ?>
  </div>

  <?php print $links ?>
</div>

Questi templates di default sono un ottimo punto di partenza per creare il proprio tema Drupal da zero. In ogni modo se siete alle primissime armi la cosa migliore è iniziare con il personalizzare un tema già esistente. Torniamo quindi al nostro caro tema Zen:

scarichiamo l'ultima versione disponibile, scompattiamola e spostiamo la cartella del tema nella directory /sites/default/themes della nostra installazione Drupal.
creiamo una copia della cartella del tema e chiamiamola ad esempio "Zen-custom".
attiviamo e selezioniamo il tema "Zen-custom" dall'area admin (/admin/build/themes) della nostra installazione Drupal.
bene, siamo pronti per iniziare a mettere le mani sul codice XHTML dei singoli files del template (per cominciare page.tpl.php, node.tpl.php, block.tpl.php, comment.tpl.php) per modificare struttura di base, ordine degli elementi e classi. Possiamo inserire o eliminare le singole variabili PHP viste sopra per mostrare o nascondere i contenuti che ci interessano.
Per finire apriamo il nostro foglio stile style.css nel nostro editor di testo preferito e modifichiamo il codice CSS (classi, sottoclassi, identificatori,..). Utilizzeremo invece un programma grafico o di fotoritocco per editare le immagini, gli sfondi, i bottoni e tutti gli elementi grafici che vogliamo modificare.
Salviamo files e immagini, cancelliamo la cache del browser (importante se vogliamo vedere le modifiche, dato che Drupal utilizza una cache piuttosto aggressiva) e ammiriamo il nostro primo tema Drupal :)

In questo articolo sono state esposte le tecniche di base per la personalizzazione e la creazione di un tema in Drupal. Altre tecniche avanzate (PHPTemplate, Variables Overrides, Themable Functions,...) permettono di creare temi complessi. Spero di riuscire a trattarle presto. Per i più impazienti, esistono diversi manuali in inglese che trattano questi argomenti.

Servizio professionale: se non hai il tempo, la voglia o le conoscenze per occuparti della conversione del tuo design JPG, PNG o PSD in un tema Drupal, se vuoi personalizzare un tema open source o convertire il tuo sito a Drupal, puoi avvalerti dei servizi di PureDivs, conversioni professionali da design psd a temi Drupal.

UPDATE: ho aggiunto negli uploads uno schema che rappresenta la struttura delle classi del tema Zen. E' una guida visuale utile a comprendere la struttura di un tema Drupal e ad individuare facilmente quali classi del foglio stile modificare per personalizzare il tema a proprio piacimento.

Questa introduzione ti è stata utile? Vorresti che venga approfondito qualche argomento in particolare? Mi farebbe piacere sapere che ne pensi, quindi se hai un minuto lascia un commento qui sotto ;)

Bravo sì!

Submitted by debora on Thu, 24/09/2009 - 11:56.

Se conoscessi le variabili, le classi, il php, i css etc. potrei quasi riuscirci :-)
Comunque, pur non sapendo nulla di tutto ciò, sono convinta che hai fatto un gran lavoro.
Pecca però di una cosa: l'offerta di fare un template a chi proprio è ignorante come me :-)
Ciaoooo

detto fatto :)

Submitted by admin on Fri, 25/09/2009 - 07:35.

per qualsiasi necessità di theming Drupal puoi visitare http://puredivs.com lo aggiungo in commento alla guida, grazie :)

OTTIMO

Submitted by Antonio on Wed, 15/04/2009 - 13:02.

Ben fatto, grazie mille, io sto perdendo ore a tradurre i relativi libri in inglese!

Citato sulla tesi

Submitted by Patrizio Emili on Tue, 03/03/2009 - 17:15.

Ciao Marco, sei stato provvidenziale nel fornire anche la traduzione delle variabili per i varii *tpl.php. Mi hai risparmiato un paio d'ore e per questo ti meriti la citazione sulla mia tesi di laurea. Grazie

bravo!!

Submitted by anonimo on Thu, 05/02/2009 - 20:02.

davvero un ottimo tutorial!! semplice e intuitivo!! bravo!

se avessi (ri)fatto

Submitted by anonimo on Sun, 07/09/2008 - 17:06.

se avessi (ri)fatto l'immagine dello schema di page.tpl.php sarebbe stato un articolo davvero unico! (ho visto la stessa immagine nel libro Pro Drupal Development..
per tutto il resto è un ottimo tutorial :)

absolutely right

Submitted by admin on Tue, 09/09/2008 - 08:36.

infatti l'immagine è tratta proprio da quel manuale. Per dare a Cesare quel che è di Cesare (shame on me, avrei dovuto farlo al momento della prima pubblicazione del libro..Matt, mi perdonerai? ;) ho aggiunto il dovuto credit a fianco immagine. Grazie per avermelo ricordato!

complimenti

Submitted by ciccio on Sun, 04/05/2008 - 14:52.

ciao, grazie per il mini-tutorial, davvero molto utile.
Volevo segnalarti questo tutorial in inglese
http://www.nicklewis.org/node/841
'mi sembra' ben fatto ma la mia conoscenza dell'inglese non mi permette di approfondire.
Affronta le tecniche 'avanzate' a cui tu fai riferimento

Cosa ne pensi?

...magari ti va di tradurlo, ampliarlo ?

grazie, ciao e complimenti ancora