HTML3: SSI


Online Manual
Home Intro History FAQ Choices Side bar Styles Headers Footers Effects Chars Address Links Images Rollovers Tables Forms SSI Plugins
Resources
Colour editing Image creation JS Tricks Servers Tokens Latin-1

HTML³: SSI

The SSI (Server Side Includes) system is a little like a primitive JavaScript, in that you embed commands inside comments and these can re-write parts of your document based on certain environment variables (such as time). However, SSI commands are executed by the server while it's serving your web page, so that by the time the page reaches the viewer's browser all they see is the resultant HTML with no trace of the original commands; the upshot of this is that unlike JavaScript they work with all browsers. It's generally used by ISPs to create error documents that can give you useful information.

The downside is that SSI is much more limited than something like JavaScript, and in fact there are only six basic commands, and you'll probably only get five of these to work. They all follow the same syntax, which must be followed exactly:

 Note that there is no gap between the <-- and the #, and between the # and the command.

Commands:

config

This sets the format of output generated by certain environment variables - for instance, using long or short months in dates. You can have more than one of these in a page, just put one right before it's needed for one command, and then another just before the second command and so on.

There are three possible arguments for this command: timefmt, sizefmt and errmesg.

timefmt
You can set the time and date format of various echo commands using a system of Unix-style tokens (very similar to those used on Acorn machines for !Alarm, or SYS"OS_ConvertDateAndTime" for the technically minded). To set the format for the date to dd/mm/yy, you would use: 

And here's a full list of those tokens:

%a abbreviated weekday name

%A full weekday name

%b abbreviated month name

%B full month name

%c locale's appropriate date and time representation

%C default date and time format

%d day of month - 01 to 31

%D date as %m/%d/%y

%e day of month - 1 to 31 (single digits are preceded by a blank)

%h abbreviated month name (alias for %b)

%H hour - 00 to 23

%I hour - 01 to 12

%j day of year - 001 to 366

%m month of year - 01 to 12

%M minute - 00 to 59

%n insert a new-line character

%p string containing ante-meridiem or post-meridiem indicator (by default, AM or PM)

%r time as %I:%M:%S %p

%R time as %H:%M

%S second - 00 to 61, allows for leap seconds

%t insert a tab character

%T time as %H:%M:%S

%U week number of year (Sunday as the first day of the week) - 00 to 53

%w day of week - Sunday = 0

%W week number of year (Monday as the first day of the week) - 00 to 53

%x Country-specific date format

%X Country-specific time format

%y year within century - 00 to 99

%Y year as ccyy (4 digits)

%Z timezone name

sizefmt
This is to set the format for how file sizes are displayed: 

`sizefmt="abbrev"`	[an error occurred while processing this directive]
`sizefmt="bytes"`	[an error occurred while processing this directive]

errmesg
This sets what error message is displayed when SSI generates an error - for instance, when you try to include a file which doesn't exist.

The following shows the format of this command, but using the text that appears as the default - change this as you see fit, perhaps even using it to to errors appearing altogether!

echo

This command allows you to basically dump the contents of some of the web server's internal variables to the page - for instance, where the viewer has just come from or when the page was last updated. Not all of these will return meaningful responses, sometimes because that part isn't in use for the particular page, and sometimes because the services isn't in use on that server.

AUTH_TYPE (none)

CONTENT_LENGTH (none)

CONTENT_TYPE (none)

DATE_GMT Thursday, 29-Jul-2010 22:19:22 GMT *

DATE_LOCAL Thursday, 29-Jul-2010 23:19:22 BST *

DOCUMENT_NAME ssi.html

DOCUMENT_URI /programs/html3/ssi.html

LAST_MODIFIED Monday, 11-Feb-2002 00:00:00 GMT *¹

PAGE_COUNT (none)

HTTP_REFERER (none)

REMOTE_ADDR 38.107.191.111

REMOTE_HOST (none)

REMOTE_USER (none)

REQUEST_METHOD GET

SERVER_NAME www.houseofmabel.com

SERVER_PORT 80

SERVER_PROTOCOL HTTP/1.1

SERVER_SOFTWARE Apache

TOTAL_HITS (none)

* - can be altered using the config command
¹ - see also flastmod

Example:


Thursday, 29-Jul-2010 23:19:22 BST

include

This allows you to include the contents of another file in the HTML file - so for instance you can automatically add the same header to each page on your site and only need to change one file to automatically change the header for every page.

There are two ways of referencing the file you want to include - file and virtual.

 file allows you to specify a file with an address working up from the current file - for instance file="text.txt" or file="textfiles/text.txt"; note however you cannot go backwards, for instance you cannot use file="../text.txt". For that you must use the virtual version: 

fsize

This command is called in the same way as include (i.e. with the argument of file or virtual), but simply prints the size of the file specified. The output can be changed by the config command. 
[an error occurred while processing this directive]

flastmod

Again, this command is called in the same way as include (i.e. with the argument of file or virtual), but prints the date the file was last modified. It can be influenced by the config command too. 
[an error occurred while processing this directive]

exec

This is used to execute programs - and will probably be switched off so you can't damage the server.

SSI programming

So far you've learnt some fun commands which can add that extra touch to your websize; however, if you want to get into the more advanced use of SSI, you can also do things like conditional checks. For instance, change the colour of a web page background colour based on the time of day!

This documentation is taken from the Apache website,

printenv

The printenv command - just used on its own, with no arguments - prints out a listing of all existing variables and their values. This is only useful when you've set some variables!

set

This sets the value of a variable.

Example:

 Attributes:

var: The name of the variable to set.
value: The value to give a variable.

Include 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 then URL for the current document.
LAST_MODIFIED: The last modification date of the document requested by the user.

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

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:
 in foo  in bar  in neither 

Flow Control Elements

The basic flow control elements are:

   

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 the 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 string1 < string2 string1 <= string2 string1 > string2 string1 >= string2: Compare string1 with string 2. If string2 has the form /string/ then 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:

 

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