Using SSI and Filters

| iMatix home page
| Xitami home page
| << | < | > | >>

Xitami
Version 2.4d7

Using SSI and Filters

Xitami supports filter programs in Perl, C, or any other language that your system supports. A filter program runs when the HTML page is displayed, unlike a CGI program, which runs when the user posts data from a HTML form. Xitami provides a standard SSI filter (PerlSSI) which requires a Perl interpreter. This is not meant for heavy-duty work, but is a good example of a filter. (We intend to develop a fast SSI module that will be embedded into the server directly.) Another example of a filter program is PHP 3.0, which Xitami supports.

To add your own filter programs, you add an entry in the [Filter] section of the config file. A filter program is invoked whenever a file with the appropriate extension is displayed.

Filter programs need to respect the rules for CGI programs. That is, they should generate the same type of header (Content-Type: text/html). Filter programs also get the standard CGI environment, and are subject to the CGI timeouts and other constraints set in the [CGI] section.

When you POST to a filter program, the form data is supplied on the standard input as for CGI programs. When you use the GET method, the file that is being filtered is provided on the standard input.

The SSI Filter

SSI (server-side includes) is a fairly standard syntax which you can read about on the NCSA site. We implemented all the common SSI tags in the PerlSSI filter. To use this, you need Perl on your system (it should be on the PATH). The PerlSSI filter is slow, and meant as a work-around until we implement SSI the correct way, in the server itself. The PerlSSI filter is located in the Xitami directory itself. To run it, you must have Perl installed. The requirements for this filter are the same as for a Perl CGI program.

By default, Xitami recognises any document with extension '.ssi', '.shtm', or '.shtml' as an SSI document. This is defined in the [Filters] section of the configuration files.

The SSI documents are placed in the normal web pages directory, and are recognised purely by their extension, not the path.

Xitami supports these SSI tags:

Element syntax: Effect:

#config errmsg="text" Specify the SSI error message.
#config sizefmt="format" Specify whether file sizes are shown in full, or abbreviated. Use the format 'abbrev' to show abbreviated sizes.
#config timefmt="format" Specify the format used for file times. By default this is: "%A, %d-%b-%y %H:%M:%S %Z". Note: the current implementation of SSI ignores the timefmt, and always uses the default time format.
#echo var="variable" Output the value of the specified variable. Xitami recognises these variables: DOCUMENT_NAME, DOCUMENT_URI, DATE_GMT, DATE_LOCAL, LAST_MODIFIED, and any environment variable (including the standard CGI environment variables).
#exec cgi="pathname" Outputs the result of the CGI program, which must be in the CGI binary directory (it cannot be on a CGI alias directory). Note that the CGI program runs in the main Xitami directory.
#exec cmd="command" Executes a native command and includes the output of this command. Note that the command runs in the main Xitami directory. This SSI command - which is a potential security risk for your system - is only accepted if the environment variable SSI_INSECURE is set to 'yes'. (Under Windows NT, in the System Control Panel, under 'Environment'; under Windows 95 by adding 'SET SSI_INSECURE=yes' to the autoexec.bat.)
#include virtual="filename" Includes the contents of the specified URI, which is assumed to be within the webpages root. Note that aliases are not supported in the current implementation.
#include file="filename" Includes the contents of the specified file, which may be anywhere in the file system space.
#flastmod {virtual|file}="filename" Outputs the time that the specified file was last modified. The file can be a URI within the webpages root, or an absolute filename, depending on whether 'virtual' or 'file' is specified.
#fsize {virtual|file}="filename" Outputs the size of the specified URL or file, using the sizefmt.

Element syntax:	Effect:
#config errmsg="text"	Specify the SSI error message.
#config sizefmt="format"	Specify whether file sizes are shown in full, or abbreviated. Use the format 'abbrev' to show abbreviated sizes.
#config timefmt="format"	Specify the format used for file times. By default this is: "%A, %d-%b-%y %H:%M:%S %Z". Note: the current implementation of SSI ignores the timefmt, and always uses the default time format.
#echo var="variable"	Output the value of the specified variable. Xitami recognises these variables: DOCUMENT_NAME, DOCUMENT_URI, DATE_GMT, DATE_LOCAL, LAST_MODIFIED, and any environment variable (including the standard CGI environment variables).
#exec cgi="pathname"	Outputs the result of the CGI program, which must be in the CGI binary directory (it cannot be on a CGI alias directory). Note that the CGI program runs in the main Xitami directory.
#exec cmd="command"	Executes a native command and includes the output of this command. Note that the command runs in the main Xitami directory. This SSI command - which is a potential security risk for your system - is only accepted if the environment variable SSI_INSECURE is set to 'yes'. (Under Windows NT, in the System Control Panel, under 'Environment'; under Windows 95 by adding 'SET SSI_INSECURE=yes' to the autoexec.bat.)
#include virtual="filename"	Includes the contents of the specified URI, which is assumed to be within the webpages root. Note that aliases are not supported in the current implementation.
#include file="filename"	Includes the contents of the specified file, which may be anywhere in the file system space.
#flastmod {virtual\|file}="filename"	Outputs the time that the specified file was last modified. The file can be a URI within the webpages root, or an absolute filename, depending on whether 'virtual' or 'file' is specified.
#fsize {virtual\|file}="filename"	Outputs the size of the specified URL or file, using the sizefmt.

With a small knowledge of Perl, you can easily modify the Perlssi filter to add support for other tags.