Server Parsed Documents

Server Parsed Documents
(Server Side Includes)

Overview
Server Side Includes (SSI) are a powerful way of embedding dynamic content in your web pages. SSI documents are parsed by the server before being sent to the client. This allows you to embed SSI tags within HTML pages which are expanded by the server before being sent to the client. The Zeus server has an exceptionally flexible SSI engine which can expand SSI tags, regardless of how the HTML was generated. The Zeus SSI engine is optimised so SSI documents do not degrade the performance of the server.
SSI enabled HTML files require a MIME type of text/x-server-parsed-html which by default is mapped on to the .shtml file extension. Any output generated which has a MIME type of text/x-server-parsed-html will be parsed by the server, whether it is from a static file, a CGI script or a Java Servelet.
SSI Directives
SSI Directives are special values in your HTML files which the server will look for to parse. In order not to interfere with your HTML design the SSI directives are included in HTML comments. HTML comments have a special starting tag ""

SSI directives contain a command, and a number of parameters and arguments. So they take the form :

The #echo Command
The echo command makes available the set of environment variables sent to CGI programs. Using this command you can send these variables back to the user without having to resort to CGI programs. The echo command is followed by the parameter and argument values "var=environment variable". For a full list of environment variables see the CGI documentation.
Example : Output Environmental Variables
The following SHTML file displays a selection of SSI variables.
Will result in something similar to the following being sent to the client:

The #include Command
Managing a complex web site can be a considerable task, particularly if you wish to maintain a common look and feel through out all the pages. Including a common footer or navigation bar to your site helps your visitors identify where they are and helps them move quickly to the information they need. However if you then need to change the footer, you would need to update every page on your site. By using SSI to insert a file at the end of each of your pages you would only need to change one file.
The SSI directive include allows us to merge other files into our HTML pages. It is followed by the parameters file or virtual. file specifies a filename relative to the current directory, virtual can specify a relative filename or an absolute URL within the whole document root for the virtual server.


Example : Including a footer.
Going back to our original scenario, displaying a common footer for all your documents is now easy. Each page on your server will reference the same document via the include SSI directive.
A .shtml file :
The /includes/footer.html file : Will result in the following output being set to the client:
The #fsize and #flastmod Commands
The #fsize command will insert the size of the specified file into the document. There are occasions when you may want a visitor to your web site to download information which could be substantial in size. In these cases it is polite to include the file size in the document so the visitor can estimate how long the download will take. You could include the file size directly in the HTML, but if the files were to change you would need to update the HTML pages as well. The #fsize command allows you to include the size of files which may change regularly.
The #fsize command is followed by the parameters file or virtual with the same meaning as the #include command described above. Each parameter take a file location as an argument.
The #flastmod command works in the same manner returning the data the file was last modified.
By using the recursive nature of the Zeus SSI engine it would be possible to generate a file listing from a CGI script, but obtain the file sizes and modification dates via the SSI commands.
Example : File Size of Downloads
A University publishes hourly satellite pictures on the web. Due to the difference in time and weather, combined with the effect of the compression code, the size can alter considerably. Using the #fsize and #flastmod commands the web page always has the correct information displayed.
The .shtml file:
Will result in something similar to the following being sent to the client:
The #config Command
The #config command can be used to change the output format of certain SSI directives, specifically those which return a time / date or a filesize. This allows you to use a more understandable format than the defaults for your particular application.
The #config command takes two parameters, timefmt to modify the date and time formats, and sizefmt to modify the file size format.
The timefmt parameter takes a free form text string of tokens as an argument in a similar vein to the UNIX library call strftime. These tokens are expanded by the server to produce the desired time format.

%a Day : abbreviated Mon, Tue, Wed

%A Day Monday, Tuesday

%b Month : abbreviated (%h) Jan, Feb, Mar

%B Month January, February

%C Year : Without Century "00" - "99"

%d Day of Month "01" - "31"

%D Date : mm/dd/yy "01/01/00" - "12/31/99"

%e Day of Month : Single figures "1" - "31"

%h Month : abbreviated (%b) Jan, Feb, Mar

%H Hour of Day : 24 hour clock "00" - "23"

%I Hour of Day "01" - "12"

%j Julian Day of Year "001" - "366"

%m Month of Year "01" - "12"

%M Minute "00" - "59"

%n Newline character

%p AM or PM "AM" | "PM"

%r Time in %I:%M:%S %p "00:00:00 am" - "12:59:59 pm"

%R Time in %H:%M "00:00" - "23:59"

%S Seconds "00" - "61"

%t Tab character

%T Time in %H:%M:%S "00:00:00" - "23:59:59"

%u Numbered Day of the Week : Starting with Monday = 1 "1" - "7"

%w Numbered Day of the Week : Starting with Sunday = 0 "0" - "6"

%y Year : Without Century "00" - "99"

%Y Year "0000" - "9999"

%Z Time Zone "GMT", "BST", "CST" ..

%% Percentage Character

Sophisticated time and date information can be constructed using these tokens. Additional text can also be included in the string, allowing additional explanation.
The sizefmt parameter takes an argument of either bytes or abbrev. The bytes value will cause all filesize information to be displayed exactly in bytes, while the abbrev value will display an approximate value with the units appended (Kb, Mb, Gb).
Example : Formatting The Date
Displaying a date on the welcome page for your site is quite a common requirement, but you probably don't want to got to all the trouble of writing a CGI script to display the whole page. You also probably don't want to use the default time format either. Using #config and the SSI environment variable date_local we can easily display the time in the way we want.
The .shtml file:

Will result in something similar to the following being sent to the client: We are even able to include HTML tags in text string which defined the date.
The #exec command
There are occasions when SSI includes and SSI variables cannot achieve the dynamic content you want, but still don't want to go to the trouble of writing a CGI program to generate the entire page content. By using the #exec command, you can include the output of a program within your HTML pages. The exec command is followed by the cgiparameter, and a valid CGI program as the attribute.

Example : A CGI to Display Machine Load
To prove that your server machine is capable you might want to include a load meter on the machine spec page. The page contains a lot of information and is updated frequently so you don't want a CGI program to generate the complete HTML code. The examples below will obtain the load average of the machine, then determine what colour to display the text.
A .shtmlfile :
The CGI Program: Possible (this is dynamic after all) result in the HTML:
Executing arbitrary shell commands
The exec command can also be used to execute arbitrary shell commands when used with the cmd= tag. For this tag to be available, the server needs to have `CGI enable anywhere' turned on. The server will execute the equivalent of /bin/sh -c "command" and replace the tag with the output of that command.
For example:

The #set command
The #set command allows you to add your own variables that can be used with the #echo command. For format of a #set command is:
For example: The #set command is extremely powerful as it provides a means of passing 'arguments' to recursively included SSI pages. This is because the #set command adds to the global variable environment, so a parsed document can set a variable then include another parsed document which uses this variable, or vice versa. For example:
File title.shtml:

Then we could use this complex standard title in a document "About Zeus" as follows:
Using the #set command allows the reuse of 'components' of HTML and is extremely useful in large web-site design.

%a	Day : abbreviated	`Mon, Tue, Wed`
%A	Day	`Monday, Tuesday`
%b	Month : abbreviated (%h)	`Jan, Feb, Mar`
%B	Month	`January, February`
%C	Year : Without Century	`"00" - "99"`
%d	Day of Month	`"01" - "31"`
%D	Date : mm/dd/yy	`"01/01/00" - "12/31/99"`
%e	Day of Month : Single figures	`"1" - "31"`
%h	Month : abbreviated (%b)	`Jan, Feb, Mar`
%H	Hour of Day : 24 hour clock	`"00" - "23"`
%I	Hour of Day	`"01" - "12"`
%j	Julian Day of Year	`"001" - "366"`
%m	Month of Year	`"01" - "12"`
%M	Minute	`"00" - "59"`
%n	Newline character
%p	AM or PM	`"AM" \| "PM"`
%r	Time in %I:%M:%S %p	`"00:00:00 am" - "12:59:59 pm"`
%R	Time in %H:%M	`"00:00" - "23:59"`
%S	Seconds	`"00" - "61"`
%t	Tab character
%T	Time in %H:%M:%S	`"00:00:00" - "23:59:59"`
%u	Numbered Day of the Week : Starting with Monday = 1	`"1" - "7"`
%w	Numbered Day of the Week : Starting with Sunday = 0	`"0" - "6"`
%y	Year : Without Century	`"00" - "99"`
%Y	Year	`"0000" - "9999"`
%Z	Time Zone	`"GMT", "BST", "CST" ..`
%%	Percentage Character