Server-Side Includes

What are Server-Side Includes?

A server-side include is a type of macro that can be expanded at the time the Web server is sending the document to the browser. Special tags embedded in an HTML document are recognized as instructions to the server to perform a substitution for the tag. The substitution depends on the tag. The supported tags include echo, include, exec, config, fsize, and flastmod. With these tags, another document can be included inline, the output of a script can be included, a file's last modification date and time can be included, and more.

Which Files are Parsed?

All files are not searched for Server-side includes. A slight performance penalty exists for doing this parsing. Only files with a certain content type are parsed before they are sent. This content type is text/x-server-parsed-html. A typical setup (and the default setup) is to have the extensions .SHTML and .SHT map to the content type text/x-server-parsed-html. This means that only files with that extension are parsed for server-side includes.

IFS files, QDLS files, spooled files and database files can all contain server-side includes. The header and footer files for spooled files and database files can also include server-side includes. However, the header and footer files for dynamic indexes will send a server-side include file as a regular HTML file.

Server-Side Include Format

The format of a server-side include is as follows:

<!--#tag parm1="value1" parm2="value2" ... -->

where,

<!--#
These five characters always begin a server-side include. This will hide the command as a comment if the file ends up on a Web server that does not support server-side includes.

tag
The tag indicates the type of server-side include to perform. Valid values are echo, include, exec, config, fsize, and flastmod. Tags are not case-sensitive. Each tag is described below.

parmX="valueX"
Each tag has one or more parameters that are specified as parm="value". If multiple parameters are specified, each is separated by a space. The parameter name is not case-sensitive, but the value might be depending on the parameter and operation.

-->
A server-side include always ends with these three characters.

Example Include

The following document will include the Internet host name of the machine that serves this document. 

<HTML>
<BODY>
This document is being served by <!--#echo var="SERVER_NAME"-->.
</HTML>
</BODY>

Example output:

This document is being served by www.inetmi.com.

Supported Tags

Below is a list of the different operations a server-side include can perform. Each tag and its parameters are described.

ECHO
The echo server-side include is replaced with the value of a pre-defined variable that is specified as a parameter. The only valid parameter is var.

The echo command is used to send the value of several pre-defined variables to the browser. These variables include all the pseudo-environment variables available to script programs and some just available to server-side include documents.

INCLUDE
The include server-side include allows one document to include another document. The main document and its included sub-documents are all sent as one large document to the browser.

Included files can themselves include other files. The level of nesting has no limit. However, circular references are not allowed. For instance, if Document A includes Document B which includes Document A again, an error will occur.

Any type of URL can be included except script URLs. This includes dynamic indexes, database files, user directory files, and spooled files.

The document to include can be specified in one of two ways:

EXEC
The exec server-side include is used to insert the output from a script into a parsed document. Any valid CGI script can be included, however the output of some scripts is not appropriate for inclusion in the middle of another HTML document. For instance, a script might have its own <HEAD> section even though the main document already contains a <HEAD> section.

Any response headers returned by the script are not included in the resulting document, but are still necessary for proper interpretation of the script output.

If the result of the CGI script is a redirection, then a hyperlink to the redirected location is inserted in the document instead of the output of the script.

The only valid parameter to exec is:

CONFIG
The config server-side include is used to configure the behavior of server-side includes. This includes changing the default error message, the time format, and the file size format. Configuration changes take effect immediately and last until the end of the document or until the configuration value is changed again.

FSIZE
The FSIZE server-side include expands to the size of a specified file. The size is displayed as configured by the sizefmt parameter to the config tag.

The target file can be specified in one of two ways:

FLASTMOD
The FLASTMOD server-side include expands to the last modification date and time of a specified file. The last modification date and time are displayed as configured by the timefmt parameter to the config tag.

The target file can be specified in one of two ways: