Using server-side includes

The Options Line

        Options Includes

FollowSymLinks

This option tells httpd that symbolic links should be followed when they are encountered. Unless you're using symbolic links in your Web directories, it doesn't really matter if you turn this on or not.

Indexes

This option tells httpd that if it is given a directory name as a URL to access, and there is no file called Index.html in that directory, it should generate a nifty little index of its own, with little icons that represent the different file types. If this option is turned off and httpd is given a directory URL to access, it will say that the URL cannot be accessed. If you want this behavior, you should turn this option on.

        Options FollowSymLinks Indexes Includes

The AddType Line

The line you use to tell httpd what files to examine looks like this:

        AddType text/x-server-parsed-html .suffix

When httpd accesses a file whose name ends in the suffix(es) you have chosen, it will examine the file to see if it contains server-side includes. If the file name does not end in the suffix(es) you have chosen, httpd will just send the file back to the browser without looking at its contents.

        AddType text/x-server-parsed-html .shtml

This has one disadvantage, however. The Purdue ECN httpd configuration says that the default file to access when a directory is given as a URL is called Index.html. So, personal home pages and departmental home pages all end in the suffix .html. If you rename them such that they end in .shtml, then httpd will no longer consider them the default page to access. If you plan to use server-side include files in your personal or departmental home page, you'll have to use this line in your .htaccess file:

        AddType text/x-server-parsed-html .html

Playing Tricks With .htaccess Files

There are two important features of .htaccess files, however, that can help us get around this problem:

1. A .htaccess file applies to the directory it is contained in and all subdirectories of that directory that do not contain .htaccess files themselves.
2. Options specified in a .htaccess file override any options that were specified in either the system-wide configuration file or a .htaccess file in a higher-level directory.

1. In the top-level directory (either /var/www/htdocs or ~/public-web), create a .htaccess file that turns server-side includes on:

           Options FollowSymLinks Indexes Includes
           AddType text/x-server-parsed-html .html
   

   This will allow you to use server-side includes in the Index.html file.
2. Keep only the Index.html file in the top-level directory. Put all other files in a subdirectory of the top-level directory.
3. In the subdirectory, create another .htaccess file, this time with the lines:

           Options FollowSymLinks Indexes Includes
           AddType text/x-server-parsed-html .shtml
           AddType text/html .html
   

   The first line is simply a repeat of the Options line from the .htaccess file in the top-level directory. The second line tells httpd to look for server-side includes in files whose names end in .shtml. At this point, it will now look for server-side includes in both files whose names end in .shtml and files whose names in .html. The third line though, tells the server that files whose names end in .html should be treated as "regular" HTML files (i.e., without server-side includes). This in effect disables the previous setting from the top-level directory.

        Options FollowSymLinks Indexes
	AddType text/html .html

One other thing to remember about .htaccess files -- they apply to the directory they are in and all subdirectories of that directory. Thus, if you have a directory structure like this:

                       ~/public-web
                ____________|___________
               /            |           \
             xx            yy            zz
            /  \          /  \          /  \
           /    \        /    \        /    \
          a      b      c      d      e      f
         / \    / \    / \    / \    / \    / \
        l   m  n   o  p   q  r   s  t   u  v   w

If you place another .htaccess file in xx that turns server-side includes back off, then they are also off in a, b, l, m, n, and o.

This has another ramification -- if you only need server-side includes in a few files, and you don't need them in your homepage, you might consider just turning them on in one subdirectory. For example, if you place a .htaccess file in the d directory that turns server-side includes on, then they will be on only for files in d, r, and s. They'll still be off in all the other directories, and you won't have to worry about the performance problems.

Format of Server-Side Includes

The specific format of a server side include is:

        <!--#command tag="value" tag="value" ... -->

config

Tells httpd how to process other server-side include lines. There are three legal tags:

errmsg

Controls what message is sent back to the client (browser) if an error occurs while parsing the document (i.e., if you screwed up one of the server-side include lines).

timefmt

Controls the format of the date/time strings printed by the echo and flastmod commands. You use the same symbols as are used with the strftime function:

 %a    abbreviated weekday name
 %A    full weekday name
 %b    abbreviated month name
 %B    full month name
 %c    appropriate date and time representation
 %C    date and time representation as produced by date(1)
 %d    day of month ( 01 - 31 )
 %D    date as %m/%d/%y
 %e    day of month ( 1 - 31; single digits are preceded by a space)
 %h    abbreviated month name.
 %H    hour ( 00 - 23 )
 %I    hour ( 01 - 12 )
 %j    day number of year ( 001 - 366 )
 %k    hour ( 0 - 23; single digits are preceded by a blank)
 %l    hour ( 1 - 12; single digits are preceded by a blank)
 %m    month number ( 01 - 12 )
 %M    minute ( 00 - 59 )
 %n    same as \n
 %p    AM or PM
 %r    time as %I:%M:%S [AM|PM]
 %R    time as %H:%M
 %S    seconds ( 00 - 61 ), allows for leap seconds
 %t    insert a tab
 %T    time as %H:%M:%S
 %U    week number of year ( 00 - 53  ), Sunday is the first day of week 1
 %w    weekday number ( 0 - 6 ), Sunday = 0
 %W    week number of year ( 00 - 53  ), Monday is the first day of week 1
 %x    appropriate date representation
 %X    appropriate time representation
 %y    year within century ( 00 - 99 )
 %Y    year as ccyy ( for example 1986)
 %Z    time zone name or no characters if no time zone exists

For example, if you want to print the date as mm/dd/yy and leave out the time, you would say:

        <!--#config timefmt="%m/%d/%y" -->

sizefmt

Controls the format of the size strings printed by the fsize command. Legal values are bytes, for a number formatted like 1,234,567, and abbrev, for a number abbreviated to kilobytes or megabytes as appropriate.

include

Include the named file. The file must contain HTML; you cannot include an image or other type of file. The file can be identified with one of two tags:

virtual

Gives a "virtual path" to a document on the server. This path name should be the same thing you would use in a URL for the file, but leave off the "http:" and the host name.

file

Gives a path name relative to the current directory. You cannot use ".." in this path name, nor can you use absolute path names. This means you can only include files at the current directory level or below.

You cannot access CGI scripts with the include command.

echo

Prints the value of one of a special set of variables. There is only one tag, var, which gives the name of the variable you want to print. You can print any of the variables that are defined for CGI scripts (the ones that are available in the server). You can also print the following variables:

DOCUMENT_NAME

The current document file name.

DOCUMENT_URI

The virtual path to this document (e.g., /~user/foo/bar.shtml).

QUERY_STRING_UNESCAPED

The unescaped version of any search query the client sent, with all shell special characters escaped with a backslash (`\').

DATE_LOCAL

The current date and time in the local time zone. This is printed according to the timefmt parameter of the config command.

DATE_GMT

The current date and time in Coordinated Universal Time (UTC), also called Greenwich Mean Time (GMT). This is printed according to the timefmt parameter of the config command.

LAST_MODIFIED

The last modification date/time of the current document. This is printed according to the timefmt parameter of the config command.

fsize

Prints the size of the specified file. The valid tags are the same as those for the include command. The format of this string is subject to the sizefmt parameter of the config command.

flastmod

Prints the last modification date/time of the specified file. The valid tags are the same as those for the include command. This is printed according to the timefmt parameter of the config command.

exec

Execute a given shell command or CGI script. There are two legal tags:

cmd

Execute the given string using /bin/sh. All of the variables defined for the echo command will be defined in the environment. You can not capture the output of this command and include it in the document.

cgi

Execute the given CGI script (which should be specified as a virtual path) and include any output from it here. The script must output HTML; it can not output images and the like. The server will interpret any URL Location: headers and translate them into HTML anchors. This is not supported on ECN web servers.

CGIs in Anchors -vs- CGIs in Server-Side Includes

When a CGI program is called through an HTML anchor, it is not executed until the user actually clicks on the anchor. If the user ignores the anchor, the program never gets executed. For programs that produce output the user may or may not be interested in, this is quite adequate. And it's more efficient, since the program is only executed when needed.

When a CGI program is called through a server-side include though, it is executed every time a document is accessed. The user running the browser has no choice in the matter; httpd executes the program and includes the output before it's sent back to the user. In fact, the user won't even know a program was executed. This is useful in some situations, but is much less efficient, since the program is executed regardless of whether anyone is going to look at its output. For this reason, the exec server-side include should be used only sparingly, if at all.

Here is an HTML document that demonstrates the difference:

        <HTML><HEAD>
        <TITLE>Finger Test<TITLE>
        </HEAD><BODY>
        Here is Debby's finger information
        called via an HTML anchor:<BR>
        <A HREF="/~debweb/finger.cgi">click here</A>
        <P>
        Here is Debby's finger information
        called via a server-side include:<BR>
        <!--#exec cgi="finger.cgi" -->
        <P>
        </BODY></HTML>