CGI Corner

Server Side Includes

Server Side Includes are useful, relatively easy to implement and very impressive, expecial towards the "profane" user ;-). So, let's see how to use 'em!

by Michele Beltrame

Server Side Includes

With Server Side Includes it is possible to create, often without writing a single line of non-HTML code, dynamic pages, that is to say pages which contents may vary depending on the moment, the user, the remote browser or other parameters. For example, with SSI you can create access counters, which are without any doubt the most common application of this technlogy.

Other possible application are, for instance, the creation of file statistics, or the possibility to view and use data which is sent to the server from the remote browser.

But how do they work?

<--#command parameter="value"-->

There shouldn't be any space between angular brackets, minus signs and # sign.

The server, before sending a document to the client, processes it and substitutes all SSI tags with what they request. A SSI tag may be substituted by the value of a server environment variable, by the output of an external program, by a text file, ...

I wrote about the server configuration for Server Side Includes in CGI Corner of Beta #9. However, it has to be reminded that the server is usually configured to scan for SSI tags only documents with .shtml extension (Server-parsed HTML). In order to make the server scan also .htm and .html file you should make the proper configuration changes or contact your webmaster. However, be aware that make the server process all documents may cause some slowdown in downloading them.

SSI directives

First of all we'll have a look at the parameters accepted by the config directive, which is used to change some aspects of the SSI interface configuration.

Parameter	Description
errmsg	Allows to set a custom error message
sizefmt	Changes the format in which file sizes are displayed
timefmt	Changes the format in which date and time are displayed

The echo directive is used to print the value of an environment variable or of a special SSI variable (which is also an environment variabile).

Parameter	Description
var	Inserts the value of the specified variable in the current HTML document

The include directly makes it possible to insert a text file into the current document.

Parameter	Description
pathname	Relative path to the current directory on the server
virtual	Virtual path (root = documentroot)

The fsize inserts the dimension of a file into the current HTML document.

Parameter	Description
file	Relative path to the current directory on the server

Finally, the flastmod directive inserts date and time of the last modification to a file.

Parameter	Description
file	Relative path to the current directory on the server

The gory details

With:

<--#config errmsg="error message"-->

it is possible to choose an error message in substitution of the default one which is, at least for Apache, the following :

[an error occurred while processing this directive]

This directive has to be placed before all the others in the HTML document, because it only affects the directives which follow it.

The

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

directive allows to change the format in which date and time are shown. This directive has to be places before a SSI tag which requests a date or a time to the server (such as flastmod).

The possible values for %1, %2, %... (the number of parameter is free) are the following. These values are the parameters which are passed to the Unix function size_t strftime(char *s, size_t max, const char *format) (time.h) :

Value	Description
%a	Writes the abbreviated name of the day (Sun, Mon, ...)
%A	Writes the extended name of the day (Wednesday, ...)
%b or %h	Writes the abbreviated name of the month (Jan, Feb, ...)
%B	Writes the extended name of the month (April, ...)
%d	Writes the day of the month without the 0 before (1->31)
%D	Writes the date in the "%m/%d/%y" format
%e	Writes the day of the month with the 0 before (01, 02, 15, ...)
%H	Writes the hour in 24h format (0->23)
%I	Writes the hour in 12h format (0->12)
%j	Writes the day of the year (1->366)
%m	Writes the number of the month
%M	Writes the number of minutes
%p	Writes "a.m." o "p.m" depending on wether it's morning or afternoon
%r	Writes the time in "%I:%M:%S %p" format
%S	Writes the number of seconds
%T	Writes the time in "%H:%M:%S" format
%U or %W	Writes the week number (1->52)
%w	Writes the number of the weekday (01->07)
%y	Writes the year omitting the century (01->99)
%Y	Writes the year (1997, ...)
%Z	Writes the time zone (MET for Italy)

The last configurable option is the format in which a file size is shown. This is done using the fsize directive :

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

Possible formats are bytes if you want the size to be printed in bytes or abbrev if you want the size to be printed in kilobytes or megabytes (rounded).

We'll now see how the fsize directive works: it prints a file size using the format specified with sizefmt. Here follows an example :

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

This tag displays the size of the file prova.pl, which is located in the /cgi-bin directory (relative path to the documentroot).

The flastmod directive shows the date of the last modification to a determined file. The path is, as in the fsize case, relative to the documentroot. The following HTML code:

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

would be substituted with something as :

21:45:12 03/1/96

Let's now switch to the include directive, which makes it possible o include a text file in the current HTML document. Two types of parameters are allowed to specify the path: file and virtual. The first is only used to refer to the current directory on the server; the second is the virtual path (% coded) and should also be used as the first choice. For instance, the following piece of HTML code :

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

may become, after it has been processed by the server and if there is a motd.txt file in the documentroot :

<PRE>
Hallo!
Today is Wednesday, January 3rd.
To see what's news click on *news*!
</PRE>

The var directive is very useful as it allows you to print environment variable without writing any code. Besides the normal environment varibales created also by the CGI interface, there are some variable which are unique to SSI interface. Here follows a list of them :

Environment variable	Description
DATE_GMT	Date and time in GMT
DATE_LOCAL	Local date and time
DOCUMENT_NAME	The name (without) path of the requested document
DOCUMENT_URI	The virtual path (URL) of the requested document
LAST_MODIFIED	Date and time of the last modification at the requested document

Here we are with the clou directive: exec, whcih makes it possible to execute CGI programs or external commands. It permits two types of parameter: cgi and cmd. The first is used to execute CGI programs: the specified string is taken as a virtual path to the program; if the first charachter isn't a "/", the string is taken as a relative path; in any case it is not possible to exit from the documentroot. Let's now see, as example, a simple access counter. Presume you have the following count.pl file in /cgi-bin :

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

Also imagine you have created a countfl file with the following instruction (unix shell commands) :

$ echo 0 > countfl
$ chmod 777 countfl

In order to make the counter work, the only thing to do is to insert the following code in the HTML document :

<P>
There have been <--#exec cgi="/cgi-bin/count.pl"--> hits to this page
</P>

The final output should be something similar to the following :

<P>
There have been 77 hits to this page
</P>

The cmd parameter is used to execute programs which are outside the HTML documents directory. For example, the following code (remember that the Unix ls command is (more or less) similiar to the dir command under Dos/Windows) :

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

will produce an output which I think is obvious to all. ;-)

It is useful to remember that the 5 environment variables accessible through the echo SSI directive are also accessible by the programs called with the exec directive, as all the other environment variables.

Apache 1.2 XSSI

It si now availbale the beta 4 of Apache 1.2, the most widely used Web server, completely freeware. With version 1.2 XSSI, an extension to SSI interface, has been introduced. There are some new exciting features in SSI, let's have a look at them.

A new SSI directive, set, has been introduced. It makes it possible to set the value of an environment value; this value will be then available to all the external programs called via SSI. It's syntax is the following :

<!--#set var="name" value="value-->"

To print the value of all the environment variables you may use the following directive :

<!--#printenv -->

These variables may be used to control the flow of the HTML document, that is to send some parts of the document only if a certain condition is true. The following directives may be used for this purpose :

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

These tags may be compared to if, elseif, else and endif statement of a programming language. The HTML code places under if and elif is sent to the client only if expr is true, otherwise the code placed under the else directive will be sent; the code under endif will be sent in any case. Expression may be one of the following :

Expressional	Value
string	true if string is not empty
string1 = string2	true if the two strings are identical. If the syntax /string2/ is used, string2 will be compared as a regular expression following the same syntax of the Unix egrep command
string1 != string2	true if the two strings are different. Regular expressions may be used in this case also
( expression )	true if expression is true
! expression	true if expression is false
expression1 && expression2	true if expression1 and expression2 are both true
espressione1 || espressione2	true if expression1 or expression2 is true (or both)

Inside an expression, environment variables should be identified placing a dollar sign before them ($).

the ability to control the flow of a document is very much powerful. To realize this have a look at the following example :

<,!--#if expr="$HTTP_USER_AGENT = /MSIE/" -->
Here you should place MS Internet Explorer specific HTML code!
<!--#elsif expr="$HTTP_USER_AGENT = /Mozilla/" -->
Here you should insert Netscape specific code!
<!--#else -->
Here you should insert generic code for other browsers!
<!--#endif -->

These few line of HTML code check wether the browser is Netscape or MS Internet Explorer. This is done by looking for, via regular expressions, the string Mozilla or MSIE inside the HTTP_USER_AGENT environment variable. If MS Internet Explorer is detected, specific code for MSIE is sent to the browser; if the browser is Netscape, specific code for it is sent; finally, if neither Mozilla or MSIE is detected, generic code is sent. This allows, for instance, to avoid sending JavaScript or frame definition tags to browser which don't support them, and to substitute them with alternate HTML code.

And next time...

The basic concepts on CGI interface have now for the most been explained, the remaining ones will be understood with experience. Next time we'll se some applications.

Bibliography :
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