Using Server Side Includes at Martnet
A brief primer on how to set up server side includes.
Using Server
Side Includes
Simply put, a Server Side Include is a command
placed inside the HTML code, which is then read by our Web Server
and run whenever someone calls up the Web Page. A Server Side
Include can be used to embed the output of a CGI program (such
as a hit counter) into a page, call external files (such as a
common "footer" file) and include it in a page, and
put the date and time the page was last modified on the page.
There are many other possibilities, and you can use multiple commands
to create truly dynamic pages.
Enabling Server-Side Includes
To use Server Side Includes in any Web Page
hosted at MartNet, you MUST end your html file names with the
suffix .shtml (ie. index.shtml)
If you do not end your html file names with .shtml suffix,
our Web Servers will not parse the document or read and execute
your Server Side Include commands! There is nothing more you need
to do to use Server Side Includes with your MartNet Hosted Web
Site!
Some Common Uses plus sample code
Note that Server Side Includes usually
expect a path to a file, NOT
a URL(as in http://www...) as part
of the command.
- Calling a CGI
- The following code Embeds a CGI (such
as a hit counter) in a page, with the CGI's output displayed
as part of the page:
A User-installed CGI:
A publically available
CGI (Fortune Teller):
-
-
Displaying document information
- The following code puts the document modification
date and time on the page:
Last modified:
-
Adding text (such as a footer) to many documents
- Add the following text to one or many
documents: (view the source
of this page for an example. The MartNet Support Site heavily
uses this Server Side Include command, with shared header and
footer files, to make managing and updating the site as easy
as possible.)
-
Hide links from external users
- Use the if command and the REMOTE_ADDR
CGI variable to see if the user is in the local domain:
- (Where 1.2.3 is the IP address prefix
of the local domain).
Other resources:
Apache mod_include Documentation We proudly use Apache
Web Servers here at MartNet, and this page contains the original
Server Documentation for the mod_include Apache module, the little
piece of software that makes Server Side Includes actually work.
A lot of the content on this page was copied from this documentation,
and this page contains technical information for those interested
in how everything works on the Server end.
NCSA Tutotial on Server Side Includes NCSA came up with the Server Side Include standard
a long time ago, and this basic turorial explains the technical
nitty-gritty of how it all works.
Apache Week - Using Server Side Includes a short, not-quite-so-technical article on using
Server Side Includes to enhance your Web Site. The Apache Week
Web Site contains a lot of additional information that may interest
serious Web Developers, and help you take advantage of the advanced
features of the Apache Web Server.
Basic
Elements and Command Syntax
Note: the following section was taken
from the Apache Web Server Documentation, and throughly explains
the use and command syntax of available Server Side Include commands.
We have modified it slightly so that it accurately reflects the
features available on our Web Servers. The original document is
available
Here.
The document is parsed as an HTML document,
with special commands embedded as SGML comments. A command has
the syntax:
The value will often be enclosed in double
quotes; many commands only allow a single attribute-value pair.
Note that the comment terminator ( --> ) should
be preceded by whitespace to ensure that it isn't considered part
of an SSI token.
The allowed
elements are:
- config
- This command controls various aspects
of the parsing. The valid attributes are:
-
- errmsg
- The value is a message that is sent back
to the client if an error occurs whilst parsing the document.
-
- sizefmt
- The value sets the format to be used which
displaying the size of a file. Valid values are bytes
for a count in bytes, or abbrev for a count in Kb
or Mb as appropriate.
-
- timefmt
- The value is a string to be used by the
strftime(3) library routine when printing dates.
-
echo
- This command prints one of the include
variables, defined below. If the variable is unset, it is printed
as (none). Any dates printed are subject to the
currently configured timefmt. Attributes:
-
- var
- The value is the name of the variable
to print.
-
exec
- The exec command executes a given shell
command or CGI script. This command is obselete, and has been
replaced by the include command. The exec
command will not work on MartNet's Web Servers (it has
been intentionally disabled for security reasons) and is included
here only for the sake of completeness.
-
-
fsize
- This command prints the size of the specified
file, subject to the sizefmt format specification.
Attributes:
-
- file
- The value is a path relative to the directory
containing the current document being parsed.
-
- virtual
- The value is a (%-encoded) URL-path relative
to the current document being parsed. If it does not begin with
a slash (/) then it is taken to be relative to the current document.
-
flastmod
- This command prints the last modification
date of the specified file, subject to the timefmt
format specification. The attributes are the same as for the
fsize command.
-
include
- This command inserts the text of another
document or file into the parsed file. Any included file is subject
to the usual access control. If the directory containing the
parsed file has the Option IncludesNOEXEC set, and the
including the document would cause a program to be executed,
then it will not be included; this prevents the execution of
CGI scripts. Otherwise CGI scripts are invoked as normal using
the complete URL given in the command, including any query string.
An attribute defines the location of the
document; the inclusion is done for each attribute given to the
include command. The valid attributes are:
-
- file
- The value is a path relative to the directory
containing the current document being parsed. It cannot contain
../, nor can it be an absolute path. The virtual
attribute should always be used in preference to this one.
-
- virtual
- The value is a (%-encoded) URL relative
to the current document being parsed. The URL cannot contain
a scheme or hostname, only a path and an optional query string.
If it does not begin with a slash (/) then it is taken to be
relative to the current document.
A URL is constructed from the attribute,
and the output the server would return if the URL were accessed
by the client is included in the parsed output. Thus included
files can be nested.
-
printenv
- This prints out a listing of all existing
variables and their values. No attributes.
- For example:
- Apache 1.2 and above.
-
set
- This sets the value of a variable. Attributes:
-
- var
- The name of the variable to set.
-
- value
- The value to give a variable.
For example:
- Apache 1.2 and above.
Include Variables
In addition to the variables in the standard
CGI environment, these are available for the echo
command, for if and elif, and to any
program invoked by the document.
- 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 then URL for the current document.
-
- LAST_MODIFIED
- The last modification date of the document
requested by the user.
Variable Substitution
Variable substitution is done within quoted
strings in most cases where they may reasonably occur as an argument
to an SSI directive. This includes the config, exec,
flastmod, fsize, include,
and set directives, as well as the arguments to conditional
operators. You can insert a literal dollar sign into the string
using backslash quoting:
If a variable reference needs to be substituted
in the middle of a character sequence that might otherwise be
considered a valid identifier in its own right, it can be disambiguated
by enclosing the reference in braces, à la shell
substitution:
This will result in the Zed
variable being set to "X_Y" if REMOTE_HOST
is "X" and REQUEST_METHOD
is "Y".
EXAMPLE: the below example will print "in
foo" if the DOCUMENT_URI is /foo/file.html, "in bar"
if it is /bar/file.html and "in neither" otherwise:
in foo
in bar
in neither
Flow Control Elements
The basic flow control elements are:
The if element
works like an if statement in a programming language. The test
condition is evaluated and if the result is true, then the text
until the next elif, else.
or endif element is included in
the output stream.
The elif or
else statements are be used the
put text into the output stream if the original test_condition
was false. These elements are optional.
The endif
element ends the if element and
is required.
test_condition
is one of the following:
- string
- true if string is not empty
- string1
= string2
string1 != string2
string1 < string2
string1 <= string2
string1 > string2
string1 >= string2
- Compare string1 with string 2. If string2
has the form /string/ then it is compared as a regular
expression. Regular expressions have the same syntax as those
found in the Unix egrep command.
- ( test_condition )
- true if test_condition is true
- ! test_condition
- true if test_condition is false
- test_condition1
&& test_condition2
- true if both test_condition1
and test_condition2 are true
- test_condition1
|| test_condition2
- true if either test_condition1
or test_condition2 is true
"=" and "!="
bind more tightly than "&&" and "||".
"!" binds most tightly. Thus, the following
are equivalent:
Anything that's not recognized as a variable
or an operator is treated as a string. Strings can also be quoted:
'string'. Unquoted strings can't contain whitespace (blanks
and tabs) because it is used to separate tokens such as variables.
If multiple strings are found in a row, they are concatenated
using blanks. So,
string1 string2 results in string1 string2
'string1 string2' results in string1 string2

This Web Site is proudly built upon an Open Source foundation:
Home
| Services
| Support
| Members
| Software
| Contact
|