SSI Handler

MIME Types: text/x-server-parsed-html

Methods: GET, HEAD

Priority: 10

Suggested Virtual Resources:

• VRes: pattern="*.shtml" type="text/x-server-parsed-html" real=true;
  Any file ending with .shtml will be processed by the SSI Handler.

The SSI Handler (Server Side Includes) will parse the specified shtml document and inline the output from any SSI commands found in the document. This provides a powerful mechanism for creating dynamic html pages. Parsing shtml documents is not as fast as calling the file handler to transfer a document, and having many shtml documents may impact the performance of a heavily loaded server.

SSI commands take the form of html comments. This prevents them from being displayed should the document ever end up in the hands of a client unparsed. Each SSI command has the following format:

<!--#command tag1=value1 tag2=value2 ... -->

• config - Configure the output of other commands.

  Tags:

• errmsg - Error message to be inlined when a command could not be completed. The default error string is "SSI Parse Error"
• timefmt - The format to be used for all commands which display a time. The format is the same as is accepted by the strftime() call in the standard C library. The default format is "%a, %d %b %Y %H:%M:%S"
• sizefmt - The format to be used for displaying file sizes. This is a printf() formatting string. The file size is a long int. Make sure your format is for a long int or you may crash the server! The default format is "%ld"
• echo - Print the output of one of the SSI Environment Variables. The only tag supported, "var", can have the following values.
• DOCUMENT_NAME - The name of the current document.
• DOCUMENT_URI - The virtual path of the current document.
• QUERY_STRING_UNESCAPED - The query string from the URI.
• DATE_LOCAL - The local time formatted by config:timefmt.
• DATE_GMT - GMT Time formatted by config:timefmt.
• LAST_MODIFIED - The last modification date of this file formatter by config:timefmt.
• include - Include the contents of another file. If the other file has a MIME type of "text/x-server-parsed-html" it will be parsed as well. Virtual Resources are NOT checked when determining the MIME type of the included file. If SSI is executed recursively by the include command, the recursed document's echo command will display the information for the calling document. If you wish to ensure the Virtual Resources are checked first and/or would like the sub-document echo command to display its own document information, SSI documents can be included recursively with the "exec cgi=..." command. Keep in mind that using "exec cgi=..." is not as efficient as the include command. Make sure a document does not recursively include itself. This would be a VERY bad thing!

  Tags:

• file - The tag-value is an absolute path.
• virtual - The tag-value is a virtual path. ( The root is the Webroot for the specified virtual host. )
• fsize - Display the size of the file specified by the tag. It is formatted based on config:sizefmt. The tags are the same as for the include command.
• flastmod - Display the last modification date of the file specified by the tag. It is formatted based on config:datefmt. The tags are the same as for the include command.
• exec - Execute a program and inline the output of the program.

  Tags:

• cmd - Execute the shell command specified in the tag value and inline its output.
• cgi - The standard behaviour of the cgi tag is to inline the output of the specified CGI. The SSI handler actually makes a request to the module roster to handle the request. This means Virtual Resources will be checked before handling the request. It can actually get any resource which the module roster can retrieve. It could be a CGI, another SSI, a directory listing, a file, or a redirect. If a redirect is returned, an html anchor of the form <A HREF="location"> will be inlined. The SSI handler will only inline the output if the MIME supertype of the returned resource is "text". This makes sure that, for example, the contents of a GIF image are not inlined.
• html - If this tag has a value of "true" and is placed before a cgi tag, only the body of the returned HTML document will be included. This tag is ignored if the cgi request is some other type of text other than HTML (text/plain for example). The parsing required to do this takes additional time. Only use it if you need it!

BeOS is a registered trademark of Be Inc.