Server Side Includes
The most frequent use of SSI is to include the contents of one or more files into a web page on a web server. For example, a web page containing a daily quotation could include the quotation by placing the following code into the file of the web page:
<!--#include virtual="../quote.txt" -->
With one change of the
quote.txt file, all pages that include the file will display the latest daily quotation. The inclusion is not limited to files, and may also be the text output from a program, or the value of a system variable such as the current time.
Server Side Includes are useful for including a common piece of code throughout a site, such as a page header, a page footer and a navigation menu. Conditional navigation menus can be conditionally included using control directives.
In order for a web server to recognize an SSI-enabled HTML file and therefore carry out these instructions, either the filename should end with a special extension, by default
.shtm, or, if the server is configured to allow this, set the execution bit of the file.
As a simple programming language, SSI supports only one type: text. Its control flow is rather simple, choice is supported, but loops are not natively supported and can only be done by recursion using include or using HTTP redirect. The simple design of the language makes it easier to learn and use than most server-side scripting languages, while complicated server-side processing is often done with one of the more feature-rich programming languages. SSI is Turing complete.
SSI has a simple syntax:
<!--#directive parameter=value parameter=value -->. Directives are placed in HTML comments so that if SSI is not enabled, users will not see the SSI directives on the page, unless they look at its source. Note that the syntax does not allow spaces between the leading "<" and the directive.
Most common directives
|include||file or virtual||This is probably the most used SSI directive, allowing the content of one document to be transcluded in another. The file or virtual parameters specify the file (HTML page, text file, script, etc.) to be included. Includes the contents of another file or the result of running a CGI script. If the process does not have access to read the file or execute the script, the include will fail. "virtual" specifies the target relative to the domain root, while "file" specifies the path relative to the directory of the current file. When using "file" it is forbidden to reference to absolute paths. Higher directories (..) are usually forbidden, unless explicitly configured. The Apache documentation recommends using "virtual" in preference to "file".|
Apache tutorial on SSI stipulates the format requires a space character before the "-->" that closes the element.
|exec||cgi or cmd||This directive executes a program, script, or shell command on the server. The cmd parameter specifies a server-side command; the cgi parameter specifies the path to a CGI script. The PATH_INFO and QUERY_STRING of the current SSI script will be passed to the CGI script, as a result "exec cgi" should be used instead of "include virtual".|
|echo||var||This directive displays the contents of a specified HTTP environment variable. Variables include HTTP_USER_AGENT, LAST_MODIFIED, and HTTP_ACCEPT.|
|config||timefmt, sizefmt, or errmsg||This directive configures the display formats for the date, time, filesize, and error message (returned when an SSI command fails).|
|flastmod or fsize||file or virtual||These directives display the date when the specified document was last modified, or the specified document's size. The file or virtual parameters specify the document to use. The file parameter defines the document as relative to the document path; the virtual parameter defines the document as relative to the document root.|
|printenv||This directive outputs a list of all variables and their values, including environmental and user-defined variables. It has no attributes.|
|if||expr||Used for condition tests that may determine and generate multiple logical pages from one single physical page.|
|elif||expr||Serves the same purpose as further conditioning in programming languages.|
|else||If none of the if and elif directive catches the present condition, things in here should happen.|
|endif||See above for example.|
|set||var, value||Sets the value of a SSI variable. (Not supported by all implementations, although present in Apache httpd.)|
- "Configuring your server to permit SSI". Apache Tutorial: Introduction to Server Side Includes. The Apache Software Foundation. Retrieved 24 June 2015.
- "Server Side Includes Turing machine, Jan Schejbal. Retrieved 2010-08-12". Janschejbal.de. Retrieved 2012-12-06.
- "Basic SSI Directives and Syntax". 2018-02-09. Retrieved 2018-02-09.