SSI - Server Side Includes

VWS customers hosted on Primus' Windows servers can take advantage of server side includes (SSI). SSI directives allow static HTML documents to be enhanced at run-time. These directives allow you to embed extra content into your webpages right before they are served to the client. Processing a document at run-time is called parsing; hence the term "parsed HTML", which is sometimes used to refer to documents that contain SSI instructions. Note that parsing tends to be extremely resource-consumptive. When you use SSI directives on a webpage, it may take longer for the server to deliver the page to the client's browser because it has to parse the SSI directives first. SSI can also interfere with attempts to cache your your documents, which can put a further load on the server. You should only use SSI directives on pages which absolutely require them.

Note : You are versed in Active Server Page (ASP) development, you could easily duplicate all of the SSI functionality using ASP.

Using SSI

SSI support is enabled on all Windows VWS's by default. All of Primus' Windows servers run the IIS web server software. Any webpage which will contain SSI directives must have either an .shtml or .stm extension (instead of .htm or .html ). Microsoft does not provide much SSI documentation as part of the IIS documentation kit.

How do I use Server Side Includes (SSI)? 

Server Side Includes (SSI) make it easy to add dynamic content to your website. SSI lets you embed a number of special 'commands' into your standard HTML documents. The general format of a SSI directive contains a command and a number of parameters and arguments. The form they usually take is:
<!--#command parameter(s)="argument"-->

Primus uses the "Zeus" web server software which supports many (but not all) of Apache's SSI features. The following pages contain additional information on Zeus' SSI features:

• http://support.zeus.com/doc/api/ssi/

Getting Started
SSI support is included by default on all of Primus' Standard, Advanced and Profusion UNIX Virtual Web Servers. To use SSI in a web page, the web page must have an extension of .shtml. This special extension forces the web server to parse your HTML page for SSI commands and process any that are found.

The #set and #echo Commands
The #set command allows you to add your own variables that can be used with the #echo command.
The #echo command allows you to output the value of a variable into your HTML page.

The format of the #set command is:
<!--#set var="..." value="..." -->

The format of the #echo command is:
<!--#echo var="..." -->

For example:
<!--#set var="message" value="Hello World!" -->
<!--#echo var="message" -->

Environment Variables
The web server provides a number of "environment variables" available to your SSI commands.
You can use the echo command to display the value of any of the environment variables.

GATEWAY_INTERFACE : <!--#echo var="GATEWAY_INTERFACE"-->
SERVER_PROTOCOL : <!--#echo var="SERVER_PROTOCOL"-->
SERVER_PORT : <!--#echo var="SERVER_PORT"-->
REQUEST_METHOD : <!--#echo var="REQUEST_METHOD"-->
HTTP_USER_AGENT : <!--#echo var="HTTP_USER_AGENT"-->
DATE_LOCAL : <!--#echo var="DATE_LOCAL"-->
DATE_GMT : <!--#echo var="DATE_GMT"-->

Will result in something similar to the following being sent to the client:
GATEWAY_INTERFACE : CGI/1.1
SERVER_PROTOCOL : HTTP/1.0
SERVER_PORT : 80
REQUEST_METHOD : GET
HTTP_USER_AGENT : Mozilla/4.0b5 [en] (Win95; I)
DATE_LOCAL : 06:12:16 PM 06/02/97
DATE_GMT : 05:12:16 PM 06/02/97

The #include file Command
Managing a complex web site can be a considerable task, particularly if you wish to maintain a common look and feel throughout all of your 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 file allows us to merge other files into your HTML pages. It is followed by the parameters file or virtual.

<!--#include file="filename"-->

The filename is relative to the current directory.

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:
<HTML>
<HEAD><TITLE>SSI Test</TITLE></HEAD>
<BODY>
<P> This is my text from index.shtml <P>
<!--#include file="footer.html"-->
</BODY>
</HTML>

The footer.html file:
Please email <a href="mailto: harry@mycompany.com "> Harry</a> for more details on our products.

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:
<html>
<head>
<title>SSI Date Test</title>
</head>
<body>
The current time is :
<b><!--#echo var="DATE_LOCAL"--></b>
<br>
But the time looks nicer this way :
<!--#config timefmt="It's <b>%A</b> and the time is <b>%I:%M %p</b>!"-->
<!--#echo var="DATE_LOCAL"-->
<hr>
</body>
</html>

Will result in something similar to the following being sent to the client:
<html>
<head>
<title>SSI Date Test</title>
</head>
<body>
The current time is :
<b>08:00:35 PM 06/02/97</b>
<br>
But the time looks nicer this way :
It's <b>Monday</b> and the time is <b>08:00 PM</b>!
<hr>
</body>
</html>

As you can see above, you are even able to include HTML tags in the text string which defined the date format.

The #include virtual command
There are occasions when SSI includes and SSI variables cannot achieve the dynamic content you want, but you still don't want to go to the trouble of writing a CGI program to generate the entire page content. By using the #include virtual command, you can include the output of a program within your existing HTML page(s). The #include vitual command is followed by the name of your script.
<!--#include virtual ="/dir/filename" -->

One example would be to have SSI call a CGI program that would print out a message to the page that called it.

Example: Call a PERL CGI that prints out "Hello There!"

#!/usr/bin/perl
# this file is named "sample.pl"
print "Hello There!\n";
# ----end of file----------------------------

Here is the HTML including the SSI code which calls the CGI.
<HTML>
<HEAD>
<TITLE>Example SSI<&/TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
Here is a example that uses SSI.
<P>
<!--#include virtual="sample.pl"-->
<P>
</BODY>
</HTML>

A Final Note on the #set Command
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.

Example File : title.shtml:
<!-- requires title -->
<!-- Imagine this is a complicated table -->
<!-- which puts the title at the top of -->
<!-- the page in a standard fashion. -->
<html>
<head>
<title><!--#echo "title"--></title>
</head>
<body bgcolor=#ffffff>
<table bgcolor=#f0f0c3 cellspacing=4>
<tr>
<td>
<font size=+3>
<!--#echo "title"-->
</font>
</td>
</tr>
</table>
</body>
</html>

Then we could use this complex standard title in a document "About SSI" as follows:
<!-- Set title, and include standard document header -->
<!--#set var="title" value="About SSI"-->
<!--#include file="title.shtml"-->
            Document body goes here.
<!-- We'd probably do the footer in the -->
<!-- same way, but for now we'll just -->
<!-- terminate the html manually. --> 

Using the #set command allows the reuse of 'components' of HTML and is extremely useful in large web-site design.

Troubleshooting

If you are having problems with development or questions on syntax, we recommend you visit one of the following pages:

 

• http://en.wikipedia.org/wiki/Server_Side_Includes

 

Primus cannot provide general technical support for SSI development, but we will support you if the problem is potentially with the Webserver.