|
|
What are Server Side Includes?
Server Side Includes (SSIs) are commands that you can include in an HTML file and which instruct the server to do something when it serves the file, such as including the text of a file, executing a CGI, including a timestamp, etc. Basically what happens is that before serving the document to the browser, the server scans through the file and looks for commands in a certain format. Where it sees them, it replaces them with appropriate material.
Since scanning and replacing SSIs requires extra work by the server, many webservers require that such files use an extension other than .html, usually .shtml, so that they don't scan a file for SSIs unless the file extension alerts them that it's necessary. On Panix, you must use either .shtml or .sht.
So how do I use them?
The basic syntax for an SSI in your HTML document is:
<!--#command tag="value"-->
where command can be one of several values, including echo, include and exec. For example, you can use an SSI to echo the environment variable for the browser's computer name by including the following in your document:
<!--#echo var="REMOTE_HOST"-->
Another very useful and very common example is a canned statement which you want included in several documents. This statement might change periodically and it would really be a major pain to edit all the documents including it. You could save yourself a lot of work by putting that statement in a file of its own, perhaps "copyright.txt", and then including the following in all the pertinent documents:
<!--#include file="copyright.txt"-->
You can also cause a script or CGI process to run, and include any text output that it returns. For example, if you have a script called "counter.cgi" which keeps tracks of "hits" on the page and prints the current value, you might use something like the following SSI:
<!--#exec cgi="counter.cgi"-->
or perhaps, for a corporate web user
<!--#exec cgi="/pcgi-bin/counter.cgi"-->
and for a personal web user
<!--#exec cgi="/~userid/pcgi-bin/counter.cgi"-->
You can also use non-CGI scripts, but the syntax is a little different; e.g.:
<!--#exec cmd="/htdocs/userdirs/userid/foo/bar.pl -a -b"-->
or
<!--#exec cmd="/htdocs/corp-dirs/userid/foo/bar.sh -a -b"-->
Two important notes about the difference between calling a CGI and a non-CGI script are that (1) for exec cgi, the path to the script must be relative to webspace root, while for exec cmd, it is relative to the filesystem, and (2) when you use exec cmd you can also pass command-line options (note that the above examples pass two options).
For further information on SSIs, check out the tutorial included in the Apache server documentation:
I'm using the exec SSI to include the output of a CGI script, but nothing shows up.
Just like a regular CGI script, before printing any text that should be included, your script should be sure to print either "Content-type: text/html\n\n" or "Content-type: text/plain\n\n".
I have all these pages with well-known URLs ending in *.html to which I want to add SSIs. What do I do?
It was mentioned above that the Panix Web server automatically parses any *.shtml and *.sht document for SSIs. However, there is a way to force it to parse other documents. What you do is place a .htaccess file in the same directory as the documents you want parsed, or in a directory above. To force the server to parse all the *.html documents in that directory, the contents of .htaccess should read something like:
AddType text/x-server-parsed-html .html