CGI Corner

Server Side Include

I Server Side Include sono comodi, relativamente semplici da implementare e di notevole effetto soprattutto sull'utente "profano" ;-). Quindi, vediamo come si usano!

di Michele Beltrame

Server Side Include

Con i Server Side Include (SSI) è possibile realizzare, spesso anche senza scrivere una riga di codice che non sia HTML, pagine dinamiche, cioé pagine i cui contenuti variano in base al momento, all'utente, al browser, o ad altri parametri. A titolo di esempio cito i contatori di accesso, che sono senz'altro l'applicazione più diffusa della tecnologia SSI.

Altre possibili applicazioni sono ad esempio la realizzazione di statistiche sui file presenti sul server, oppure la visualizzazione e l'utilizzo di alcuni dati che vengono forniti al server dal browser.

Ma come funzionano?

<--#comando parametro="valore"-->

Non devono essere presenti spazi tra le parentesi angolari, i trattini ed il cancelletto.

Il server, prima di inviare un documento al client, lo processa e sostituisce tutti i tag SSI con il con ciò che viene da essi richiesto. Un tag SSI potrebbe venire sostituito dal valore di una variabile d'ambiente del server, dall'output di un programma residente sul server, da un file di testo, ...

Della configurazione del server per il supporto degli SSI si è già parlato in CGI Corner di Beta n. 9. È bene tuttavia ricordarsi che il server è generalmente configurato per scandire alla ricerca di tag SSI solo i documenti con estensione .shtml (Server-parsed HTML). Affiché siano processati anche i file con estensione .htm e .html configurate opportunamente il server oppure contattate il vostro webmaster. Tuttavia ricordate che far processare al server tutti i documenti potrebbe causare qualche rallentamento nel loro caricamento.

Le direttive SSI

Vediamo anzitutto i parametri accettati dalla direttiva config, che serve per modificare alcuni aspetti della configurazione dell'interfaccia SSI.

Parametro	Descrizione
errmsg	Permette di personalizzare il messaggio d'errore
sizefmt	Modifica il formato di visualizzazione della dimensione dei file
timefmt	Modifica il formato di visualizzazione della data

La direttiva echo visualizza il valore di una variabile d'ambiente o di una variabile speciale SSI (che è comunque una variabile d'ambiente).

Parametro	Descrizione
var	Inserisce nel documento il valore della variabile d'ambiente specificata

La direttiva include permette l'inserimento di un file di testo nel documento corrente.

Parametro	Descrizione
pathname	Path relativo alla directory corrente sul server
virtual	Path virtuale (root = documentroot)

La direttiva fsize inserisce nel documento HTML la dimensione di un file.

Parametro	Descrizione
file	Path relativo alla directory corrente sul server

Infine, la direttiva flastmod inserisce la data e l'ora dell'ultima modifica ad un file.

Parametro	Descrizione
file	Path relativo alla directory corrente sul server

Gli insanguinati dettagli

Con:

<--#config errmsg="messaggio d'errore"-->

è possibile scegliere un messaggio d'errore in sostituzione di quello standard che, almeno per quanto riguarda Apache, è :

[an error occurred while processing this directive]

Questa direttiva va collocata prima di tutte le altre nel documento HTML, in quanto ha effetto solo sulle direttive che la seguono.

La direttiva

<--#config timefmt="%1 %2 %..."-->

permette di cambiare il formato con cui data ed ora vengono visualizzate. La direttiva va posizionata prima di un tag SSI che richieda al server una data o un'ora (come ad esempio flastmod).

I possibili valori di %1, %2, %... (i parametri possono essere un numero indefinito) sono i seguenti, che, altro non sono che i parametri che vengono passati alla funzione Unix size_t strftime(char *s, size_t max, const char *format) (time.h) :

Valore	Descrizione
%a	Scrive il giorno della settimana abbreviato (Sun, Mon, ...)
%A	Scrive il giorno della settimana in forma estesa (Wednesday, ...)
%b o %h	Scrive il nome del mese abbreviato (Jan, Feb, ...)
%B	Scrive il nome del mese in forma estesa (April, ...)
%d	Scrive il giorno del mese senza lo 0 davanti (1->31)
%D	Scrive la data nel formato "%m/%d/%y"
%e	Scrive il giorno del mese con lo 0 davanti (01, 02, 15, ...)
%H	Scrive l'ora secondo il formato a 24 ore (0->23)
%I	Scrive l'ora secondo il formato a 12 ore (0->12)
%j	Scrive il giorno dell'anno (1->366)
%m	Scrive il numero del mese
%M	Scrive il numero di minuti
%p	Scrive "a.m." o "p.m" a seconda che sia mattina o pomeriggio
%r	Scrive l'ora nel formato "%I:%M:%S %p"
%S	Scrive il numero di secondi
%T	Scrive l'ora nel formato "%H:%M:%S"
%U o %W	Scrive il numero della settimana (1->52)
%w	Scrive il numero del giorno della settimana (01->07)
%y	Scrive l'anno omettendo il secolo (01->99)
%Y	Scrive l'anno (1997, ...)
%Z	Scrive la time zone (MET per l'Italia)

L'ultima opzione configurabile è il formato con cui viene visualizzata la dimensione di un file (tramite la direttiva fsize) :

<--#config sizemft="formato"-->

I possibili formati sono bytes perché la dimensione venga visualizzata in byte o abbrev perché essa venga visualizzata in megabyte o kilobye (arrotondati).

Vediamo ora il funzionamento della direttiva fsize: essa stampa la dimensione di un file seguendo il formato specificato in sizefmt. Vediamo un esempio :

<--#fsize file="/cgi-bin/prova.pl"-->

Questo tag visualizza la dimensione del file prova.pl che si trova nella directory cgi-bin (path relativo alla documentroot).

La direttiva flastmod visualizza invece la data dell'ultima modifica ad un determinato file. Anche qui il path è relativo alla documentroot. Il seguente codice HTML :

<--#config timefmt="%T %D"-->
<--#flastmod file="/cgi-bin/prova.pl"-->

verrebbe sostituito dal server con qualcosa tipo :

21:45:12 03/1/96

Passiamo ora alla direttiva include, che permette l'inclusione di file di testo nel documento HTML corrente. Sono ammessi due tipi di parametro per specificare il path: file e virtual. Il primo si riferisce unicamente alla directory corrente sul server; il secondo è il path virtuale (codificato con i segni %) ed andrebbe in ogni caso preferito. Ad esempio il seguente brano di file HTML :

<PRE>
<--#include virtual="/motd.txt"-->
</PRE>

potrebbe diventare, una volta processato dal server e se esiste nella documentroot un opportuno file motd.txt :

<PRE>
Ciao!
Oggi è Venerdì 3 Gennaio.
Per vedere le novità fai click su *news*!
</PRE>

Molto comoda è la direttiva var che permette, senza ricorrere a programmi esterni, la visualizzazione delle variabili d'ambiente messe a disposizione dall'interfaccia CGI nonché di altre variabili d'ambiente che sono esclusivo appannaggio dell'interfaccia SSI. Eccone la lista :

Variabile d'ambiente	Descrizione
DATE_GMT	La data e l'ora in GMT
DATE_LOCAL	La data e l'ora nel fuso orario su cui è impostato il server
DOCUMENT_NAME	Il nome (senza path) del documento richiesto dall'utente
DOCUMENT_URI	Il path virtuale (URL) del documento richiesto dall'utente
LAST_MODIFIED	La data e l'ora dell'ultima modifica al documento richiesto dall'utente

Ed eccoci alla direttiva clou: exec, che permette l'esecuzione di programmi CGI o di comandi esterni. Essa ammette due tipi di parametro: cgi e cmd. Con il primo è possibile l'esecuzione dei programmi CGI: la stringa specificata viene intesa come path virtuale; se il primo carattere non è una "/" la stringa viene intesa come path relativo, ma non è comunque possibile uscire dalla documentroot. Vediamo come esempio un semplicissimo contatore di accessi. Poniamo di avere il seguente file count.pl in /cgi-bin :

#!/usr/bin/perl
print "Content-type: text/html\n\n";
open (CTN, "countfl");
$accessi=<CTN>
chop($accessi);
close (CTN);
$accessi++;
print "$accessi\n";
open (CTN, ">countfl");
print CTN "$accessi\n";
close (CTN);

E supponiamo di aver creato un file countfl nel seguente modo (da una shell unix) :

$ echo 0 > countfl
$ chmod 777 countfl

Per far funzionare il contatore sarà sufficiente inserire il seguente codice nel documento HTML :

<P>
Questa pagina ha avuto <--#exec cgi="/cgi-bin/count.pl"--> accessi
</P>

L'output finale sarà qualcosa di questo tipo :

<P>
Questa pagina ha avuto 77 accessi
</P>

Il parametro cmd permette invece l'esecuzione di programmi esterni alle directory dove sono contenuti i docmenti HTML. Ad esempio, ricordandosi che il comando Unix ls corrisponde (più o meno) al comando dir sotto Dos/Windows, il seguente codice HTML :

<--#exec cmd="/bin/ls"-->

produrrà un output facilmente intuibile da tutti. ;-)

È utile ricordare che le 5 variabili d'ambiente accessibili tramite la direttiva echo dell'interfaccia SSI sono accessibili anche dai programmi chiamati con la direttiva exec esattamente come le altre variabili d'ambiente.

Apache 1.2 XSSI

È da un po' di tempo disponibile la beta 4 della versione 1.2 di Apache, il più diffuso server Web per Unix, completamente freeware. Con questa versione è stata introdotta l'interfaccia XSSI (eXtended Server Side Include) che, come forse il nome fa intuire, è un'estensione dell'interfaccia SSI. Vediamo quali sono le novità introdotte.

È stata introdotta una nuova direttiva SSI, set, che permette di assegnare un valore ad una variabile d'ambiente; essa sarà poi disponibile a tutti i programmi esterni chiamati successivamente tramite SSI. La sintassi è la seguente :

<!--#set var="nomevariabile" value="valore-->"

Per visualizzare tutte le variabili d'ambiente si può utilizzare la seguente direttiva :

<!--#printenv -->

Le variabili possono poi essere utilizzate per il controllo di quali parti del documento devo essere inviate al client, tramite le seguenti direttive :

<!--#if expr="espressione" -->
<!--#elif expr="espressione" -->
<!--#else -->
<!--#endif -->

Queste corrispondono agli statement if, elseif, else ed endif di un linguaggio di programmazione. Il codice HTML posto sotto if ed elif viene infatti inviato al client se e solo se expr risulta vera, altrimenti viene inviato il codice posto sotto la direttiva else; il codice sotto endif viene comunque inviato. Espressione può essere :

Espressione	Valore
stringa	vera se la stringa non è vuota
stringa1 = stringa2	vera se le due stringhe sono uguali. Se si utilizza la sintassi /stringa2/, essa verrà confrontata come una regular expression secondo la stessa sintassi del comando Unix egrep
stringa1 != stringa2	vera se le due stringhe sono diverse. Anche qui è possibile utilizzare il confronto con regular expression
( espressione )	vera se espressione è vera
! espressione	vera se espressione è falsa
espressione1 && espressione2	vera se sia espressione1 che espressione2 sono vere
espressione1 || espressione2	vera se o espressione1 o epressione2 (o entrambe) è vera

All'interno dell'espressione le variabili d'ambiente andranno identificate precedendole con un dollaro ($).

La possibilità di controllare quali parti del documento vengono inviate all'utente è di potenza devastante. Basti vedere il seguente brano di documento HTML :

<,!--#if expr="$HTTP_USER_AGENT = /MSIE/" -->
Qui va inserito codice HTML specifico per MS Internet Explorer!
<!--#elsif expr="$HTTP_USER_AGENT = /Mozilla/" -->
Qui va inserito codice HTML specifico per Netscape!
<!--#else -->
Qui va inserito codice HTML generico per gli altri browser
<!--#endif -->

Queste righe controllano se il browser è Netscape o Internet Explorer ricercando, tramite regular expression, la stringa Mozilla o MSIE all'interno della variabile d'ambiente HTTP_USER_AGENT. Nel caso si tratti di Internet Explorer, viene inviato al client codice HTML specifico per MSIE, se il browser è invece Netscape viene inviato codice specifico per esso; infine, se il browser non è nessuno dei due cercati, viene mandato altro codice. Ciò permette ad esempio di non inviare JavaScript o tag per la definizione di frame a browser che non li supportano, sostituendoli con codice HTML alternativo.

E la prossima volta...

I concetti di base sull'interfaccia CGI sono ormai stati spiegati in gran parte, i rimanenti si comprenderanno con l'esperienza. La prossima volta vedremo qualche programma.

Bibliografia :
Larry Wall / Randal L. Schwartz - "Programming perl" - O'Reilly & Associates
Shishir Gundavaram - "CGI Programming on the World Wide Web" - O'Reilly & Associates
Apache Documentation - http://www.apache.org/docs/
A. S. Hornby - "Oxford Student's Dictionary of AMERICAN English" - Oxford University Press