Server-side includes allow you to add information to CGI programs and HTML documents that the server sends to the client when acting as an origin server (that is, not to proxied or cached objects). The current date, the size of a file, the date of last change to a file are examples of the kind of information that can be sent to the client. This section describes the command format for server-side includes and explains how to make server-side include commands work in your CGI programs and HTML documents. You can also use server-side includes to customize error pages.
Before using server-side includes on your server, consider performance, security, and risk issues:
To enable server-side includes, in the Configuration and Administration forms, select Server Configuration -> Basic Settings. Use this form to specify which of the following types of server-side includes are acceptable:
Use this form also to specify whether to do server-side include processing for text or HTML documents in addition to other file types.
In addition, ensure that the file extension that you use for the include is recognized. In the Configuration and Administration forms, select Server Configuration -> MIME Types and Encoding, and use the MIME Types form. Note that the shtml and htmls extensions are recognized by default.
To configure your server for server-side includes by editing the directives in the proxy configuration file, see the reference sections for the following directives:
Include commands must be included in the HTML document or CGI program as comments. The commands have the following format:
<!--#directive tag=value ... --> or <!--#directive tag="value" ... -->
The quotation marks around values are optional, but they are required in order to embed spaces.
This section explains the directives that are accepted by the server for server-side includes. (Do not confuse these directives with the directives for the proxy configuration file, which are documented in Appendix B. Configuration file directives.)
config--control file processing
Use this directive to control certain aspects of file processing. Valid tags are cmntmsg, errmsg, sizefmt, and timefmt.
Example:
<!--#config cmntmsg="[This is a comment]" --> <!-- #echo var=" " extra text -->
Result: <!--[This is a comment] extra text -->
Default: [the following was extra in the directive]
Example:
<!-- #config errmsg="[An error occurred]" -->
Default: "[An error occurred while processing this directive]"
Example 1:
<!--#config sizefmt=bytes --> <!--#fsize file=foo.html -->
Result: 1024
Example 2:
<!--#config sizefmt=abbrev --> <!--#fsize file=foo.html -->
Result: 1K
Default: "abbrev"
Example:
<!--#config timefmt="%D %T" --> <!--#flastmod file=foo.html -->
Result: "10/18/95 12:05:33"
Default: "%a, %d %b %Y %T %Z"
The following strftime() formats are valid with the timefmt tag:
Specifier | Meaning |
---|---|
%% | Replace with % |
%a | Replace with the abbreviated weekday name |
%A | Replace with the full weekday name |
%b | Replace with the abbreviated month name |
%B | Replace with the full month name |
%c | Replace with the date and time |
%C | Replace with the century number (year divided by 100 and truncated) |
%d | Replace with the day of the month (01-31) |
%D | Insert the date as %m/%d/%y |
%e | Insert the month of the year as a decimal number (01-12) (Under C POSIX only, it is a 2-character, right-justified, blank-filled field) |
%E[cCxyY] | If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %EC is mapped to %C) |
%Ec | Replace with the alternative date and time representation |
%EC | Replace with the name of the base year (period) in the alternative representation |
%Ex | Replace with the alternative date representation |
%EX | Replace with the alternative time representation |
%Ey | Replace with the offset from %EC (year only) in the alternative representation |
%EY | Replace with the full alternative year representation |
%h | Replace with the abbreviated month name (the same as %b) |
%H | Replace with hour (23-hour clock) as a decimal number (00-23) |
%I | Replace with hour (12-hour clock) as a decimal number (00-12) |
%j | Replace with the day of the year (001-366) |
%m | Replace with the month (01-12) |
%M | Replace with minute (00-59) |
%n | Replace with a new line |
%O[deHlmMSUwWy] | If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %Od is mapped to %d) |
%Od | Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading zeroes if there is any alternative symbol for zero, otherwise with leading spaces |
%Oe | Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading spaces |
%OH | Replace with the hour (24-hour clock), using the alternative numeric symbols |
%OI | Replace with the hour (12-hour clock), using the alternative numeric symbols |
%Om | Replace with the month, using the alternative numeric symbols |
%OM | Replace with the minutes, using the alternative numeric symbols |
%OS | Replace with the seconds, using the alternative numeric symbols |
%OU | Replace with the week number of the year (Sunday as the first day of the week, rules corresponding to %U), using the alternative numeric symbols |
%Ow | Replace with the weekday (Sunday=0), using the alternative numeric symbols |
%OW | Replace with the week number of the year (Monday as the first day of the week), using the alternative numeric symbols |
%Oy | Replace with the year (offset from %C) in the alternative representation and using the alternative numeric symbols |
%p | Replace with the local equivalent of AM or PM |
%r | Replace with the string equivalent to %I:%M:%S %p |
%R | Replace with time in 24-hour notation (%H:%M) |
%S | Replace with seconds (00-61) |
%t | Replace with a tab |
%T | Replace with a string equivalent to %H:%M:%S |
%u | Replace with the weekday as a decimal number (1-7), with 1 representing Monday |
%U | Replace with the week number of the year (00-53), where Sunday is the first day of the week |
%V | Replace with the week number of the year (01-53), where Monday is the first day of the week |
%w | Replace with the weekday (0-6), where Sunday is 0 |
%W | Replace with the week number of the year (00-53), where Monday is the first day of the week |
%x | Replace with the appropriate date representation |
%X | Replace with the appropriate time representation |
%y | Replace with the 2-digit year number within the century |
%Y | Replace with the full 4-digit year number |
%Z | Replace with the name of the time zone or no characters if the time zone is unknown |
The operating system configuration determines the full and abbreviated month names and years.
echo--display variable values
Use this directive to display the value of environment variables specified with the var tag. If a variable is not found, a (None) is displayed. Also, echo can display a value set by the set or global directives. The following environment variables can be displayed:
Example:
<!--#echo var=SSI_DIR -->
exec--specify CGI programs
Use this directive to include the output of a CGI program. The exec directive discards any HTTP headers that the CGI outputs except for the following:
cgi--specify CGI program URL
Use this directive to specify the URL of a CGI program.
In this example, program is the CGI program to be executed, and path_info and query_string represent one or more parameters passed to the program as environment variables:
<!--#exec cgi="/cgi-bin/program/path_info?query_string" -->
This example shows the use of variables:
<!--#exec cgi="&path;&cgiprog;&pathinfo;&querystring;" -->
flastmod--display date and time document was last changed
Use this directive to display the last date and time the document was changed. The formatting of this variable is defined by the config timefmt directive. The file and virtual tags are valid with this directive, and their meanings are defined as follows.
Directive formats:
<!--#flastmod file="/path/file" --> <!--#flastmod virtual="/path/file" -->
<!--#flastmod file="/path/file" -->
<!--#flastmod virtual="/path/file" -->
Example:
<!--#flastmod file="foo.html" -->
Result: 12May96
fsize--display file size
Use this directive to display the size of the specified file. The formatting of this variable is defined by the config sizefmt directive. The file and virtual tags are valid with this directive, and their meanings are the same as defined previously for the flastmod directive.
Example:
<!--#fsize file="/path/file" --> <!--#fsize virtual="/path/file" -->
Result: 1K
global--defines global variables
Use this directive to define global variables that can be echoed later by this file or by any included files.
Example:
<!--#global var=VariableName value="SomeValue" -->
For example, to reference a parent document across the virtual boundary, you need to set a global variable DOCUMENT_URI. You also need to reference the global variable in the child document. This example shows the HTML coding you need to insert in the parent document:
<!--#global var="PARENT_URI" value=&DOCUMENT_URI; -->
This example shows the HTML coding you need to insert in the child document:
<!--#flastmod virtual=&PARENT_URI; -->
include--includes a document in output
Use this directive to include the text from a document in the output. The file and virtual tags are valid with this directive, and their meanings are the same as defined above for the flastmod directive.
set--set variables to be echoed
Use this directive to set a variable that can be echoed later, but only by this file.
Example:
<!--#set var="Variable 2" value="AnotherValue" -->
While defining a directive, you can echo a string in the middle of value. For example:
<!--#include file="&filename;" -->
Variables: A server-side set directive is generally followed by an echo directive, so that it looks for the set variable, echoes where the variable is found, and proceeds with the function. It can contain multiple references to variables. Server-side sets also allow you to echo a variable already set. If a set variable is not found, nothing is displayed.
When a server-side set encounters a variable reference inside a server-side include directive, it attempts to resolve it on the server side. In the second line of the following example, the server-side variable &index; is used with the string var to construct the variable name var1. The variable &var1; is then assigned a value by escaping the & in ê so that it is not recognized as a variable. Instead, it is used as a string to create the value frêd, or fred with a circumflex over the e. The variable ê is a client-side variable.
<!--#set var="index" value="1" --> <!--#set var="var&index;" value="fr\êd" --> <!--#echo var="var1" -->
Characters that can be escaped (called escaped variables) are preceded with a backslash (\) and include the following:
Character | Meaning |
---|---|
\a | Alert (bell) |
\b | Backspace |
\f | Form feed (new page) |
\n | New line |
\r | Carriage return |
\t | Horizontal tab |
\v | Vertical tab |
\' | Single quotation mark |
\" | Double quotation mark |
\? | Question mark |
\\ | Backslash |
\- | Hyphen |
\. | Period |
\& | Ampersand |