Server-side Includes

			Home
		Server-side Includes

The Sambar Server Server Side include implementation is based on the Apache implementation. Server-side includes allow you to embed commands in an HTML file that are carried out when the document is served to a browser. This functionality is also available using the proprietary Sambar Server tags, which perform considerably than faster, but are non-portable.

Using Server-side includes you can offer dynamically generated data such as the current date or time, include the output of a CGI script in a Web page, or signature files that are appended or prepended to all of your Web pages. All this comes with the cost of additional processing on the server to parse for the SSI directives within the HTML file. For this reason, you must configure the Sambar Server with the file extension that should be processed for Server-side includes; by default, the SSI files must have the extension .shtml. See the Configuration documentation for additional details on configuring or disallowing SSIs.

Server-side includes (SSI) can be configured so that users can execute arbitrary programs on the server (see the #exec command). The Sambar Server allows you to disable the #exec functionality from SSIs or disable SSI functionality all-together by removing the shtml entry from the Server Side Includes = line in the config.ini. This

Warning! Additional SSI extensions can be configured in the config.ini file, but the extension .stm should NOT added as an SSI extension; the .stm extension should only be used for Sambar Server scripting (required for the System administration pages).

SSI Overview

SSIs appear in HTML documents within comment tags, beginning with . The following is the basic format:

where #command is the include command to be executed (see below for a list of supported commands). The following illustrates how to display when the current document was last modified:

Supported Commands

The following is a list of commands and their associated tags:

fsize prints the size of the specified file.
- file gives a pathname relative to the current directory. ../ cannot be used in this pathname (this is enforced by the Sambar Server). If the entire path is specified (i.e. c:/sambar44/docs/foo.dat), the resulting file must be relative to the document directory of the request. To access files in the cgi-bin directory or elsewhere, virtual paths should be used.
- virtual is a (%-encoded) URL relative to the current document being parsed. The URL cannot contain a scheme or hostname, only a path (a query string is not permitted). If it does not begin with a slash (/) then it is taken to be relative to the current document.
  If the file begins with a slash (/), then the included file may be any valid URL (i.e. HTML file, Sambar Server template, shtml file; or even CGI/WinCGI command). It is recommended that all include files have a leading slash (/) and avoid using relative paths.
flastmod prints the last modification date of the specified file (using the default system date/time format). The attributes are the same as for the fsize command.
include
include will insert the text of a document into the parsed document. This command accepts the following tag(s):
- file gives a pathname relative to the current directory. ../ cannot be used in this pathname (this is enforced by the Sambar Server). If the entire path is specified (i.e. c:/sambar44/docs/foo.dat), the resulting file must be relative to the document directory for request. To access files in the cgi-bin directory or elsewhere, virtual paths should be used.
- virtual is a (%-encoded) URL relative to the current document being parsed. The URL cannot contain a scheme or hostname, only a path (a query string is not permitted). If it does not begin with a slash (/) then it is taken to be relative to the current document.
  IMPORTANT! If the file does not begin with a slash (/), it is treated as a standard HTML file and sent uninterpreted.
  If the file begins with a slash (/), then the included file may be any valid URL (i.e. HTML file, Sambar Server template, shtml file; or even CGI/WinCGI command). It is recommended that all include files have a leading slash (/) and avoid using relative paths.
  If the virtual document begins with http:// the request is treated as a remote page request and the content of the remote request is fetched and included in the page.
echo prints the value of one of the include variables (defined below). All dates are printed in the standard Sambar Server date format. The only valid tag to this command is var, whose value is the name of the variable you wish to echo. See the ENV variables sample server-side include form for echo examples.
set sets the value of a variable. The variable can be used for substitution in exec and include directives.
To echo the value of a variable previously set, the variable must be pre-pended with a $ symbol:
exec executes a given CGI or WinCGI script. Valid tags are:
- cgi will execute the CGI script specified by the value. By default, the CGI must be found in the cgi-bin directory and the cgi-win directory will be set to the "working" directory.
- wincgi will execute the WinCGI script specified by the value. By default, the WinCGI must be found in the cgi-win directory and the cgi-win directory will be set to the "working" directory.
cmd will execute the Windows command specified by the value. The working directory is the Sambar Server installation directory.

By default the PATH_INFO and QUERY_STRING of the original request are passed to the cgi/wincgi executable. The specification requires that all parameters to be passed to the CGI script be passed as arguments to the server-side include URL request. The Sambar Server extends this functionality, allowing parameter arguments to be provided to the CGI in the server-side include (see below). Any arguments provided for the CGI will be passed in the QUERY_STRING, over-riding the arguments passed to the original URL.

SSI Environment Variables

The following is a list of variables that are made available to parsed documents (most CGI variables, are also made available):

DOCUMENT_NAME: The current filename.

DOCUMENT_URI: The virtual path to this document (such as /foo/zippy.shtml).

DATE_LOCAL: The current date, local time zone.

DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.

LAST_MODIFIED: The last modification date of the current document in GMT.

LAST_MODDATE: The last modification date of the current document in local time.

All environment variables available in the Sambar Server Scripting language are also available here (i.e. day, hour, document_uri).

Unsupported SSI Commands

The following SSI commands are not supported by the Sambar Server at this time:

config

printenv

if / else / elif constructs

Extending SSI Commands

Server-side include commands may be extended using the Sambar Server DLL interface (sa_cmd_init). See the sample programs included with the Sambar Server for more information.