Server Side Includes

Enabling SSI

If your web document contains SSI directives, you need to enable SSI. The way to do this is to use the .shtml extension, rather than .htm or .html, for your files. This tells the Web server that it should interpret any SSI directives in these files and render them correctly.

The SSI directives are treated as comments by web authoring software, since they use this syntax:
 

<!--#element attribute=value attribute=value ... -->

The value will often be enclosed in double quotes; many commands only allow a single attribute-value pair. Here are some typical examples that use the echo element:
 

<!--#echo var="date_local" -->
<!--#echo var="remote_host" -->
<!--#echo var="remote_user" -->

Using include will allow you to include the content of another file into your current document. For example, if we wanted to include an email address and a copyright notice at the bottom of all of our web pages, we could create a file named footer.html that contained this information and "include" it into all of our pages. If the email address changes, or we wish to add something else to the footer in the pages on our site, we only have to change the content of one file instead of every page — very efficient and convenient. At the bottom of each of our pages we would put

<!--#include virtual="/ourpages/bits/footer.html" -->

An attribute, using either "virtual" or "file," defines the location of the file we want to include:

• virtual gives a virtual path to a document on the server that is a (%-encoded) URL relative to the current document being parsed (displayed in the web browser). The URL cannot contain a scheme or hostname (eg. columbia.edu), only a path and an optional query string. If it does not begin with a slash (/) then it is taken to be relative to the current document.
• file gives a pathname relative to the directory containing the current document being parsed. You cannot use ../ (go up a directory) in this pathname, nor an absolute path.

It is usually best to use virtual.

SSI Quick Reference

Date of current file's last modification

<!--#echo var="last_modified" -->

The size of a file

<!--#fsize virtual="/cu/lweb/index.html" -->

Date of a given file's last modification

<!--#flastmod virtual="/cu/lweb/index.html" -->

Current date in the local time zone

<!--#echo var="date_local" -->

The browser the client is using
<!--#echo var="http_user_agent"-->

The current date in Greenwich Mean Time

<!--#echo var="date_gmt"-->

The filename (excluding directories) of the document requested by the user.

<!--#echo var="document_name"-->

The (%-decoded) URL path of the document requested by the user. Note that in the case of nested include files, this is not then the URL for the current document.

<!--#echo var="document_uri"-->

(The following are part of the Apache Standard CGI Environment Variables)

The revision of the Common Gateway Interface that the server uses

<!--#echo var="gateway_interface"-->

The server's hostname or IP address

<!--#echo var="server_name"-->

The name and version of the server software that is answering the client request

<!--#echo var="server_software"-->

The name and revision of the information protocol the request came with

<!--#echo var="server_protocol"-->

The port number of the host on which the server is running

<!--#echo var="server_port"-->

The method with which the request was issued: GET or POST

<!--#echo var="request_method"-->

Extra path information

<!--#echo var="path_info"-->

The translated version of PATH_INFO

<!--#echo var="path_translated"-->

The directory from which the web documents are served

<!--#echo var="document_root"-->

The remote hostname of the user making the request

<!--#echo var="remote_host"-->

The remote IP address of the user making the request

<!--#echo var="remote_addr"-->

The authentication method used to validate a user

<!--#echo var="auth_type"-->

The authenticated name of the user

<!--#echo var="remote_user"-->

The email address of the user making the request (not always available)

<!--#echo var="http_from"-->

A list of MIME types that the client can accept

<!--#echo var="http_accept"-->

The browser the client is using to issue the request

<!--#echo var="http_user_agent"-->

The URL of the document that the client was at before accessing current file (not always available)

<!--#echo var="http_referer"-->

Dates

Some of the ssi's display a date, for example, a file's last modification, the current date in the local time zone, etc. You can configure how the date is displayed and which elements of the date are displayed by using
<!--#config timefmt=" " --> and the following variables:

Full

Abbreviated

%A Full weekday name %a Abbreviated weekday name
%B Full month name %b Abbreviated month name
%Y Full year %y Abbreviated year
%D Date as mm/dd/yy %d Day of the month
%H Hour as 1 - 23 %I Hour as 1 - 12
%M Minutes 0 -60 %m Month of the year 01 - 12
%R Time as %H: %M %r Time as %I: %M: %S: %p
%p a.m. or p.m. %T Time as %H: %M: %S
%S Seconds as 0 - 60 %Z Time zone name

For example

<!--#config timefmt="%d %B %Y" -->
<!--#echo var="DATE_LOCAL" -->

will produce

02 December 2011

SSI Flow Control

The basic flow control elements are:

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

The if element works like an if statement in a programming language. The test condition is evaluated and if the result is true, then the text until the next elif, else. or endif element is included in the output stream The elif or else statements are be used to put text into the output stream if the original test_condition was false. These elements are optional. The endif element ends the if element and is required.

test_condition Is One of the Following:
string
true if string is not empty
string1 = string2
string1 != string2
Compare string1 with string 2. If string2 has the form /string/ than it is compared as a regular expression. Regular expressions have the same syntax as those found in the Unix egrep command.
( test_condition )
true if test_condition is true
! test_condition
true if test_condition is false
test_condition1 && test_condition2
true if both test_condition1 and test_condition2 are true
test_condition1 || test_condition2
true if either test_condition1 or test_condition2 is true
"=" and "!=" bind more tightly than "&&" and "||"; "!" binds most tightly. Thus, the following are equivalent:

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

Anything that's not recognized as a variable or an operator is treated as a string. Strings can also be quoted: 'string'. Unquoted strings can't contain whitespace (blanks and tabs) because it is used to separate tokens such as variables. If multiple strings are found in a row, they are concatenated using blanks. So,

string1 string2 results in string1 string2
'string1 string2' results in string1 string2

Variable substitution is done within quoted strings. You can put a dollar sign into the string using backslash quoting:

<!--#if expr="$a = \$test" -->

Example

The below example will print "in foo" if the DOCUMENT_URI is /foo/file.html, "in bar" if it is /bar/file.html and "in neither" otherwise:

<!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" -->

in foo

<!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" -->

in bar

<!--#else-->

in neither

<!--#endif-->