Decodifica URL

Drupal è un sistema in cui le pagine richieste sono quasi sempre costruite dinamicamente.
Il testo della pagina è archiviato in un database e quando viene richiesto, Drupal deve leggerlo e trasformarlo in codice HTML per essere visualizzato sul browser.
Drupal è quindi un sistema che genera pagine dinamiche.
Quando un browser invia un URL per richiedere una pagina del sito ,il sistema deve individuare dall' URL quale funzioni attivare per generare e visualizzare la pagina richiesta.
Il meccanismo che individua le funzioni da richiamare è descritto qui di seguito.

Impostazione della variabile $_GET['q']

La variabile $_GET['q'] , e il suo valore , è resa disponibile dal server web.
Il server web imposta il valore di $_GET['q'] al percorso richiesto interno al sito, in seguito indicato con il termine path. E' dal valore di questa variabile che Drupal parte per determinare quale funzione attivare per visualizzare il contenuto richiesto.

Ad esempio:
se l' URL=http://miosito.com allora $_GET['q'] = ''
se l' URL=http://miosito.com/node/345 allora $_GET['q'] = node/345
se l' URL=http://miosito.com/contabilita/elenco-fatture/attive allora $_GET['q'] = contabilita/elenco-fatture/attive

Conversione Url alias

Richiesta della home page

Se l' URL inviato contiene il solo nome del sito www.miosito.com e quindi $_GET['q'] = "", Drupal non effettua alcuna conversione riconoscendo nell' URL la richiesta della home page del sito.
In questo caso Drupal forza $_GET['q'] = "node".

Richiesta di una pagina generica

L'URL inviato al sistema, può contenere un alias dell'URL, come nell'esempio di "miosito.com/contabilita/elenco-fatture/attive". Il path contenuto nella variabile $_GET['q'] in questo caso sarà uguale a "contabilita/elenco-fatture/attive".
Il sistema per prima cosa converte il path ricevuto in un indirizzo interno e successivamente individua la funzione da attivare per estrarre dal database il contenuto richiesto.
La conversione viene eseguita nella fase di bootstrap, a cui si rimanda , ed in particolare nella fase di BOOTSTRAP_PATH.
In questa fase Drupal cerca nella tabella URL_ALIAS il path "contabilita/elenco-fatture/attive" e se esiste imposta la variabile $_GET['q'] al valore del corrispondente path di sistema.
Esempio: contabilita/elenco-fatture/attive => node/345
A conversione avvenuta avremo $_GET['q'] = node/345 e quindi il sistema saprà quale nodo deve essere visualizzato.
Evidentemente se non si trova una corrispondenza nella tabella indicata, significa che l'URL non contiene un alias e quindi la variabile $_GET['q'] non sarà alterata.

Individuazione della page_callback

Dopo l'eventuale conversione dell' URL , in $_GET['q'] si trova l'indirizzo reale della pagina da visualizzare.
Drupal deve ora individuare la page_callback, per estrarre e visualizzare il contenuto richiesto.

Abbiamo visto in Avvio di Drupal che all'interno del file index.php la lettura del contenuto viene eseguito dalla funzione menu_execute_active_handler(), il cui codice è parzialmente riportato a fondo pagina.
Questa , al suo interno, chiama la funzione menu_get_item() che individuerà la page_callback, e se specificato, caricherà anche il nodo o l'oggetto richiesto.
In che modo viene individuata la page callback?
La page_callback è individuata grazie alla tabella MENU_ROUTER. In questa tabella sono contenute le informazioni necessarie per individuare la page_callback, il cui nome è indicato nel campo <page_callback>. In particolare la colonna <path> contiene i possibili path parametrizzati che possono essere richiesti.
La tabella MENU_ROUTER è caricata da Drupal, quando si entra nel menu Amministrazione->Elenco moduli e si salva la pagina. Drupal chiamerà tutte le funzioni implementate nei moduli che hanno nome: nomemodulo_menu(). In queste funzioni sono definite le page_callback e tutte le infornazioni necessarie per eseguire le funzione richieste che saranno archiviate nella tabella MENU_ROUTER.Di tutto questo si parlerà nello parte dedicata all sviluppo dei moduli. Ad esempio, volendo modificare il nodo 12345 , potrebbe essere inviato a Drupal il path node/12345/edit.
In questo caso, il sistema cercherebbe nella colonna <path> uno dei seguenti path:

7 node/12345/edit
6 node/12345/%
5 node/%/edit
4 node/%/%
3 node/12345
2 node/%
1 node

Potrebbero non essere tutti presenti, ma tra quelli presenti, l'ordine di selezione è dato dal valore del campo <fit> della tabella.
Il path node/%/edit indica che il record della tabella contiene il nome della page_callback per tutti i path costituiti da 'node', un numero identificativo del nodo , e 'edit' come per 'node/12345/edit'
Individuato il path, il corrispondente record viene posto in un array e tornato alla funzione menu_execute_active_handler() che chiamerà la page_callback.
Oltre a tutti i campi della tabella menu_router, l'array conterrà anche:
$router_item[access] = che indica se si può accede al percorso.
$router_item[href] = equivalente al campo <path>
$router_item[localized_options] per ulteriori opzioni sul path inseribili da altre funzioni.

Gli argomenti della page callback e la lettura dell'oggetto

La funzione menu_get_item() è in grado di leggere l'oggetto richiesto (ad esempio un nodo) se nella tabella MENU_ROUTER è specificata una funzione di caricamento.

argomenti per la homepage

La page_callback chiamata è la node_page_default() a cui non vengono passati argomenti. Il valore $router_item[page_arguments] è nullo.

argomenti per un nodo generico

Abbiamo visto ad esempio che per la richiesta node/12345, il sistema trova nella tabella MENU_ROUTER il path 'node/%' e a questo corrispondono i due campi:
<page_callback> : node_page:view()
<load_function>: node_load() (serializzata in tabella)
Essendo presente il nome di una funzione di caricamento, la menu_get_item() sarà in grado di leggere l'oggetto, utilizzando la funzione indicata, e inserirlo in
$router_item[page_arguments] come argomento della funzione di page_callback.

Di seguito un frammento del codice che :

• chiama la menu_get_item() per riempire l'array $router_item con le informazione sulla page_callback da chiamare;
• lancia la page_callback tramite la funzione PHP call_user_func_array();

All'avvio di Drupal, il valore di $path è NULL e la funzione menu_get_item() leggerà il path dalla variabile globale $_GET['q'].
La page_callback a questo punto leggerà il contenuto e tornerà una stringa contenente il corrispondente codice HTML.

Bootstrap

La funzione drupal_bootstrap() è contenuta nel file ./includes/bootstrap.inc che viene subito caricato. All'interno del file bootstrap.inc sono definite le otto costanti che indicano quale sotto fase attivare nel bootstrap.

• DRUPAL_BOOTSTRAP_CONFIGURATION=0
• DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE=1
• DRUPAL_BOOTSTRAP_DATABASE=2
• DRUPAL_BOOTSTRAP_ACCESS=3
• DRUPAL_BOOTSTRAP_SESSION=4
• DRUPAL_BOOTSTRAP_LATE_PAGE_CACHE=5
• DRUPAL_BOOTSTRAP_PATH=6
• DRUPAL_BOOTSTRAP_FULL=7

Alla funzione drupal_bootstrap() viene passato un parametro che indica a quale fase fermarsi del bootstrap. All'avvio, e in generale su richiesta di un nodo generico, il parametro è posto uguale a DRUPAL_BOOTSTRAP_FULL in modo tale da eseguire tutte le otto le fasi. Le funzioni attivate dalle singole fase sono definite nella funzione _drupal_bootstrap($phase).

1) DRUPAL_BOOTSTRAP_CONFIGURATION
Funzioni utilizzate:
conf_init() inizializza le variabili
conf_path() torna il percorso del file settings.php

1. Vengono eliminate le definizioni , se esistenti (ini_get('register_globals')=1), delle variabili globali del php: _ENV, _GET, _POST, _COOKIE, _FILES, _SERVER, _REQUEST, access_check, GLOBALS .
2. Sono inizializzate le variabili globali locali di Drupal.
   Le variabili $db_url, $db_prefix ,$db_type sono lette dal file sites/default/settings.php
   Le variabili: $base_url, $base_path, $base_root, $cookie_domain, $conf, $installed_profile sono calcolate a run-time

2) DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE

Include il file ./includes/cache.inc
Funzioni utilizzate:
_drupal_cache_init()

Inizializzazione della cache.
All'avvio non viene eseguita nessuna operazione.

3) DRUPAL_BOOTSTRAP_DATABASE

Include il file ./includes/database.inc
Funzioni utilizzate:
- db_set_active() Apre la connessione al database definito in settings.php

Apre la connessione al database.
Le funzioni per accedere al database sono definite nel file ./includes/database.$db_type.inc. (tipicamente $db_type=mysql)

Se il file non esiste, Drupal si ferma indicando che non è possibile utilizzare il tipo di database definito in $db_type. Se la connessione va a buon fine viceversa vengono impostati i valori delle seguenti variabili globali:

• $db_url contiene la stringa di connessione definita in settings.php
• $db_type contiene il tipo di database da utilizzare per la connessione corrente (dedotta da $db_url)
• $active_db = Resource php al database attivo.

Se username='username' e password='password' in $db_url di settings.php, Drupal avvia l'installazione del sistema caricando il file instal.php. Il valore di ritorno della funzione db_set_active() è il nome del database precedentemente attivato, FALSE se non ce ne era nessuno.

4) DRUPAL_BOOTSTRAP_ACCESS

Funzioni utilizzate:
_drupal_is_denied()

La funzione drupal_is_denied(), verifica che ci siano i permessi per l'accesso all'host contenente Drupal.

5) DRUPAL_BOOTSTRAP_SESSION
Include il file ./includes/session.inc
Funzioni utilizzate:
session_set_save_handler() (nativa php)

Imposta le funzioni di archiviazione sessioni a livello utente, ed avvia mediante session_start() la gestione della sessione.

6) DRUPAL_BOOTSTRAP_LATE_PAGE_CACHE

Include i file ./includes/cache.inc, ./includes/module.inc
Funzioni utilizzate:
_drupal_cache_init()

Se la cache è abilitata e per la URL fornita esiste un record nella tabella cache, Drupal legge il contenuto della cache, visualizza la pagina e si ferma.
Se la cache non è abilitata o è vuota , Drupal torna dalla funzione _drupal_cache_init() e continua con il bootstrap eseguendo le funzioni e le fasi successive. In particolare in questa fase esegue le seguenti funzioni:
timer_start()
drupal_page_header()
Inizializza l'array globale $conf utilizzata dalla funzione variable_get().
Attiva , mediante drupal_page_header(), le impostazioni del protocollo HTTP per la risposta.

header("Expires: Sun,19 Nov 1978 05:00:00 GMT");
header("Last-Modified: ".gmdate("D, d M Y H:i:s")." GMT");
header("Cache-Control: store, no-cache, must-revalidate");
header("Cache-Control: post-check=0, pre-check=0", FALSE);

7) DRUPAL_BOOTSTRAP_PATH
Include il file ./includes/path.inc
Funzioni utilizzate:
drupal_init_path()

Inizializza la variabile $_GET['q'] al valore 'node'.

8) DRUPAL_BOOTSTRAP_FULL
Include il file ./includes/common.inc
Funzioni utilizzate:
_drupal_bootstrap_full()

E' l'ultima fase del bootstrap del sistema.

La funzione drupal_bootstrap_full() consente di caricare gli ultimi file include:
./includes/theme.inc
./includes/pager.inc
./includes/menu.inc
./includes/tablesort.inc
./includes/file.inc
./includes/unicode.inc
./includes/image.inc
./includes/form.inc
che conterranno le funzioni da utilizzare nelle tre successive fasi (vedi Avvio di Drupal), attivare delle funzioni di inizializzazione del sistema e caricare i moduli abilitati.
L'ultima funzione module_invoke_all('init') invoca tutte le funzioni di inizializzazione del tipo hook_init(), se esistenti, dei singoli moduli.

Visualizzazione del contenuto

Gli argomenti trattati fanno riferimento alla versione 5.x di Drupal

In questa fase Drupal visualizza la pagina richiesta utilizzando gli stili del tema impostato e il file page.tpl.php come guida per la costruzione dinamica della pagina.
Per fare questo Drupal chiama la funzione theme('page',$return) a cui passa, come argomenti, il parametro 'page' e il codice HTML del contenuto della pagina preparato nella precedente fase.

La funzione theme()
La funzione theme() individua la funzione corretta da eseguire. In questo caso, in base al parametro passato 'page' , chiamerà:

• miotema_page() se esiste questa funzione in /miotema/template.php
• phptemplate_page()se esiste questa funzione in phptemplate.engine >
• theme_page() altrimenti (questa funzione è sempre presentte in includes/theme.inc )

Generalmente, e consideriamo questo caso, Drupal trova e chiama la funzione phptemplate_page()

La funzione phptemplate_page()
Al suo interno la funzione avvia le seguenti operazioni:

• Legge e definisce la variabile $mission (missione del sito)
• Inserisce il path di favicon.ico nel tag <HEAD>
• Se richieste, riempie le barre laterali (sidebar-left e sidebar-right)

Le barre laterli
Per le barre laterali Drupal definisce la variabile $layout che pone uguale a:left, right, both, none a seconda che sia stata definita la barra laterale sinistra, la destra, entrambe o nessuna. In fase di definizione dello stile del tema, questa variabile può essere usata per definire le dimensioni delle regioni dei contenuti in funzione della presenza o meno delle barre laterali.

Poichè la barre laterali sono costituite da blocchi, Drupal legge tutti i blocchi da visualizzare nella pagina richiesta e genera il corrisondente codice HTML che pone nelle variabili $sidebar_left e $sidebar_right.
Il loop sui blocchi viene eseguito dalla funzione theme_blocks($region), essendo $region la regione da caricare: left o right.
Ogni singolo blocco è formattato con la funzione phptemplate_block() che a sua volta si avvale delle funzioni:

• _phptemplate_callback() per caricare, nell'array $variables, tutte le variabili da usare nei template
• phptemplate_default() per individuare il file di template da usare per il rendering
• _phptemplate_render()a cui viene passato il nome del file (generalmente block.tpl.php) di template e l'array $variables per eseguire la definitiva preparazione del codice HTML del blocco.

Il processo si ripete per il blocco successivo, fino a completare il codice di tutta la barra laterale.

E' possibile generare la funzione miotema_page($return) in template.php per decidere il valore della variabile $show_blocks che consente di nascondere(=false) o mostrare (=true) le barre laterali.

function miotema_page($return) {
	$show_blocks = false
	return phptemplate_page ($return,$show_blocks)
}

Caricamento

• Lettura del contenuto di un nodo - node_load()
• Lettura extra-contenuto di un nodo

Lettura del contenuto di un nodo - node_load()

La lettura del contenuto del nodo, è eseguita mediante la funzione node_load($nid) a cui è passato il valore dell'identificativo univoco del nodo <nid> da caricare. Al suo interno viene generata la query indicata, che usa tre tabelle:

• NODE da cui sono estratte informazioni sulla pubblicazione e tipo del nodo
• NODE_REVISIONS da cui sono estratte informazioni sul contenuto del nodo (Il titolo del nodo è letto da questa tabella e non da NODE come si potrebbe pensare)
• USERS da cui sono estratte informazioni sul proprietario del nodo

Query di selezione

SELECT n.nid, n.type, n.language, n.uid, n.status, n.created, n.changed, n.comment, n.promote, 
n.moderate,  n.sticky, n.tnid, n.translate, r.vid, r.uid AS revision_uid, r.title, r.body, r.teaser, r.log,
 r.timestamp AS revision_timestamp, r.format, u.name, u.picture, u.data 
FROM node n 
INNER JOIN users u ON u.uid = n.uid 
INNER JOIN node_revisions r ON r.nid = n.nid AND r.vid = <n.nid>
WHERE n.nid = <n.nid>

Dala funzione node_load() torna un oggetto ($node) contenente le informazioni lette mediante la query.
In particolare i valori $node->body e $node->teaser conterranno rispettivamente contenuto e sommario del nodo.

Oggetto $node generato dalla funzione.
(ND=da tabella NODE; NR da tabella NODE_REVISIONS; US da tabella USERS)

Lettura extra-contenuto di un nodo

Oltre alla lettura delle informazioni contenute specificatamente nelle tabelle NODE e NODE_REVISIONS, Drupal consente di aggiungere ulteriori informazioni ai nodi e quindi all'oggetto $node.
Potremmo decidere di definire un nuovo tipo di nodo con informazioni aggiuntive salvate in una tabella separata.
Pensiamo ad esempio ad una rubrica telefonica. Il nominativo e l'identificativo univoco potrebbero essere rispettivamente il campo <title> e il campo <nid> della tabella NODE, mentre tutte le informazioni aggiuntive come l'indirizzo, il telefono, l'email etc, potrebbero essere memorizzate in una tabella separata.
Si pone quindi il problema di leggere queste ulteriori informazioni associate ai nodi.
Drupal consente di leggere queste extra informazioni implementando funzioni particolari che gestiscano queste situazioni.
Dobbiamo distinguere due casi:

Implementazione della funzione legata alla tipologia del nodo

Nella tabella NODE_TYPES sono elencati il tipo di nodi definiti nel sistema. Tra questi sono presenti i nodi principali, forniti con il sistema, quali: page, book, story etc.
Dalla stessa tabella vediamo che il campo <module> ci dice da quale modulo sono gestiti i nodi.
Ora supponiamo di aggiungere il nuovo tipo di nodo "rubrica" e che questo tipo di nodo sia gestito dall'omonimo modulo con tutte le sue funzioni implementate in rubrica.module. Ora quando Drupal leggerà un nominativo dal nodo rubrica, nominativo e identificativo saranno letti come indicato nel precedente paragrafo, mentre l'ulteriore contenuto sarà letto chiamando la funzione rubrica_load($node). La funzione deve tornare un array associativo costituito dalle coppie chiave=valore. Un esempio di semplice codice è il seguente:

All'oggetto $node originale, Drupal aggiungerà le informazioni:

La funzione è chimata all'interno di node_load() mediante node_invoke($node,'load');
Attenzione:Nel caso il modulo di gestione sia quello di default node, il nome della funzione deve essere node_content_load() e non node_load() come dovrebbe.

Implementazione della funzione legata ad un modulo

In questo caso viene chiamata una funzione per avvisare altri moduli che si sta caricando un nodo.
Infatti la funzione non appartiene al modulo che gestisce il tipo di nodo come nel caso precedente , ma ad altri moduli attivi.
A questo punto la funzione chiamata potrebbe compiere due diverse operazioni:

• aggiungere informazione al nodo. Si ricade nel caso precedente e quindi anche la funzione potrebbe essere implementata in modo analogo.
• Utilizzare l'informazione di lettura del nodo contenute in $node per altre attività ad esempio per eseguire statistiche sulla frequenza di lettura di quel nodo.

In entrambi i casi possono dunque essere aggiunte o meno extra informazioni all'oggetto $node.
La funzione da implementare deve chiamarsi nomemodulo_nodeapi($node,$opz).
A questa funzione è passato l'oggetto $node e il valore $opz='load. che indica l'operazione che si sta eseguendo sul nodo .
Un esempio di semplice codice, nel caso in cui venga aggiunta informazione a $node, è il seguente:

La funzione è chiamata all'interno di node_load() mediante node_invoke_nodeapi($node,'load');
La funzione node_load() per ogni nodo letto chiama tutte le funzioni implametate in questo modo.

Visualizzazione

• Costruzione del contenuto
• Costruzione dei links del contenuto
• Rendering del contenuto
• Modifica globale del contenuto
• Tematizzazione del contenuto

Abbiamo visto che la funzione node_load() insieme ad altre funzioni di integrazione, genera l'oggetto $node con tutte le informazioni sul nodo e, tra queste, quelle sul corpo ($node->body) e sul sommario ($node->teaser). Drupal deve ora leggere queste informazioni,e prepararle alla visualizzazione finale. La fase di preparazione del contenuto usa quindi la funzione node_view($node, $teaser = FALSE, $page = FALSE, $links = TRUE). Il parametro $node è l'oggetto nodo; $teaser indica se visualizzare o meno il sommario; $page indica se visualizzare o meno l'intero contenuto del nodo; $links indica se visualizzare o meno i links associati al nodo.
Ma perchè è necessaria la fase di preparazione dei contenuti? Ci sono diversi motivi, ad esempio:

• Necessità di codificare le informazioni in codice HTML
• Eseguire codice PHP contenuto nei campi del nodo
• Verificare che non ci sia codice malevolo
• Consentire di tematizzare le informazioni del nodo
• Tradurre le informazioni
• Avviare eventi che avvisino la visualizzazione di quel nodo
• Applicare il tema corrente al nodo

In questa fase Drupal genera l'array $node->content[<campo>] che contiene tutti i contenuti del nodo, sia del campo body sia di tutti i campi aggiunti dai moduli esterni a quella tipologia di nodo.
Vediamo quindi quali sono i passi che portano alla definizione del contenuto da visualizzare.
Per fare questo di seguito è riportato integralmente il codice della funzione node_view()

La funzione comprende cinque fasi:
1.Costruzione del contenuto
Per prima cosa la funzione node_build_content (costruzione del contenuto) genera l'array $node[content].
2. Costruzione dei links del contenuto
Se richiesti i links nel contenuto, Drupal chiama tutte le funzioni dei moduli esterni che implementano la funzione nomemodulo_link($node,$teaser) e successivamente consente di modificare i links costruiti chiamando la funzione, se esistente, nomemodulo_tiponodo_alter(). Ad esempio avendo un tipo nodo rubrica e gestito dal modulo node, la funzione si chiamerà node_rubrica_alter().
3. Rendering del contenuto
Drupal esegue il rendering dei campi definiti in $node->content. Il risultato è una stringa che viene copiata in $node->body o $node_teaser in funzione dei valori passati in $page e $teaser.
4. Modifica globale del contenuto
Qui Drupal dà l'ultima possibilità di modificare le informazioni del nodo, contenuto e links inclusi, prima di applicare il tema corrente e di visualizzare il nodo.i
5. Tematizzazione del contenuto
Al termine il contenuto costruito viene tematizzato per la definitiva visualizzazione. Per un nodo generalmente è usato il template node.tpl.php.

Fase 1: costruzione del contenuto nell'array $node[content]

Avvia la costruzione del contenuto del nodo mediante la node_build_content($node, $teaser, $page);
Qui, la preparazione dell'array $node[content] può avvenire mediante due funzioni:
1. Una funzione personalizzata
2. La funzione standard node_prepare()

Funzione personalizzata

Drupal legge il tipo di nodo corrente ($node->type) e dalla tabella NODE_TYPE ricava il modulo che gestisce il tipo di nodo, che supponiamo abbia il nome nomemodulo.
Cerca quindi la funzione nomemodulo_view($node, $teaser, $page) e se esiste la chiama.
Nel caso il nodo sia gestito dal modulo "node" la funzione si dovrebbe chiamare node_view, ma poichè questa funzione è quella che stiamo descrivendo, solo per questo caso la costruzione del nome della funzione non segue la regola generale, ma si dovrà chiamare node_content_view() (che comunque non esiste).
La costruzione dell' array $node->content[] per tutti i campi del nodo è quindi totalmente affidata alla funzione personalizzata.

Funzione standard node_prepare($node, $teaser)

Se non è fornita la funzione personalizzata , Drupal chiama la sua funzione node_prepare()
Qui viene elaborato il contenuto del corpo (body) o del sommario (teaser) del nodo applicando i fitri impostati tramite la funzione check_markup(), di cui parleremo in altra parte. Inoltre imposta il flag $node->readmore= True/False in funzione del valore di $teaser/$page. Al termine è generato il primo pezzo dell'array node->content e precisamente:
node->content['body']['#value'] che contiene il valore del corpo o del sommario del nodo,
node->content['body']['#weight']=0 posizione del corpo del nodo in fase di visualizzazione.
Si pone ora il problema di generare il contenuto di tutti quei campi non standard del nodo, aggiunti eventualmente da altri moduli. Ad esempio se è stato generato un nuovo tipo di nodo usando il modulo CCK, il nodo conterrà campi aggiuntivi che devono essere gestiti dal modulo CCK. Per fare questo Drupal esegue tutte le funzione nomemodulo_nodeapi($node,'view', $teaser, $page).
Gli array node->content['nome campo'] che vengono creati possono avere strutture complesse e non omogenee.
Ad esempio per un campo CCK immagine la struttura che si ottiene è la seguente

$node[content][field_immagine]	Array [6]	
	field	Array [11]	
		#type		content_field	
		#title		immagine	
		#field_name	field_immagine	
		#access		true	
		#label_display	above	
		#node		stdClass	
		#teaser		1	
		#page		false	
		#context	teaser	
		#single		true	
		items	Array [1]	
			0	Array [7]	
				#item	Array [12]	
					fid	20	
					list	0	
					data	Array [0]	
					uid	3	
					filename	foto.jpg	
					filepath	sites/files/foto.jpg	
					filemime	image/jpeg	
					filesize	123453	
					status	1	
					timestamp	1265803634	
					nid	7	
					#delta	0	
				#weight	0	
				#theme		filefield_formatter_default	
				#field_name	field_immagine	
				#type_name	nuovotipo	
				#formatter	default	
				#node		stdClass	
	#weight	1	
	#post_render	Array [1]	
			0	content_field_wrapper_post_render	
	#field_name	field_immagine	
	#type_name	nuovotipo	
	#context	teaser

Fase 2:costruzione dei links del contenuto

All'oggetto $node sono associati i Links di navigazione del nodo che , generalmente, compaiono al termine del sommario di un nodo in prima pagina. Se presenti sono inseriti nell' array $node->links. Drupal consente di generare l'array $node->links chiamando due funzioni personalizzate:
- nomemodulo_link($type, $node, $teaser = FALSE)
Dove:
$type è il tipo di nodo (ad esempio 'node'),
$node l'oggetto in cui inserire l'array del link,
$teaser indica se il nodo è in prima pagina o meno.
La funzione è chiamata per tutti i moduli che la implementano. Ad esempio node_link(), comment_link() taxonomy_link() etc.
La funzione deve tornare un array contenente le componenti caratteristiche della funzione di costruzione del link: l().
Come esempio di implementazione riporto integralmente la funzione node_link().

Come si vede , Il valore di ritorno è l'array $links che sarà aggiunta agli array già definiti. L'oggetto nodo non deve quindi essere modificato all'interno della funzione.
- nomemodulo_link_alter(&$data)
Dopo che l'intero array dei link è stato costruito, Drupal da una ultima opportunità di modificarlo chiamando ancora per tutti i moduli le funzioni nomemodulo_link_alter() passando in &$data il riferimento il valore $node->links.

Fase 3:rendering del contenuto

Il rendering del contenuto (generazione del codice HTML definitivo) avviene mediante la funzione drupal_render(&$elements) chiamata ricorsivamente su tutti i campi del nodo. Il parametro $elements corrisponde all'array precedentemente generata $node->content[]. La funzione torna la stringa $content contenente tutto il contenuto del nodo pronto per essere visualizzato. Il contenuto è copiato in $node->body o in $node->teaser a seconda dei valori $teaser e $page passati alla funzione node_view(). In $node , la variabile in cui non è copiato il contenuto è eliminata da Drupal.
Al''interno della funzione drupal_render(), Drupal ci consente di modificare il contenuto sia prima di eseguire il rendering sia dopo averlo eseguito. Vediamo come.
- Personalizzazione mediante $node->content['#pre_render']
Prima di eseguire il rendering del contenuto, Drupal chiama tutte le funzioni eventualmente definite nell'array $node->content['#pre_render']. Le funzioni possono avere un qualsiasi nome e ad esse Drupal passa tutta l'array $node->content precedentemente generata.
- Personalizzazione mediante $node->content[<campo>]['#pre_render']
Il valore [#pre_render] può essere assegnato ad ogni campo (Es.: $content[body][#pre_render]) per chiamare una o più funzioni da eseguire per il particolare elemento. In questo caso è passato alla funzione il solo elemento $content[<campo>].
- Personalizzazione mediante $node->content['#post_render']
Dopo aver eseguito il rendering del contenuto, Drupal chiama tutte le funzioni eventualmente definite nell'array $node->content['#post_render']. Le funzioni possono avere un qualsiasi nome e ad esse Drupal passa la stringa $content contenente il rendering del contenuto e l'array $node->content.
- Personalizzazione mediante $node->content[<campo>]['#post_render']
Il valore [#post_render] può essere assegnato ad ogni campo (Es.: $content[body][#post_render]) per chiamare una o più funzioni da eseguire per il particolare elemento. Le funzioni possono avere un qualsiasi nome e ad esse Drupal passa la stringa $content contenente il rendering del contenuto e l'array $node->content[<campo>].
- Personalizzazione mediante ['#prefix'] e ['suffix']
Il rendering finale di ogni singolo elemento del contenuto viene sempre racchiuso tra i valori #prefix e #suffix forniti per quell'elemento come vediamo dal codice stesso della funzione drupal_render(&$elements)

Fase 4:modifica globale del contenuto

In questa fase, l'oggetto $node contiene il rendering del contenut , l'array dei links se presenti e quanto modificato o aggiunto dai moduli che implementano la funzione nomemodulo_nodeapi($node,'view', $teaser, $page).
Qui il nodo può essere ulteriormente modificato prima che sia applicato il tema corrente, implementando nei moduli la funzione nomemodulo_nodeapi($node,'alter', $teaser, $page).

Fase 5:tematizzazione del contenuto

Al nodo è applicata la tematizzazione mediante la funzionetheme('node', $node, $teaser, $page) . Generalmente per tematizzare un nodo viene usato il file template node.tpl.php. Di questo ne parleremo in altra parte.

Eventi

Drupal durante le operazioni di caricamento, inserimento, aggiornamento, cancellazione e visualizzazione dei nodi , consente allo sviluppatore di eseguire funzioni personalizzate per alterare la modalità operativa standard.
Indichiamo con:

• nomemodulo il nome di un modulo personallizzato che implementa le funzioni richieste.
• nomemodulotipo il nome del modulo che gestisce il tipo di nodo, letto dalla tabella NODE_TYPE nel campo module. Nel caso che il tipo sia node, nomemodulotipo sarà uguale a node_content, e i nomi di funzione dovranno essere quindi node_content_load, node_content_view, node_content_save, questo perchè le funzioni node_load, node_view, node_save etc. sono funzioni standard di Drupal.
• nometipo il nome del tipo di nodo.

Per ogni tipo di operazione, la sequenza con cui sono descritte le funzioni coincide con quella di esecuzione.
Di seguito riportiamo le funzioni che , se esistenti, sono chiamate da Drupal nei diversi contesti.

Caricamento

nomemodulotipo_load(&$node,$page,$teaser)

Implementata nel modulo che gestisce il tipo di nodo, consente di caricare dei campi aggiuntivi all'oggetto nodo.

nomemodulo _nodeapi($node,$op='load')

Consente a ogni modulo che la implementa di aggiungere ulteriori campi all'oggetto nodo non definiti nella tabella NODE.

Visualizzazione

nomemodulotipo_view($node,$page,$teaser)

Implementata nel modulo che gestisce il tipo di nodo, se presente sosituisce la funzione node_prepare() che è responsabile della generazione dell'array $node->[content].

nomemodulo _nodeapi(&$node,$op='view')

Consente a ogni modulo che la implementa di preparare alla visualizzazione i campi aggiunti al nodo.

nomemodulo_link($type, $node, $teaser = FALSE)

$type è il tipo di nodo (ad esempio 'node'),
Consente a ogni modulo che la implementa di aggiungere links da visualizzare nel nodo corrente.

nomemodulo_link_alter(&$node->links)

Consente a ogni modulo che la implementa di modificare l'intero array dei links da visualizzare nel nodo corrente.

nomemodulo_nodeapi($node,'alter', $teaser, $page)

Consente a ogni modulo che la implementa di modificare l'intero oggetto $node prima che il nodo sia passato alla funzione theme('node', $node).

Theme System

QUESTA SEZIONE E' IN LAVORAZIONE
----------------------------------------------

Quando Drupal deve generare il codice HTML per elementi come nodi, blocchi , menu, breadcrumb, links e altro, cerca, per il tema corrente, le funzioni e file teplate che consentono di codificare gli elementi richiesti.
La ricerca avviene applicando regole sulla priorità di ricerca, sui nomi e sulla posizione delle funzioni e dei file all'interno delle directory e dei moduli che consentono a Drupal di ottenere una elevata personalizzazione del sistema.
Conoscendo e seguendo le regole di ricerca è possibile personalizzare un sito generando nuove funzioni e file template in base alle proprie esigenze.

Convenzioni su nomi e file

Nome del tema

Il nome del tema deve essere diverso dal nome di qualsiasi modulo

Directory del tema

Tutti i file appartenenti alla definizione di un tema , devono stare all’interno di una propria subdirectory che prende il nome del tema. La subdirecotory può essere contenuta all'interno di una delle seguente directory:

• miosito/themes/miotema
• miosito/sites/all/....../miotema

Il motore di elaborazione del tema controllerà , per il tema selezionato, la presenza di file template con estensione .tpl.php.

Il file screenshot del tema

Il file deve essere in formato .png di dimensioni 150x90.
Se presente viene mostrato nella pagina di amministrazione dei temi.

I file di stile CSS

Il file di stile del tema

Il tema utilizza come dichiaratore di stile il file style.css per default.
Altri file possono essere caricati utilizzando l'istruzione @import dei file css.

Temi multipli con più file di stile

E’ possibile creare temi che differiscono per il solo file di definizione degli stili css:style.css.
Per fare questo bisogna creare nella directory di base del tema, delle subdirectory contenenti i file style.css. Ogni subdirectory costituirà un nuovo tema. Ad Esempio:

miosito/sites/all/themes/miotema_A/ (directory principale del tema)

• template.tpl.php file di template comuni
• page.tpl.php file di template comuni
• ...
• style.css
• miotema_B/style.css
• miotema_C/style.css

Il motore riconoscerà tre temi: miotema_A, miotema_B, miotema_C.
Ciascun tema utilizzerà i file di base con estensione .tpl.php, e ciascuno avrà nella propria subdirectory il file di stile style.css.

La suddivisione in Regioni

Gli argomenti trattati fanno riferimento alla versione 5.x di Drupal

Funzioni principali:
phptemplate_regions()
drupal_set_content($region=NULL,$data=NULL)

I temi possono definire ed implementare un numero generico di regioni.
Le regioni sono essenzialmente contenitori di... contenuti.
Le regioni suddividono la pagina del browser in aree che costituiranno i limiti in cui visualizzare i contenuti stessi. Così, generalmente, tutti i temi hanno una regione per:

• i contenuti dell’intestazione, header
• due regioni per i contenuti dei menu laterali, sidebar-left e sidebar-right
• una regione per i contenuti del fondo pagina, footer
• una regione centrale, content

ed altre regioni che possono complicare notevolmente il layout del sito.

Definizione delle regioni

Le regioni sono definite mediante una funzione php che torna un array associativo contenente la codifica delle regioni e la loro descrizione utilizzata nella pagina di amministrazione dei blocchi.
La funzione è la seguente:

function phptemplate_regions() {
  return array(
       'left' => t('left sidebar'),
       'right' => t('right sidebar'),
       'content' => t('content'),
       'header' => t('header'),
       'footer' => t('footer')
  );
}

Il primo nome della regione diventa la regione di default per il posizionamento di blocchi nel caso in cui non sia dichiarata espressamente una regione.

Nel caso di PhpTemplate Engine la funzione phptemplate_regions() è contenuta nel file: miosito/themes/engines/phptemplate/phptemplate.engine.
Drupal prima di chiamare questa funzione , verifica se esiste una funzione analoga fornita nei file template del tema corrente e che si chiami miotema_regions().
Per cui, per personalizzare le regioni di un tema, bisogna definire la funzione miotema_regions() nel file template.php nella directory del tema.

function miotema_regions() {
  return array(
       'regione1' => t('regione1'),
       'regione2' => t('regione2'),
       'regione3' => t('regione3'),
       'header' => t('header'),
       'footer' => t('footer')
  );

Nel caso di .theme Engine la funzione è contenuta nel file del tema miotema.theme

Per riempire una regione è possibile utilizzare la funzione

function drupal_set_content($region = NULL, $data = NULL) {
  static $content = array();
  if (!is_null($region) && !is_null($data)) {
    $content[$region][] = $data;
  }
  return $content;
}

Es.: drupal_set_content('left', 'Hello there.')

phptemplate engine

Gli argomenti trattati fanno riferimento alla versione 5.x di Drupal

Il motore phptemplate è contenuto nella direcotory themes/engines/phptemplate ed è costituito dai seguenti file:

1) phptemplate.engine contenente le funzioni di default per la gestione di blocchi, box. commenti, nodi
2) default.tpl.php non è ancora chiaro l'uso
3) node.tpl.php per la stampa dell’oggetto nodo
4) block.tpl.php per la stampa dell’oggetto blocco
5) box.tpl.php per la stampa dell’oggetto box
6) comment.tpl.php per la stampa dell’oggetto commento

Questi sono alcuni dei file necessari per la gestione di un tema di default. Ma per la realizzazione del tema sono necessari altri due file,fondamentali, contenuti obbligatoriamente nella subdirectory del tema selezionato:

page.tpl.php è il file principale del tema che definisce il layout del tema.
style.css contiene la definizione degli stili del tema.

Ogni tema può quindi utilizzare, i due file page.tpl.php e style.css pi ù i cinque file di default .tpl.php contenuti in themes/engines/phptemplate oppure una loro implementazione personalizzata. In questo caso i file si dovranno chiamare allo stesso modo , ma dovranno trovarsi nella subdirectory del tema.

Aggiungere un tema

Per aggiungere un nuovo tema, si deve quindi:

creare una nuova directory con il nome del tema in /sites/all/themes/miotema oppure /themes/miotema

• copiare nella directory i file *.tpl.php
• scrivere un nuovo file page.tpl.php per la definizione del layout del tema
• scrivere un nuovo file style.css per la definizione degli stili del tema

La cosa più semplice, comunque, è prendere i file di un tema esistente, magari di quelli di default (bluemarine), copiarli nella nuova directory e cominciare a modificarli secondo le proprie esigenze.

<p>questo è un blocco </p>
 oppure
<?php  print “questo è un blocco”; ?>

 
<?php 
 $block = module_invoke('block', 'block', 'view', 1); 
 print $block['content'];
 ?> 

La funzione theme()

E' sconsigliato inserire direttamente codice HTML in Drupal, sebbene sia permesso dai formati di input (FilteredHTML,FullHTML). Drupal mette a disposizione delle funzioni proprio per produrre codice HTML personalizzabili all'interno di ciascun tema.

Le funzioni che producono codice HTML, devono però poter funzionare per qualunque tema selezionato. Ad esempio volendo stampare una tabella si può usare la funzione theme_table() o volendo stampare un blocco si può usare la funzione theme_block(). Tutte le funzioni tematizzate di sistema si trovano nel file includes/theme.inc. Ma se, ad esempio, un tema deve visualizzare l’oggetto ‘blocco’ in un modo particolare può essere implementata la funzione theme_block(), chiamandola miotema_block(), ed inserendola nel file template.tpl.php.

A questo punto è necessario che Drupal sia in grado di sapere che esiste una funzione personalizzata ed usare quella invece della funzione di default. Prendondo come esempio la funzione theme_table(), Drupal, nel momento in cui deve chiamare la funzione, verifica, con le priorità indicate, se:

Il tema implementa la funzione

Verifica se la funzione theme_table() è implementata nel tema corrente.
La funzione implementata:

• si deve chiamare: miotema_table()
• può stare nel file template.php o in un file .tpl.php del tema

Il motore di template implementa la funzione

Se il tema non implementa la funziona, Drupal verifica se la funzione theme_table() &egrave implementata dal motore di template del tema corrente.
La funzione implementata:

• si deve chiamare phptemplate_table()
• può stare:
• nel file che implementa il motore (es.: phptemplate.engine)
• nei file .php o .tpl.php del tema (es.: template.php, block.tpl.php)

Il sistema implementa la funzione

Se il motore non implementa la funziona, Drupal chiama la funzione theme_table() implementata da sistema.

La funzione implementata:

• starà nel file includes/theme.inc

Un help delle funzioni di sistema tematizzate può essere trovato in http://api.drupal.org/api/group/themeable/5?sort=asc&order=Name

La funzione theme()

Quando abbiamo bisogno di chiamare una funzione tematizzata, è bene non chiamare la funzione direttamente, ma lasciare che sia Drupal a fare questo per noi tramite la funzione theme('block',args). Infatti supponiamo di voler visualizzare una tabella all'interno di codice php scritto da noi, la chiamata alla funzione giusta potrebbe essere del tipo:

  function miafunzione() {
  ......
     // stampa tabella
     if (isset('miotema_table') miotema_table(.....);
     elseif (isset('phptemplate_table') phptemplate_table(.....);
     else theme_table();
     ......
  }

Tutto questo può essere semplificato utilizzando la funzione theme() e delegare a Drupal la scelta della funzione corretta:

  function miafunzione() {
  ......
     // stampa tabella
     theme('table',$args);
     ......
  }

Il theme registry

Abbiamo visto come l'applicazione di un tema agli elementi del sito , venga eseguito da Drupal mediante funzioni come theme_breadcrumb($breadcrumb), theme_links($links, $attributes) o mediante file template come page.tpl.php, node.tpl.php, block.tpl.php. Per tenere traccia di queste e delle altre informazioni necessarie per applicare correttamente un tema agli elementi del sito, Drupal genera il cosiddetto theme registry. Fisicamente il tema registry è costituito da un'array associativa , indicata in seguito come $hooks, contenente tutti i nomi dei possibili hooks (breadcrumb,links,block,node,page) e, per ciascuno di essi, le corrette informazioni per gestire quella tipologia di elemento.L'array generato è salvato nel database. L'individuazione della funzione o del file template da utilizzare avviene passando sempre attraverso la funzione che è alla base della tematizzazione di Drupal: theme($hook,$args). Il parametro $hook indica a quale elemento applicare il tema. Ad esempio theme('breadcrumb',$args) per il breadcrumb, theme('links',$args) per i links del nodo, theme('node',$args) per un nodo, theme('page', $args) per la pagina finale.
Il valore $args indica qui semplicemente il passaggio di uno o più argomenti alla funzione theme().
Infatti come si vede dal frammento di codice della funzione theme

i parametri non sono passati esplicitamente , ma sono letti mediante la funzione func_get_args().
In questo modo possono essere passati un numero di argomenti indefinito che la funzione theme() passerà alla funzione o al file template che effettivamente si occuperà di tematizzare l'elemento.
Il primo parametro è sempre il valore hook che viene estratto dall'array $args.
Dopo aver letto gli argomenti e individuato l'hook, Drupal carica l'array $hooks dal database. La lettura dell'array è eseguita la prima volta che viene chiamata la funzione theme() mediante la funzione theme_get_registry(). Successive chiamate di theme() troveranno l'array $hooks carico in quanto definito come variabile 'static'.

Da dove è letto il theme registry?
Il theme registry è generato ogni volta che si entra nella pagina contenente la lista dei moduli. Dopo averlo generato Drupal salva l'array nel database e precisamente nella tabella CACHE.
In questa tabella, ogni tema ha un suo theme registry salvato nel campo DATA , e individuato dal record con il campo CID uguale a "theme_registry:NomeTema", dove NomeTema è ovviamente il nome del tema. Volendo quindi forzare la rigenerazione del theme registry basterà semplicemente cancellare il record associato al tema.

L'array $hooks
L'array $hooks è un array associativo nella forma $hooks['hook'][propietàX] = valore , dove valore può essere anche un array o un oggetto. Poco più avanti nel frammento di codice, Drupal per comodità, carica in $info le sole informazioni relative all'hook corrente:$hooks[$hook].

Costruzione del theme registry

Come viene costruita l'array $hooks? Da dove Drupal prende le informazioni in essa contenute?
Vediamo in dettaglio la costruzione dell'array, supponendo di voler generare il theme registry per il tema Minnelli derivato dal tema Garland e gestito dal motore phptemplate.
Entrando in theme(), Drupal verifica l'esistenza della variabile statica $hooks e se non ancora impostata,
avvia l'inizializzazione del tema corrente tramite la init_theme().
Il tema corrente è definito o in $user->theme o , se nullo, con il tema di default letto con la funzione variable_get('theme_default', 'garland').
Tra le operazione attivate durante l'inizializzazione del tema, quella che a noi qui interessa è la creazione del theme registry. Per leggere gli hooks, Drupal usa la funzione _theme_load_registry() definita in theme.inc, che verifica l'esistenza del theme registry nella tabella CACHE e in caso affermativo riporta l'array contenuto nel campo DATA, altrimenti avvia la sua costruzione.
Nel secondo caso, Drupal dovrà quindi individuare tutti gli hooks e le loro proprietà definiti all'interno del sistema.
La costruzione del theme registry avviene in due fasi:
a) Individuazione di tutti gli hooks definiti nel sistema;
b) Modifica dei parametri degli hooks letti mediante ricerca di funzioni e/o file template personalizzate.

Ricerca degli hook definiti nel sistema

La funzione che avvia la costruzione del theme registry è la funzione _theme_build_registry($theme, $base_theme, $theme_engine) in cui i parametri indicano il nome del tema, il tema base di riferimento (nullo se il tema è già un tema base) , il nome del motore di gestione del tema, nel nostro caso phptemplate.
Gli hooks appartenenti al theme registry sono definiti all'interno dei moduli.
Ogni modulo che vuole esporre i propri hooks deve implementare la funzione nomemodulo_theme() che deve fornire un'array contenente nomi e proprietà degli hooks da esporre.
Ad esempio il modulo di gestione dei blocchi, implementa la funzione block_theme():

che espone il solo hook "block_admin_display_form" e indicando che deve essere gestito tramite file template. Dove starà il file template? Se non altrimenti definito Drupal si aspetta di trovarlo nel percorso del modulo. Altri esempi è possibile vederli in node_theme() nel modulo node.module, in comment_theme() nel modulo comment.module etc. Per individuare tutti gli hooks dei moduli Drupal esegue un ciclo su tutti i moduli attivi chiamando per ogni modulo la funzione: _theme_process_registry(&$cache, $name, $type, $theme, $path)
dove:

• $cache è l'array degli hooks che si sta generando a cui accodare eventuali altri hooks
• $name è il nome del modulo in cui cercare gli hooks
• $type ='module' indica a Drupal che è in corso una ricerca in un modulo
• $theme nonostante il nome fuorviante, in questo caso ripete il nome del modulo
• $path indica la directory del modulo

La funzione _theme_process_registry legge l'array restituito dalla funzione nomemodulo_theme() e aggiunge al theme registry gli hook in essa definiti.
Di seguito indichiamo con $info[] l'array restituito dalla funzione nomemodulo_theme() per un singolo hook.
Per l'esempio precedente si avrebbe:
$info[template]= 'block-admin-display-form'
$info[file]= 'block.admin.inc
$info[arguments]=array('form' => NULL)
e con $hook[] le proprietà generate nel theme registry per l'hook letto, ad esempio per block_admin_display_form .
Ad ogni hooks Drupal assegna le seguenti proprietà:

$hook[type]
Valore sempre presente, definito da codice.
Indica dove l'hook è stato definito. Per i moduli è uguale a 'module'

$hook[theme path]
Indica il percorso del modulo. $hook[theme path]=$path (passato come argomento)

$hook[arguments]
Array.Indica il nome e il valore di default degli argomenti da fornire alla funzione o al file template.
E' il valore $info[arguments]

$hook[function]
Indica il nome della funzione di gestione dell'hook.
Se un modulo non definisce ne la proprietà "template" ne la proprietà "function" Drupal imposta
$hook[function]=theme_hook() come nome della funzione che dovrà gestire l'hook. Naturalmente la funzione theme_hook() deve essere implementata nel modulo.

$hook[file]
Se è impostata la proprietà $info[file] , significa che le funzioni di tematizzazione dell'hook sono definite nel file indicato, ad esempio nomemodulo.inc. La corrispondente proprietà dell'hook sarà:
$hook[file]=$path .'/'. $info['file'] con $path percorso del modulo.
E' possibile mettere le funzioni di gestione anche in file esterni alle directory del modulo , impostando la proprietà $info[path]. In questo caso il valore $hook[file] non viene impostato, ma è caricato immediatamente il file
$info['path'] .'/'. $info['file'] per individuare nelle successive fasi eventuali funzioni di tematizzazione.

$hook[template]
Solo se non definita la proprietà $info[function]
Indica il nome e percorso del file template.
Per default il file template viene definito nel percorso del modulo:
$hook[template] = $path ."\" . $info[template];

$hook[theme paths]
Array.Indica un array di directory in cui cercare eventuali implementazioni per il tema.
Per i moduli è aggiunto o la directory del modulo o la proprietà $info[path] se definita.

$hook[preprocess functions]
Array.Indica un array di funzioni di preprocessing da usare in caso di gestione con file template.
Se è definita l'array $info[preprocess functions] allora sarà $hook[preprocess functions]=$info[preprocess] altrimenti Drupal genera l'array $info[preprocess] avviando la ricerca in tutti i moduli delle seguenti funzioni:

• nomenodulo_preprocess
• nomenodulo_preprocess_hook

e aggiungendo sempre la funzione template_preprocess definita in theme.inc e, se esistente, la funzione template_preprocess_hook
Al termine della ricerca sarà: $hook[preprocess functions]=$info[preprocess].
Terminato di impostare le proprietà di tutti gli hooks appartenenti al modulo, la funzione _theme_preprocess_registry aggiiungerà gli hooks inidividuati nel modulo corrente all'array generale degli hooks $cache.

Ricerca di funzioni e template personalizzati

Nella fase precedente, Drupal ha individuato tutti gli hook definiti nei moduli tramite le funzioni nomemodulo_theme(). Chi sviluppa un modulo deve fornire anche le funzioni o i file template associati agli hooks esposti in nomemodulo_theme(). Drupal consente però di eseguire un "override" delle funzioni e file template fornite mediante la ricerca di funzioni e template alternativi.
Per ogni hook definito Drupal cerca l'esistenza delle seguenti funzioni in ordine di priorità

- nometema_hook()
- nometemabase_hook()
- engine_hook()

e quindi continuando a suppore minnelli come tema corrente, garland come tema base e phptemplate come motore per i temi , Drupal cercherà le seguenti funzioni:

- minnelli_hook()
- garland_hook()
- phptemplate_hook()

Per i file template chercherà i seguenti file:

- hook.tpl.php nella directory del tema corrente (minnelli)
- hook.tpl.php nella directory del tema base (garland)

Per ogni funzione trovata Drupal imposta:
$hook['function]=<nuovo_nome_funzione>

Per ogni template trovato Drupal imposta:
$hook['template]=<file template>
$hook['path]=<directory del tema>

Infine Drupal modifica anche le seguenti proprietà:

$hook[type]
Il valore è posto uguale a 'base_theme_engine' se la ricerca avviene all'interno della directory
del tema base. E' posto uguale a 'theme_engine' se la ricerca avviene all'interno della directory
del tema corrente.

$hook[theme path]
Indica il percorso del tema.

$hook[theme paths]
Oltre ai paths già individuati, aggiunge il path del tema:
$hook[theme paths][]=$path

$hook[preprocess functions]
Drupal aggiorna la proprietà cercando le seguenti funzioni di preprocessing:

- phptemplate_engine_preprocess
- phptemplate_engine_preprocess_hook
- phptemplate_preprocess
- phptemplate_preprocess_hook
- nometemabase_preprocess
- nometemabase_preprocess_hook
- nometema_preprocess
- nometema_preprocess_hook

Ulteriore modifica mediante drupal_alter()

L'ultima possibilità di modificare il theme registry è data da Drupal mediante la funzione drupal_alter('theme_registry', $cache).
Questa funzione ricerca e chiama tutte le funzioni nomemodulo_themaregistry_alter($hooks) che possono quindi modificare ulteriormente le informazioni fornite precedentemente. Ad esempio un modulo che implementa funzioni tipo theme_hook() potrebbe utilizzare funzioni differenti in base al contesto in cui si trova.

Le funzioni usate

Riepiloghiamo di seguito le principali funzioni utillizzate per la generazione del theme registry.

_theme_build_registry($theme, $base_theme, $theme_engine)
dove:
$theme è il nome del tema
$base_theme è il tema base di riferimento (nullo se il tema è già un tema base)
$theme_engine è il nome del motore di gestione del tema, nel nostro caso phptemplate.
Contenuta in includes/theme.inc
Questa funzione avvia il processo di costruzione del theme registry.

_theme_process_registry(&$cache, $name, $type, $theme, $path)
dove:
$cache è l'array degli hooks che si sta generando a cui accodare eventuali altri hooks
$name è il nome del modulo o del tema in cui cercare gli hooks
$type = indica il tipo di ricerca che si sta eseguendo. Assume i valori: module, base_theme_engine, base_theme, theme_engine, theme.
$theme nome del modulo o del tema
$path indica la directory del modulo
Definita in includes/theme.inc
E' chiamata cinque volte all'interno della funzione _theme_build_registry(), una per ogni tipologia di ricerca.

1) $type= module
$name e $theme corrispondono al nome del modulo
Ricerca delle definizioni degli hooks nei moduli.
Per eseguire la ricerca chiama le funzioni nomemodulo_theme()

2) $type= base_theme_engine
$name=motore del tema , nel nostro caso: phptemplate
$theme=nome del tema base su cui eseguire la ricerca (garland ad esempio)
$path=percorso del tema
Ricerca le funzioni personalizzate con nome phptemplate_hook() e nometemabase_hook()
Ricerca i template personalizzati nella directory del tema base (garland)
Per eseguire la ricerca chiama la funzione phptemplate_theme() definita in themes/engines/phptemplate

3) $type= base_theme
$name e $theme corrispondono al nome del tema base
$path=percorso del tema base
Per eseguire la ricerca chiama, se esiste, la funzione nometemabase_theme().
Questa funzione non è implementata in Drupal..

4) $type=theme_engine
$name=motore del tema , nel nostro caso: phptemplate
$theme=mode le tema su cui eseguire la ricerca (minnelli ad esempio)
$path=percorso del tema
Ricerca le funzioni personalizzate con nome phptemplate_hook() e nometema_hook()
Ricerca i template personalizzati nella directory del tema (minnelli)
Per eseguire la ricerca chiama la funzione phptemplate_theme() definita in themes/engines/phptemplate

5) $type=theme
$name e $theme corrispondono al nome del tema base
$path=percorso del tema
Per eseguire la ricerca chiama, se esiste, la funzione nometema_theme().
Questa funzione non è implementata in Drupal.

phptemplate_theme($existing, $type, $theme, $path)
dove:
$existing è l'array degli hooks definiti nel sistema
$type uguale a 'base_theme_engine' (ricerca per tema base ) o 'theme_engine' (ricerca per tema derivato)'
$theme è il nome del tema per cui cercare funzioni o template personalizzati
$path è il percorso del tema
Definita in themes/engines/phptemplate/pgptemplate.engine
Praticamente è la funzione che ricerca tutte le funzioni e i file template personalizzati, consentendo allo sviluppatore di eseguire l'override delle funzioni e template di default..

Tipologia dei moduli

Un modulo può essere di tipo:

Block module

Sono moduli che generalmente vengono posizionati sulle barre laterali. Drupal chiama la funzione miomodulo_block($op=='view') con opzione uguale a view per ottenere il contenuto del blocco. In particolare Drupal si aspetta un array $block di ritorno con i seguenti valori impostati:

$block['subject'] = t('MioModulo');
$block['content'] = contenuto del blocco;

Node module

Sono moduli che generalmente generano pagine di contenuto come blog, forum, book pages.

Le funzioni minime che è bene definire per un modulo sono:

• miomodulo_block()
• miomodulo_help()
• miomodulo_perm()

Hook principali

IN FASE DI REALIZZAZIONE

Elenco degli hook principali

Accesso ai moduli:permessi

Premesso che , l’accesso ad un modulo viene impostato tramite la pagina Gestione utenti->Controlli accessi.

In questa pagina compaiono per ogni modulo i permessi associati ad esso e per ogni permesso a quale ruolo è assegnato il permesso.
I ruoli per default sono due: anonymous user e authenticated user.
E’ possibile aggiungere altri ruoli utilizzando la pagina Gestione utenti->Ruoli.
Detto questo, le descrizione dei permessi che compaiono nella pagina Gestione utenti->Controlli accessi sono definite mediante la funzione:

Qui sopra sono riportati solo due permessi, ma ovviamente ne potrebbero essere definiti altri. E' bene inserire sempre il nome nel modulo per ogni permesso. In caso contrario Drupal potrebbe assegnare la stringa di permesso a più moduli, creando seri problemi all'impianto di sicurezza.

Per verificare se l’utente corrente ha determinati permessi usare la funzione user_access()

Versioni precedenti alla 5.0 di Drupal usavano la funzione message_access() ora deprecata.

Messaggi di configurazione del modulo

Pagina dei moduli
Nella pagina dei moduli le descrizioni associate al modulo provengono dal file miomodulo.info contenuto nella directory del modulo. All’interno del file sono contenute almeno le prime due variabili:

$Id$
name = miomodulo
description = "Descrizione MioModulo"
dependencies = modulo1 modulo2 modulo3
package = MieModuli

con i seguenti significati

• name Nome del modulo
• description Descrizione del modulo
• dependencies Indica i moduli da cui il modulo stesso dipende. Drupal non attiverà il modulo finchè non saranno attivi i moduli da cui dipende
• package Pakage di appartenenza del modulo.Tutti i moduli appartenenti allo stesso package sono mostrati raggruppati nella pagina dei moduli

Pagina dei blocchi
Nome del blocco nella lista blocchi

Funzione miomodulo_block($op=’list’)

Esempio:

* Descrizione dell'help all’interno della configurazione del blocco

Funzione miomodulo_help($section = "")

Come definito al paragrafo Accesso ai moduli:permessi, i permessi di accesso ai moduli sono definiti mediante la funzione miomodulo_perm()

Il valore di $section deve essere verificato posizionando il cursore sul link ‘configura’ della pagina dei blocchi e vedere a quale percorso punta. Generalmente è admin/build/block/configure/MioBlocco/0 e quindi scrivere la funzione miomodulo_help() nel seguente modo:

Pagina del controllo accessi utenti
Come definito al paragrafo Accesso ai moduli:permessi, i permessi di accesso ai moduli sono definiti mediante la funzione miomodulo_perm()

Style sheet

Quando un modulo ha fogli di stile propri, questi devono essere caricati prima di visualizzare il contenuto della pagina generata dal modulo. Nella pagina HTML generata da Drupal i file di stile compaiono secondo la sequenza:

stile/i del modulo corrente
stile/i del modulo corrente contenuti nel tema corrente
stili di default di Drupal
stili del tema corrente

come di seguito indicato.

<style type="text/css" media="all">@import "/sites/all/modules/miomodulo/miomodulo.css"</style>
<style type="text/css" media="all">@import "/sites/all/themes/miotema/miomodulo.css"</style>

<style type="text/css" media="all">@import "/modules/book/book.css"</style>
<style type="text/css" media="all">@import "/modules/node/node.css"</style>
<style type="text/css" media="all">@import "/modules/system/defaults.css"</style>
<style type="text/css" media="all">@import "/modules/system/system.css"</style>
<style type="text/css" media="all">@import "/modules/user/user.css"</style>
...
<style type="text/css" media="all">@import"/sites/all/themes/miotema/style.css"</style>

Per fare questo è utilizzata la funzione drupal_add_css() secondo il codice riportato.
L'esempio riporta il codice necessario per caricare il foglio di stile miomodulo.css.
Questo codice deve essere chiamato dalle funzioni del modulo che preparano codice HTML.

function miomodulo_css_file() {
       $css_files = array();    // array in cui definire i file css
        // Definisce i percorsi dei file di stile
       $file_css_modulo          = drupal_get_path('module', 'miomodulo') . '/miomodulo.css';
       $file_css_modulo_in tema  = path_to_theme() .  '/miomodulo.css'; // se esistente
       // Definisce nell'array lo stile di default del modulo 
       $css_files[] = array('file' => $file_css_modulo, 'type' => 'module', );
        /* 
       Definisce nell'array lo stile ripetuto nella directory del tema corrente
       Se esiste un file di stile nella directory del tema corrente
       con lo stesso nome dello stile del modulo lo carica. 
       */
       if (file_exists($file_css_modulo_in tema) {
           $css_files[] = array('file' => $file_css_modulo_in tema, 'type' => 'theme', );
       }
       // Avvisa Drupal di caricare i fogli definiti
       foreach ($css_files as $css_file)
       {
           drupal_add_css($css_file['file'], $css_file['type'], 'all', false);
       }
}