Home > Guardian Error Handling System > Help > 1024

Customizing HTML: Using server-side includes

All of the Guardian templates accept include files using the following syntax:

<!--#include virtual="/path/to/file.txt" -->
<!--#include file="/path/to/file.txt" -->

If your website layout is already based on included headers and footers, you can simply customize the main "template.txt" template with those same include statements. Then your error pages will automatically match the layout of the rest of your site.

This feature is designed to make it easy to include simple, text-based include files. There are several limitations that prevent this feature from being used for more complex tasks, and they are listed below.

Path Limitations

The template-parser for this script resides in the current working directory of:

	guardian/data/en

When a #include link is found, the script will begin searching the file system for a file with the matching name, starting it the current working directory. Up to 12 parent folders will be searched.

For example, assume that Guardian is installed to "e:/webroot/guardian" and the site's web root is "e:/webroot". Guardian encounters the link:

<!--#include virtual="/shared/footer.txt" -->

The template parser will look in the following folders for the file "footer.txt":

e:/webroot/guardian/data/en/shared/footer.txt
(the current-directory plus the literal path)

e:/webroot/guardian/data/en/../shared/footer.txt
 == e:/webroot/guardian/data/shared/footer.txt

e:/webroot/guardian/data/en/../../shared/footer.txt
 == e:/webroot/guardian/shared/footer.txt

e:/webroot/guardian/data/en/../../../shared/footer.txt
 == e:/webroot/shared/footer.txt

The fourth attempt will locate the file.

Note that Guardian is not aware of the URL-to-folder mappings of the server, and so it cannot directly locate the file in the same way that the web server can. This may cause Guardian to sometimes include the wrong file, or to sometimes not find an existing file.

Executable Limitations

Most web servers will process script files that are included, like:

<!--#include virtual="/banner-ad.asp" -->

The include parser with this script cannot parse script files. In the case above, the literal source code of the script would be included, instead of the output from interpreting the script.

(Actually, that is what would happen if the parser tried to include that file. In practice the parser would skip the above #include because it is aware of its own limitations with ASP files.)

File Extension Limitations

To help alleviate the problem with including script content, and to help keep the system more secure, include files will only be processed if they have one of the following extensions:

txt|htm|html|shtml|stm|inc|css

Other SSI Tags

The following includes will also work:

<!--#echo var="LAST_MODIFIED" -->
# prints the last-modified date and time for the script file (not the template file)

<!--#echo var="DATE_GMT" -->
# prints the date and time, in the GMT time zone

<!--#echo var="DATE_LOCAL" -->
# prints the date and time, in the local time zone

<!--#echo var="DOCUMENT_NAME" -->
# prints the base filename of the script, i.e. 'ag.pl'

<!--#echo var="DOCUMENT_URI" -->
# prints the path and filename of the script, i.e. '/guardian/ag.pl'

<!--#echo var="var" -->
# if $ENV{'var'} is defined, will print it
# do *not* use this to echo raw user-defined variables like
# CONTENT_LENGTH, QUERY_STRING, HTTP_*, etc., since that will
# create an XSS security hole  :(

Here is some example SSI calls that have been used to customize the error output:

<p>Your attempt has been logged:</p>

<p>IP Address: <!--#echo var="REMOTE_ADDR" --></p>

<p>URL: %ErrorURL%</p>

Advanced

Template-parsing is handled by the ParseTemplate subroutine which is defined in library file guardian/ag-shared.txt. You can customize that subroutine to give it any behavior that you want.

Handling of "echo var" SSI calls is modeled after the Apache mod_include specification; see http://httpd.apache.org/docs/mod/mod_include.html. Vars supported are DATE_GMT, DATE_LOCAL, LAST_MODIFIED, DOCUMENT_URI, DOCUMENT_NAME, and all standard environment variables (SERVER_SOFTWARE, HTTP_USER_AGENT, HTTP_REFERER, REMOTE_ADDR, etc.)

SSI elements "config", "exec", "fsize", "flastmod", "printenv", "set" are ignored (passed through to output - other filters may capture and execute them). Only "include" and "echo" are handled.


    "Customizing HTML: Using server-side includes"
    http://www.xav.com/scripts/guardian/help/1024.html