Home > Fluid Dynamics Search Engine > Help > 1024

Customizing HTML: Parsing Server-Side Includes (SSI)

Include files are excellent tools for managing web content. FDSE provides limited support for them.

As an example of include support, the "header.htm" template for each language uses an SSI call to inline the text of the "style.inc" file.

SSI parsing is done with the PrintTemplate function. PrintTemplate will attempt to properly handle include files. Because it is ignorant of the mappings between URL paths and file system paths, this code is somewhat error prone. However, I believe it will function for the majority of users and those users will find it very helpful.

Below are acceptable server-side include formats. These must match exactly - no freedom in whitespace is allowed:

<p>The script was modified on: <!--#echo var="LAST_MODIFIED" -->.</p>
<p>Hello world: <!--#include virtual="file.txt" -->.</p>
<p>Hello world: <!--#include file="file.txt" -->.</p>

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.)

The latter two examples indicate that the user wants to replace the SSI call with the literal contents of "file.txt". Let's say our current working directory is "./searchdata" (or whatever $DataFilesDir is), and the language is set to "english". We search for the file "file.txt" in this order:

	"./searchdata/templates/english/file.txt"
	"./searchdata/templates/english/../file.txt"
	"./searchdata/templates/english/../../file.txt"
	"./searchdata/templates/english/../../../file.txt"
	"./searchdata/templates/english/../../../../file.txt"
	...

Up to 12 parent paths will be searched. Note that this is equivalent to searching:

	"./searchdata/templates/english/file.txt"
	"./searchdata/templates/file.txt"
	"./searchdata/file.txt"
	"./file.txt"
	"../file.txt"
	...

If "file.txt" if found, its contents will be read and inserted into the document where the SSI call was, and the search process will stop. The text contents will also be recursively searched for any SSI calls, and PrintTemplate will attempt to resolve those as well. Any %replace_values will also be handled.

There is the risk of infinite looping, i.e. "foo.txt" includes "bar.txt" which includes "foo.txt" which includes "bar.txt" which... To avoid this, if PrintTemplate has already included some file named "file.txt", then it will not include another one named "file.txt", even though they may be in different directories. This is because PrintTemplate is generally ignorant of its own absolute path, and so it cannot resolve the absolute path of the target file, and since it never wants to risk including the same file twice, it errs on the side of caution.

SSI parsing will fail under these scenarios:

These failures arise because:

These reasons are fundamental and cannot be (generally) overcome with current software. The only way to overcome this is to have CGI execution operate beneath the include-processing filter. Currently web servers seem to send content either to the include parser or to the Perl parser, not both.


    "Customizing HTML: Parsing Server-Side Includes (SSI)"
    http://www.xav.com/scripts/search/help/1024.html