DragonFly On-Line Manual Pages
HTTPD_SSI(7) DragonFly Miscellaneous Information Manual HTTPD_SSI(7)
NAME
httpd_ssi - Server Side Includes (SSI) for xs-httpd
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 opt=arg [opt=arg ...]-->
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 PPMs. 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.
<!--#echo varname [encoding={none|html|url}]-->
<!--#echo var=varname [encoding={none|html|url}]-->
<!--#echo envvar=varname [encoding={none|html|url}]-->
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 CGIs.
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:
<!--#run-cgi /~username/cgi-bin/file-->
The arguments will be made available through the QUERY_STRING
environment variable. For example
<!--#run-cgi "/~username/cgi-bin/file?foo=bar&foo=baz"-->
Quotes are important here to guarantee proper parsing. Without
these the path might be interpreted as a command, value pair.
<!--#set varname=value [varname=value ...]-->
Set one or more internal variables with given names and values.
These variables can later be printed using the 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 title="Hello World"-->
set in combination with include can be used for example to create
a common header file for inclusion, 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/
xs-httpd/3.5 May 9, 2007 xs-httpd/3.5