Webmaster's Guide to Server Side Includes

Have you ever wanted to add the same content to hundreds of Web pages and not have to change each page individually? Or perhaps you've wanted your site to have different style sheets for different browsers or directories, but you can't think of a quick way to do it. Or maybe you just wanted to make your site a little more dynamic but don't want to get into all the intricacies of CGI or ASP. If you've wished for any these things, this article is for you.

We begin with an introduction to server side includes, or SSI. For those of us most acquainted with SSI, we simply call them includes. SSI allow you to display and act upon environment variables and include external files in your HTML pages when displayed in a browser. In addition, SSI can control the content and style of your HTML pages conditionally with if/else logic. In short, SSI are directives you can include in an HTML page. The directives are quite simple to write. Understanding what is going on behind the scenes isn't too difficult to understand either. If you include SSI in yourpage.html and yourpage.html is requested by a browser, your server will retrieve yourpage.html, parse the SSI and then send the page back to the requesting browser.

SSI are a feature of some Web servers, like Apache for example. A common misconception is that *all* Web servers allow the use of SSI. If your Web server is lucky enough to have SSI, the Web server needs to have SSI enabled, usually requiring a small edit to the configuration files. Moreover, when you enable SSI, you instruct the Web server to parse SSI directives only in files of a certain type. Usually, people instruct the Web server to only look for include directives (not the SSI) in files with a .shtml extension. If you instruct the Web server to look for includes in files with an .html extension, then your Web server will do exactly that. This will affect your Web server's performance to some degree by slowing down the download time for each HTML page. Thus, you need to decide if almost all of your HTML pages are going to have SSI or only a few of them. In addition, the amount of time your HTML pages are slowed down depends on the complexity of the SSI you write.

Syntax

The syntax for a server side include directive is:

<!--#command parameter="argument" -->

Each directive requires a parameter and each parameter takes an argument. There are six server side include commands, namely: include, echo, config, exec, flastmod and fsize.

Perhaps the most important command is the include command. The include command allows you to include an external file in an HTML page. For example, you could save an embedded style sheet in an included file like so:

<STYLE TYPE="text/css">
<!--
  .include font{ font-size: 75%; font-family: verdana,  
   arial, helvetica;}
  .include A:link { color: blue; }
  .include A:visited { color: purple; }
   pre.code {color: #660099; margin-left:5%}
   address {text-align: right}
-->
</STYLE>

You could then save the above SSI, which is also an embedded style sheet as stylesheet.html. If you save stylesheet.html in the same directory as the HTML pages you want stylesheet.html to work with you can place the directive:

<!--#include file="stylesheet.html" --> 

in the HTML pages you want stylesheet.html to be contained in.

However, if you save stylesheet.html in a different directory than the HTML pages you want this stylesheet.html to affect, you can use the more general:

<!--#include virtual="/directory_name/stylesheet.html"-->

In general, the virtual parameter allows you to place include directives in any HTML file regardless of its location relative to the file that's included.

Using Environment Variables

The echo command is also very useful. You can use echo to output any of the CGI environment variables in addition to six environment variables specific to SSI, which are listed below.

• DATE_GMT: holds date and time in GMT
• DATE_LOCAL: holds date and time in local time zone
• DOCUMENT_NAME: holds the current filename
• DOCUMENT_URI: holds path of file from server root to filename
• LAST_MODIFIED: holds last modification date and time for current file
• QUERY_STRING_UNESCAPED: holds unaltered query string with all shell metacharacters escaped with a "\".

So, in accordance with the list above, the include directive below will output the date the HTML page containing the directive was last modified.

<!--#echo var="LAST_MODIFIED" -->

With the exec command, you can place the output of a program in an HTML page. The exec command takes two parameters: cmd for any application and cgi for a CGI script. The syntax for the exec cgi directive is basically the same as other include directives. Here's an example:

<!--#exec cgi="/cgi-bin/some_cgi_program.cgi" -->

In this example the output of some_cgi_program.cgi from the directory cgi-bin will be included in any HTML file with the above directive.

The other three include commands follow the same grammar. The fsize command outputs the size of a file. You could even use the fsize command to output the size of one HTML page in another HTML page. The config command is useful for changing the server side include error message, and for formatting time and file size information. The flastmod command is useful for displaying the last time any file was modified.