SSI (Server Side Includes) directives allow static HTML documents to be enhanced at run-time, that is, the directives are special placeholders in an HTML document that the server will replace with actual data just before sending the final document to the browser.
Processing a document at run-time, in order to find the placeholders, is called parsing it; hence the term "parsed HTML" sometimes used for documents that contain SSI instructions. Parsing tends to be extremely resource-consumptive, and is not enabled by default.
According to "Web Design in a Nutshell":
SSI allows you to create the framework for pages that will be dynamically generated by the server. For the web author, this can be a powerful tool for managing site production and increasing efficiency. The following are just a few examples of the ways SSI can be used:
- Placing elements that you use over and over again. If you have an element that appears on every page of your site, such as complex navigational header, you can place a single SSI command that just sources it in instead. If you make changes to the header, such as changing a URL or a graphic, you only need to make the change once, and it will be updated automatically on all pages of your site.
- Place a constantly changing element on your page with a single line. For example, if you maintain a homepage that has a message that changes every day, use SSI command (and a script on the server) to replace the message automatically. You never need to touch the source code for the home page - you just let the server do the work.
- Show the date and time the page was last updated.
- Allow multiple users to submit content for inclusion on a web page without giving them access to the HTML source. For example, staff members could send in weekly updates via email. The server could run a script that turns the email into a text file, which is then inserted into the web page via an SSI command.
SSI commands have the following format:
<!--#element attribute="value" -->
The element is one of the predefined functions that SSI can perform (see below). The command also includes one or more attribute/value pairs that provide the specific parameters to the function.
Note:
The simple type of Server Side Include is a "virtual include", which tells the server to add information too a file before sending it to the browser.
In this example, let's take a page from within a web site that uses a standard navigational toolbar held together with a table. Instead of placing the table in the HTML source for every web page in the site, we could just insert it into each document as follows:
<html> <head><title>News<</title></head> <body> <!--#include virtual="navtable.html" --> <h1>Today's Headlines</h1> ... page contents ... </body> </html>
Documents that contain SSI commands should be saved with an identifying suffix, which indicates to the server that the file should be parsed before being sent to the browser. In most cases, the suffix is .shtml.
The command in the above example uses the include element, which inserts the text of another document into the parsed file. The include element uses the virtual parameter to specify the URL of the document to be inserted, in this case navtable.html. The following shows the (simplified) contents of navtable.html:
<table> <tr><td><img src="toolbar.gif"></td></tr> ... complicated toolbar stuff ... </table>
Technically, this is just a fragment of an HTML document because the structural tags (head, body) have been omitted. This is one way to ensure the final document doesn't end up with a double (and conflicting) set of structural tags.
The server puts the fragment in the spot indicated by the virtual include command. When the document is sent to the browser, the source looks like:
<html> <head><title>News<</title></head> <body> <table> <tr><td><img src="toolbar.gif"></td></tr> ... complicated toolbar stuff ... </table> <h1>Today's Headlines</h1> ... page contents ... </body> </html>
The full list of the elements for an Apache server can be found on Apache XSSI Documentation.
bytes
for a count in bytes, or
abbrev
for a count in Kb or Mb as appropriate.
(none)
.
Any dates printed are subject to the currently configured timefmt
.
Attributes:
The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the original request from the client; these cannot be specified in the URL path. The include variables will be available to the script in addition to the standard CGI environment.
If the script returns a Location: header instead of output, then this will be translated into an HTML anchor.
The include virtual
element should be used in preference to
exec cgi
.
/bin/sh
.
The include variables are available to the command.
sizefmt
format specification. Attributes:
timefmt
format specification. The attributes are
the same as for the fsize
command.
An attribute defines the location of the document; the inclusion is done for each attribute given to the include command. The valid attributes are:
../
, nor can it be an
absolute path. The virtual
attribute should always be used
in preference to this one.
<!--#printenv -->
<!--#set var="category" value="help" -->
echo
command, for if
and
elif
, and to any program invoked by the document.
Example: Printing the date and time.
In the following, the current date and time is displayed
on the web page using the echo element and the
DATE_LOCAL variable. If the following SSI command is put
to an HTML source:
<--#echo var="DATE_LOCAL" -->
the server will print the following in the place of
the command:
Friday, 01-Oct-99 19:17:32 EET
Flow control elements are a set of if/else commands (similar to if statements used in a programming language) that allow authors to create conditional commands. Using flow control elements, authors can make documents display differently based on specific variables (the "test conditions"). For instance, you could publish one version of your page for users accessing it with the Netscape browser and another for Internet Explorer users.
The basic flow elements are:
<--#if expr="test_condition" --> <--#elif expr="test_condition" --> <--#else --> <--#endif -->
The first command contains the if
statement that
causes the server to test for a condition (e.g. if the browser
is Netscape). If it is found to be true, the server prints
the text or executes any SSI commands immediately following
the if
command. If the test condition is false,
the elif
or else
statements are
used to output specified text or commands. The endif
element ends the if
element and is required.
In the following example, a greeting is customized based on the user's browser:
<--#if expr="\"$HTTP_USER_AGENT\" = \"Mozilla\"" --> Welcome Netscape User! <--#elif expr="\"$HTTP_USER_AGENT\" = "\"Explorer\"" --> Welcome Internet Explorer User! <--#else --> Welcome! <--#endif -->
Variable substitution is done within quoted strings in most cases where they may reasonably occur as an argument to an SSI directive. This includes the config, exec, flastmod, fsize, include, and set directives, as well as the arguments to conditional operators. You can insert a literal dollar sign into the string using backslash quoting:
<!--#if expr="$a = \$test" -->
If a variable reference needs to be substituted in the middle of a character sequence that might otherwise be considered a valid identifier in its own right, it can be disambiguated by enclosing the reference in braces, à la shell substitution:
<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
This will result in the Zed variable being set to "X_Y" if REMOTE_HOST is "X" and REQUEST_METHOD is "Y".
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 -->
FORMAT |
DESCRIPTION |
EXAMPLE |
%% |
% | |
%a |
Day of the week abbreviation | Sun (for Sunday) |
%A |
Day of the week | Sunday |
%b |
Month name abbreviation | Mar (for Mar) |
%B |
Month name | March |
%d |
The day of the month as a decimal number | 1 (not 01) |
%D |
Date as mm/dd/yy (or %m/%d/%y) | 06/23/95 |
%e |
Date of the month as a decimal number in a two-digitfield ranging from 1 through 31 | 01 |
%H |
The hour of the 24-hour clock as a decimal number (00 through 23) | 13 |
%I |
The hour of the 12-hour clock as a decimal number (00 through 12) | 1 |
%j |
The day of the year as a decimal number (01 through 366) | 111 |
%m |
The month of the year as a decimal number (01 through 12) | 11 |
%M |
The minutes of the hour as a decimal number (00 through 59) | 08 |
%p |
The local AM or PM string | p.m. |
%r |
The 12-hour clock time in local AM/PM notation Time as "%I:%M:%S AM | PM" | 10:24:58 AM |
%S |
The seconds of the minute as a decimal number (00 through 59) | 50 |
%T |
The 24-hour time in "%H:%M:%S" format | 16:23:43 |
%U |
The week of the year as a decimal number (00 through 52) with Sunday as the first day of the week Week of the year (also %W) | 49 |
%w |
The day of the week as a decimal number (0 through 6) | 05 |
%W |
The week of the year (00 through 53) with Monday as the first day of the week | 50 |
%y |
The year of the century (00 to 99) | 99 |
%Y |
Year as a decimal number | 1999 |
%Z |
The time zone name (if one can be determined) | EST |