Quid Pro Quo provides you with the ability to embed server commands into your HTML documents in the form of special HTML tags. When the server processes your document, it will replace these server commands with text appropriate to the function of the tag. This allows you to insert server environment variables such as the server hostname, client address, or hit count. Server Side Includes (SSI) also allows you to insert the contents of an entire separate file, or even the output from a CGI application or script.

SSI commands take the form of special HTML comments. Typically, HTML comments are passed on to the client browser, which processes the file, ignoring the comments. An HTML comment looks like:

<!-- This is a comment -->

To force Quid Pro Quo to recognize an SSI command, it must be embedded in a comment. For instance:

<!--#echo var="SERVER_NAME"-->

When processed, Quid Pro Quo will replace the entire comment/command with the hostname of the server.

To use SSI, you must first configure Quid Pro Quo to recognize SSI files. In the Configure dialog, select the MIME Mappings panel. Quid Pro Quo is pre-configured to use the file suffix .shtml for SSI files. If you would like to use another suffix, add it by clicking on the new button. Otherwise, you are ready to go.

Quid Pro Quo recognizes six SSI commands:

The config Command

The config command does not actually insert any text into your HTML document. Rather, it tells Quid Pro Quo how to format the output of the other SSI commands. The config command takes one or two arguments. This is an example of the syntax:

<!--#config timefmt="%A, %B %d, %Y" sizefmt="abbrev"-->

The second argument, abbrev, is the simpler of the two. You can set it to one of two values. "abbrev" tells Quid Pro Quo that when inserting the size of a file, use the number of kilobytes. "bytes", as the name suggests, uses the number of bytes instead. This argument is useful if you will be using the fsize command.

The timefmt argument is somewhat more complicated. C programmers will recognize it as the "fmt" argument to the strftime standard library call. If you are not a C programmer, it indicates the format of the date and time output of the echo and flastmod command. It has a number of possible values. When used in combination, these values indicate how to print a date. These values are:

So the example config command:

<!--#config timefmt="%A, %B %d, %Y" sizefmt="abbrev"-->

Would format the date as:

Monday, September 12, 1996

The default format is "%I:%M %p %A, %B %d, %Y" You do not need to specify both the timefmt and sizefmt. Specifying only one at a time is also valid. So,

<!--#config timefmt="%A, %B %d, %Y"-->
<!--#config sizefmt="abbrev"-->

are both valid commands. You may issue the config command multiple times in the same document, in order to get different formats in different parts of the document.

The echo Command

The echo command allows you to insert text into your HTML document. When Quid Pro Quo encounters the echo command, it replaces the command with the specified value. For example:

<!--#echo var="SERVER_NAME"-->

would be replaced with the hostname of you server, such as "www.yoursite.com". There are a number of different values that can be inserted:

For example, this file:

Hello user at <!--#echo var="REMOTE_HOST"-->! This site has served
<!--#echo var="TOTAL_HITS"--> documents.

would appear something like:

Hello user at netcom.com! This site has served 8365 documents.

on the user's browser.

Quid Pro Quo is not able to specify every variable for every document served. For instance, REMOTE_USER and AUTH_TYPE will only be available in documents that required authorization (that is, those that belong to a realm). In these instances, the command is stripped from the document as usual, but nothing is inserted in its place.

The flastmod Command

The flastmod command allows you to insert the date of the last modification of any file on your site. It works like the echo command's LAST_MODIFIED variable, but with one difference -- flastmod allows to insert the modification date of other files, not just the current document.

flastmod takes one argument, but that argument can take two forms. The syntax is:

<!--#flastmod file="picture.gif"-->

or

<!--#flastmod virtual="/images/picture.gif"-->

The first example uses the "file" argument. In this argument, you specify a file with a path relative to the document containing the flastmod command. In this example "picture.gif" should be in the same directory as the current document.

The second example takes a "virtual" file path as its argument. This path is constructed exactly like a URL for your site is. Thus "/images/picture.gif" is the same file as "http://www.yoursite.com/images/picture.gif".

The format of the date displayed is controlled by the config command. If Quid Pro Quo cannot find the file you have specified in the argument, the command is stripped from the output text, but nothing is inserted in its place.

The fsize Command

The fsize command works like the flastmod command. That is, it allows you to insert information about another file on your web site into the current document. But rather than insert the date of the last modification, fsize inserts the size of the file. The syntax is:

<!--#fsize file="picture.gif"-->

or

<!--#fsize virtual="/images/picture.gif"-->

For an explanation of the "file" and "virtual" arguments see the flastmod command. The number displayed by the fsize command in controlled by the config command. It can display the file size in either bytes or kilobytes.

The exec Command

The exec command is the most powerful of the Quid Pro Quo SSI commands. It allows you to run a CGI application or plug-in and insert its results into the current document. You could also run multiple CGI applications or plug-ins from a single URL. There is no limit to the number of exec calls that you can make in a single document. The syntax is:

<!--#exec virtual="/cgi-bin/mycgi.cgi"-->

Unlike the flastmod and fsize commands, exec only takes a "virtual" file path.

For instance, the file:

Here's the result of a CGI: <!--#exec virtual="/cgi-bin/mycgi.cgi"-->

would result in something like:

Here's the result of a CGI: Hello from the CGI!

When inserting the results of a CGI application or script, Quid Pro Quo strips the HTTP header from the result.

The include Command

The include command allows you to include the contents of a file into the current document. This is particularly useful for including common parts of documents that are identical across multiple documents. For example, say all of your site's pages have a common footer that contains a button bar with links to other documents on your site. If the URL of one of these linked documents changed, you would have to update every document on your site to point to the new URL. An easier way is to use the include command. At the bottom of every page put:

<!--#include virtual="/docs/footer"-->

where "footer" is a file containing the HTML code necessary to display your button bar.

The include command takes one argument, which can be either a "virtual" or "file" argument. See the flastmod command for a description of how to use this argument. If the include command is unable to find the file to be included, it will strip the command from the output text, but will not replace it with anything.


Send questions and comments to me, Chris Hawk

Welcome | Contents | Glossary