Manual Reference Pages  - HTTPD_SSI (7)

NAME

httpd_ssi - Server Side Includes (SSI) for xs-httpd

CONTENTS

Description
     Content directives
     Control directives
See Also

DESCRIPTION

One of the advanced features of this WWW server is its server side includes. Server side includes (SSIs) are "commands" to the server to do something. These may be embedded in HTML documents.

The general format of such a directive is as follows: name is the name of the directive. Options may sometimes be omitted. Option and argument pairs should be separated each other nd from the command name by a single space. If the argument contains spaces or other special characters (such as the equals sign), it must be contained in double quotes ("). Note also that a directive must start and end on the same line. You may have other things on that line, including other directives.

When the server sends a HTML document to the remote client, it will parse all of the directives that are embedded in that document. The following directives are recognized:

    Content directives

<!--# count-total -->
  This directive inserts the number of times that this page has ever been retrieved. You may use counters as many times as you wish per page, they will only increment once.

<!--# count-month -->
  This directive inserts the number of times that this page has been retrieved this month.

<!--# count-today -->
  This directive inserts the number of times that this page has been retrieved today.

<!--# count-total-gfx[location-->]
  This directive inserts a HTML tag to include a graphical representation of the number of times that this page has ever been retrieved. If location is specified, it will be used as a base location for the font. A font has 10 digits in it, each in a separate file, all PPM’s. Say location is /~user/font1/, and digit 1 is needed, then /~user/font1/1.ppm will be used as that digit. Three standard fonts are supplied with this WWW server. They may be accessed using the locations: /fonts/digital (which is the default), /fonts/large and /fonts/largecol.

<!--# count-month-gfx[location-->]
  This directive inserts a HTML tag to include a graphical representation of the number of times that this page has been retrieved this month. See above for location.

<!--# count-today-gfx[location-->]
  This directive inserts a HTML tag to include a graphical representation of the number of times that this page has been retrieved today. See above for location.

<!--# count-reset -->
  This directive resets all counters for this page to 0.

<!--# date[format= conv-spec-->]
  This directive inserts the current date and time, optionally in your own format. The conversion specification conv-spec must be in strftime(3) format.

<!--# date-format format= conv-spec -->
  This directive sets format as the new date and time format. You must specify the format in strftime(3) format.


.Brq Cm none Ns No | Ns Cm html Ns No | Ns Cm url Ns No -->

 
.Brq Cm none Ns No | Ns Cm html Ns No | Ns Cm url Ns No -->
 
.Brq Cm none Ns No | Ns Cm html Ns No | Ns Cm url Ns No -->
  Print the value of a variable. This can be a local variable that was set using the set directive, or an CGI environment variable that was set by the webserver. If the envvar option is used, only CGI environment variables are searched.

The optional encoding= argument defaults to html encoding. Selecting none will do no rewriting at all and is therefore useful in text/plain files. Selecting html replaces special html symbols (such as <’ and &’) to the appropriate sgml entities for proper display. Selecting url encodes any non alphanumeric characters with their %xx’ equivalent.

<!--# include file = file -->
<!--# include-file file -->
  This directive allows you to include file in this document. This is very useful for standard headers and footers. Note that included files may be nested and that directives are parsed in them. Note also that counters and such always count the original file, so you can use the count directives in your standard headers and footers. The argument can be an absolute path ( /home/username/.html/file.html), a virtual path relative to the user’s html directory ( /~username/file.html) or a relative path ( file.html).

<!--# include binary = file -->
<!--# include virtual = file -->
  By default included files are handled as if they are standard HTML documents. This means these are interpreted as text and SSI directives inside these files will be parsed as well. Special handling can be selected using the binary or virtual argument.

Binary files are copied directly: without SSI handling or other special (text) parsing taking place. Virtual files are handled as if these were separate webserver (GET) requests: full parsing is done and it is even possible to call CGI binaries which will be interpreted as well this way.

<!--# last-mod[file-->]
<!--# last-modified[file-->]
  This directive inserts the last modification date of either the originally request file (the current document) or the optionally specified file. The date will be in the format specified by the date-format directive.

<!--# run-cgi cgi -->
  Runs the CGI binary cgi and inserts its output at this point. Standard PATH_INFO and PATH_TRANSLATED parsing is done, so you can give arguments to the CGI binary. All standard CGI environment variables will be set up appropriately. See httpd_cgi(7) for more details on CGI’s.

The CGI pathname must be given in URL syntax, the same way as the local part of a full URL. The path may not be omitted: The arguments will be made available through the QUERY_STRING environment variable. For example Quotes are important here to guarantee proper parsing. Without these the path might be interpreted as a command, value pair.

echo directive. The variables can also be accessed from other files that are processed during the same request.

Variable names or values may contain spaces if this value is enclosed in double quotes, e.g.

set in combination with include can be used for example to create a common header file for inclusing, in which only the title changes. This title can then be printed with echo. Another useful method is to have set in combination with if -statements in an included file, for instance to generate a common menu file in which the selected entry is displayed distinctively. Alternatively, variables may also be set in the included file and then used in the main document.

    Control directives

<!--# if keyword pattern[pattern ...-->]
<!--# if-not keyword pattern[pattern ...-->]
  The if and if-not directives try to match the value associated with the given keyword against the set of patterns. If any pattern matches or in the case of if-not if no pattern matches the section until the next matching else or endif is parsed. Otherwise when a matching else directive is encountered the section up to the matching endif directive is parsed. Patterns are simple case-insensitive wildcard patterns.

The following keywords are recognized:

var= varname
envvar= varname
  Use the requested variable or CGI environment variable to check against the given pattern(s).

For backwards compatibility reasons the following keyword aliases are also recognized:

browser
  Alias for envvar= USER_AGENT
remote-host
  Alias for envvar= REMOTE_HOST
remote-name
  Alias for envvar= REMOTE_HOST
remote-addr
  Alias for envvar= REMOTE_ADDR

<!--# else -->
  This directive optionally separates the code for the true and the false evaluation of the corresponding checking (i.e. if or if-not) directive. If there is no else directive between the checking directive and the corresponding endif directive nothing will be evaluated when the check fails.

<!--# endif -->
  This directive closes a conditional section started by an if or if-not directive.

<!--# switch keyword -->
  The switch directive tries to find a corresponding case directive with a matching pattern before the corresponding endswitch directive. If a matching case directive is found the code following this case up to the next corresponding case directive or the next corresponding endswitch directive.

<!--# case pattern[pattern ...-->]
  The case directive starts the section to parse if any of its patterns matches the keyword from the corresponding switch.

<!--# endswitch -->
  This directive closes a conditional section started by the corresponding switch directive.

SEE ALSO

httpd(1), httpd_cgi(7)

The project homepage: http://www.xs-httpd.org/


May 9, 2007 HTTPD_SSI (7) xs-httpd/3.5