(rahul.net)
Demonstration page: server-side includes

This web page has been set up to provide examples of the use of server-side includes. The URL of this page is: http://www.rahul.net/ssidemo/. From the UNIX shell you may see this page in the directory /mi/home/ssidemo/www . Once you reach that directory you will find this web page in the file index.shtml .

The full documentation for the Apache web server may be found at this URL: http://mauve.rahul.net/manual/index.html. The documentation for the syntax of lines that use server-side includes may be found at this URL: http://mauve.rahul.net/manual/howto/ssi.html. Note: Not every feature described in the above manuals is available here.

Server-side includes are active for any document whose name ends with .shtml . Special directives in the file will be processed by the web server before it is sent to the web client requesting it.

Some features (primarily program execution from within server-side includes) are available, by special request, to Premium customers only.

Example: Local time

You may include the local time at San Jose, California into your document with code like this:


	<strong>
        Local time is <!--#echo var="DATE_LOCAL" -->.
	</strong>

The result looks like this in the final document:

Local time is Sunday, 07-Apr-2013 16:43:02 PDT.

Reload this page in your web browser to see the timestamp change.

A Definition: Virtual Path

For use in examples below, we will define the virtual path of a web document or program as follows. First, find any full URL by which we can access the document; for example, consider this URL for a cgi-bin program: http://www.rahul.net/cgi-bin/ssidemo/printalpha.sh . From this URL, delete the http: part and the domain name part. What is left is the string /cgi-bin/ssidemo/printalpha.sh, and we will call this the virtual path of this cgi-bin program.

Here is another example, for a regular document. Consider the URL http://www.rahul.net/ssidemo/somefile.txt . Again, from this URL, delete the http: part and the domain name part. What is left is the string /ssidemo/somefile.txt . Again, this is the virtual path of this document.

A virtual path looks like a UNIX pathname, but is not exactly the same as one, because it begins at the web server's root directory and not at the filesystem root directory.

Example: Simple file inclusion

Simple file inclusion means that your web page may incorporate the contents of any other file. If the original file contains these lines:


	<strong>
        Included text coming up:
        <!--#include virtual="somefile.txt" -->
	... done.
	</strong>

Then the contents of 'somefile.txt' will be included at the point where the #include virtual is done. You already saw the contents of 'somefile.txt' if you followed the link to it, in the section where we defined virtual paths. The same text, taken from inside somefile.txt, will be automatically included into this document due to the #include virtual line. Here is the final result:

Included text coming up: I am somefile.txt, and the rest of me has the alphabet: abcdefghijklmnopqrstuvwxyz ... done.

The filename used in the #include virtual directive may be a simple filename in the same location as the document that includes that file, as in the example above. Or it may be a pathname relative to the location of that document, e.g., 'subdira/subdirb/somefile.txt'. Or it may be the virtual path of the document, as we defined it above.

Don't use a full URL, including the http: part or the domain part, in an #include line -- it won't work. Here is an example that won't work:


<!--#include virtual="http://www.rahul.net/ssidemo/somefile.txt" -->

But a virtual path, like the one shown below, will work:


<!--#include virtual="/ssidemo/somefile.txt" -->

Example: Program execution

Program execution from server-side includes is enabled for Premium customers upon request.

In an #include virtual line, if the filename end with .cgi the web server will assume it is a program to be executed, and will include the output from that program into the including file. Also, if the pathname corresponds to the virtual path of any cgi-bin program, program execution will occur, without the .cgi suffix being required. Here are some examples.

Suppose we have a little shell script like this:


        #! /bin/sh
        # This is the shell script 'printalpha.cgi'
        echo 'Content-type: text/plain'
        echo ''
        echo 'printalpha.cgi says:  abcdefghijklmnopqrstuvwxyz'

Let's use the following lines in our document:


	<strong>
        Include the result of program execution here:
        <!--#include virtual="printalpha.cgi" -->
	... done.
	</strong>

Here is the output in the final document:

Include the result of program execution here: [an error occurred while processing this directive] ... done.

Here is an example of a program being invoked from our cgi-bin directory, without needing the .cgi suffix in its name. We will put the executable program printalpha.sh in our cgi-bin directory ~aftp/pub/ssidemo/cgi. Its normal cgi-bin URL will then be http://www.rahul.net/cgi-bin/ssidemo/printalpha.sh . Its pathname for use in server-side includes is its virtual path, which is /cgi-bin/ssidemo/printalpha.sh .

The lines in our document are:


	<strong>
        Include the result of program execution here:
        <!--#include virtual="/cgi-bin/ssidemo/printalpha.sh" -->
	... done.
	</strong>

Here is the final output:

Include the result of program execution here: [an error occurred while processing this directive] ... done.

Passing arguments to cgi-bin programs

We can also pass any desired arguments to a cgi-bin program, simply by appending a question mark and the URL-encoded arguments. Here is a quick example. More details than this are beyond the scope of this document.


        <!--#include virtual="/cgi-bin/ssidemo/myprog?arg1&arg2&arg3" -->

To a2i communications home page