Server Side Includes

Server-Side Includes (SSI) let you insert dynamically generated data such as the current date, external files, and the output of programs into the returned document.
SSIs were originally developed for the early NCSA server.
They are supported by Apache and many other servers.

SSI implementations

SSI implementations are server-specific.
SSI is a convention, not a standard.
Documentation applicable to wyrd.hood.ed is at Apache module mod_include and A Tutorial

File naming conventions

Servers are configured to look for SSIs only in files with specified extensions.
On wyrd, SSI files to be parsed by the server must have the extension .shtml.
Other systems may use different extensions.
Notice that most of the page URLs of these course materials show the .shtml file extension.
If your file does not have the correct extension, it will be sent directly to the client without the substitutions being made.

SSI command syntax

A SSI command is written in the form:

       <!--#command attribute="value" attribute="value" ... -->

It is formatted like an HTML comment, so if you don't have SSI enabled, the browser will ignore it, but it will still be visible in the HTML source.
If you have SSI correctly configured, the directive will be replaced with its results.
The leading <!--#command may not contain any whitespace.
There should be whitespace preceding the terminating -->.

SSI commands

echo: print variables
include: include a file
fsize: print size of a file
flastmod: print last modification time of a file
config: configure output formats
printenv: print all available variables
exec: execute external programs
set: set a value of a variable
: (Links are to Apache manual entries)

Standard variables

The echo command just emits the value of a variable.
There are several standard variables.

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.

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

Monday, 16-Sep-2024 14:52:35 EDT

`file` and `virtual` attributes.

The file and virtual attributes provide the location of a file for use with the #include,#flastmod, and #fsize commands.
The value of file is a path relative to the directory containing the current document being parsed.
For Apache, the file attribute value cannot contain ../or begin with a slash.
So on wyrd you cannot include files that are outside of the document root, or above the current document in the directory structure with file.
For wyrd, the virtual attribute should always be used in preference to file.
The value of virtual is a URL-path.
If it does not begin with a slash (/) then it is taken to be relative to the current document.

The `#include` element

This command inserts the text of another document or file into the parsed file.
The location of the document to be included is given by a file or virtual attribute value.

Example 1

   <head>
       <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
       <title>Demonstration of Server Side Includes</title>
   </head>

   <body>
   <h1>Demo of Server Side Includes</h1>
   
   <h2>Some of the commands</h2>
   
   <p>This file name: <!--#echo var="DOCUMENT_NAME" --></p>

   <p>Local date: <!--#echo var="DATE_LOCAL" --></p>
   <p>GMT date: <!--#echo var="DATE_GMT" --></p>
   <p>This file last modified: <!--#echo var="LAST_MODIFIED" --> </p>

   <p>This file's size: <!--#fsize file="ssi_example1.shtml" --> </p>
   <p>Other file last modified: <!--#flastmod virtual="plugin.txt" --> </p>
   <p>Other file's size: <!--#fsize file="plugin.txt" --></p>

   
   <h2>An included file</h2>
   <p>The following lines are contained in the file plugin.txt.</p>
   <!--#include virtual="plugin.txt" -->

   <h2>Execute a CGI script:  </h2> 
   <p>The script is in a separate .cgi file</p>   
   <div style="white-space: pre;">

   <!--#exec cgi="script1.cgi" -->
   </div>


   
   </body>
   </html>

Directory containing example files. The example is saved with three different extensions - .shtml, .html, and .txt. Only the .shtml one has the commands executed.

Example 2

If an included file also has the extension .shtml, commands it it will be executed too.

   <body>
   <h1>Demo of Included Server Side Includes</h1>
   
   <p>The following content comes from executing commands stored in the file more.shtml.</p>

   
   <!--#include virtual="more.shtml" -->
   
   </body>

The included file more.shtml:

    <p>Echoed values are for the requested document, which is not necessarily the one containing the command.</p>
  
   Its name is <!--#echo var="DOCUMENT_NAME" --> <br />
   It was last modified <!--#echo var="LAST_MODIFIED" --> </p>

Directory containing the example files.

Building sites with SSI

The common components of the pages, such as headings, navigation menus, and footers, are saved separately and included in each page.

Example (uses SSI)

File main.shtml

<!--#include virtual="head.txt" -->

    <title>More SSI: Main page</title>
    <!-- Custom style -->
    <style type="text/css">
        h1 {background: yellow; color:red;}
    </style>

<!--#include virtual="nav.txt" -->

<h1>Welcome to SSI demo</h1> 


<p>This is the home page</p>

<!--#include virtual="foot.txt" -->

File second.shtml

<!--#include virtual="head.txt" -->

    <title>More SSI: Second page</title>
    <!-- Custom style -->
    <style type="text/css">

        h1 {background: cyan; color:maroon;}
    </style>

<!--#include virtual="nav.txt" -->

<h1>Continued SSI demo</h1> 

<p>This is the second page</p>

<!--#include virtual="foot.txt" -->

File head.txt

<!DOCTYPE html>
<htmllang="en">

<head>
 <meta charset ="utf-8">

File nav.txt


</head>
<body>

<hr>
<pre><a href="main.shtml">HOME PAGE</a> |  <a href="second.shtml">SECOND PAGE</a></pre>

<hr>
<hr>

File foot.txt

<hr />
<p>Foot Foot Foot Foot Foot </p>

</body>
</html>

Directory containing the files for example 3.

Advantage

Supports modularization - pages can have several standard components, such as headers, footers & sidebar menus, and each page can include customized versions.

Disadvantage

Although there is only one copy of each included file, the #include statements are repeated many times, which could lead to errors (such as typographical errors) and inefficiencies (for example, if the name of an included file is changed, all the statements will have to be changed).

Comments to: dong@hood.edu

Last Modified: 31 July 2015. 17:57

IT581: Practicum in Web Development, Summer 2015 (Hybrid)