MartNet Support - Using Server Side Includes at Martnet (A brief primer on how to set up server side includes.)

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 for a count in bytes, or for a count in Kb or Mb as appropriate.

timefmt: The value is a string to be used by the 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 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

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 , . or element is included in the output stream.

The

or statements are be used the put text into the output stream if the original test_condition was false. These elements are optional.

The

element ends the 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: