Uusmediasovellusten tekniikat, Server Side Includes (SSI)




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.

How SSI is used

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:

Adding SSI commands to a document

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:

Example

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>

Basic elements

The full list of the elements for an Apache server can be found on Apache XSSI Documentation.

config
This command controls various aspects of the parsing. The valid attributes are:
errmsg
The value is a message that is sent back to the client if an error occurs whilst parsing the document.
sizefmt
The value sets the format to be used when displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in Kb or Mb as appropriate.
timefmt
The value is a string to be used when printing dates.
echo
This command prints one of the include variables, defined below. If the variable is unset, it is printed as (none). Any dates printed are subject to the currently configured timefmt. Attributes:
var
The value is the name of the variable to print.
exec
The exec command executes a given shell command or CGI script. The IncludesNOEXEC Option disables this command completely. The valid attributes are:
cgi
The value specifies a (%-encoded) URL relative path to the CGI script. If the path does not begin with a (/), then it is taken to be relative to the current document. The document referenced by this path is invoked as a CGI script, even if the server would not normally recognize it as such. However, the directory containing the script must be enabled for CGI scripts (with ScriptAlias or the ExecCGI Option).

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.

cmd
The server will execute the given string using /bin/sh. The include variables are available to the command.
fsize
This command prints the size of the specified file, subject to the sizefmt format specification. Attributes:
file
The value is a path relative to the directory containing the current document being parsed.
virtual
The value is a (%-encoded) URL-path relative to the current document being parsed. If it does not begin with a slash (/) then it is taken to be relative to the current document.
flastmod
This command prints the last modification date of the specified file, subject to the timefmt format specification. The attributes are the same as for the fsize command.
include
This command inserts the text of another document or file into the parsed file. Any included file is subject to the usual access control. If the directory containing the parsed file has the Option IncludesNOEXEC set, and the including the document would cause a program to be executed, then it will not be included; this prevents the execution of CGI scripts. Otherwise CGI scripts are invoked as normal using the complete URL given in the command, including any query string.

An attribute defines the location of the document; the inclusion is done for each attribute given to the include command. The valid attributes are:

file
The value is a path relative to the directory containing the current document being parsed. It cannot contain ../, nor can it be an absolute path. The virtual attribute should always be used in preference to this one.
virtual
The value is a (%-encoded) URL relative to the current document being parsed. The URL cannot contain a scheme or hostname, 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.
A URL is constructed from the attribute, and the output the server would return if the URL were accessed by the client is included in the parsed output. Thus included files can be nested.
printenv
This prints out a listing of all existing variables and their values. No attributes.
For example: <!--#printenv -->
Apache 1.2 and above.
set
This sets the value of a variable. Attributes:
var
The name of the variable to set.
value
The value to give a variable.
For example: <!--#set var="category" value="help" -->
Apache 1.2 and above.

Using environmental variables

In addition to the variables in the standard CGI environment, these are available for the echo command, for if and elif, and to any program invoked by the document.
DATE_GMT
The current date in Greenwich Mean Time.
DATE_LOCAL
The current date in the local time zone.
DOCUMENT_NAME
The filename (excluding directories) of the document requested by the user.
DOCUMENT_URI
The (%-decoded) URL path of the document requested by the user. Note that in the case of nested include files, this is not the URL for the current document.
LAST_MODIFIED
The last modification date of the document requested by the user.

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

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

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

SSI TIME FORMATS

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

Helena Ahonen
Last modified: Wed Oct 20 07:33:56 EET DST 1999