Server Side Includes Tutorial

What are server-side includes? Put simply, they are server commands that are embedded into HTML files. Ordinarily, if you want something to show up on your webpage you must write it manually into your HTML file. But what if you want something that is always changing, say the current date, to be reported when a user loads your page? These are commands that are run on the server's side that are included in the HTML document when a remote user requests them.

"Server-parsed HTML" is the general term in which these directives are included. It is important to remember that the actual HTML file does not change--only the information sent to the remote client is dynamic. The physical HTML file remains the same with all of the SSI directives intact.

The SSI Directives

Each directive has the following format:

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

Here is a breakdown of the most useful commands and their associated tags:

#config timefmt

This configures the custom formatting of time and date reporting. Ordinarily, the date/time is returned in the following format:

Thursday, 30-Jan-2003 11:42:22 CST
This is a perfectly acceptable report of the local date and time, but for many aesthetic reasons, is often inappropriate for certain documents. Here are some alternative ways one can report the local date and time, even separately:
Date: Thursday, January 30 2003
timefmt string used: <!--#config timefmt="%A, %B %d %Y"-->

Time: 11:42 AM
timefmt string used: <!--#config timefmt="%I:%M %p"-->

Date/Time: 30 Thu 03, 11:42
timefmt string used: <!--#config timefmt="%e %a %y, %H:%M"-->

Here is a table of values that can be used in the string of this directive. All values are preceded by a % so that they are not confused with actual letters in the formatting:

  a   Displays the locale's abbreviated weekday name (Sun to Sat or the non-
English equivalent).

A Displays the locale's full weekday name.

b Displays the locale's abbreviated month name.

B Displays the locale's full month name.

c Displays the locale's appropriate time and date representation.

C Displays the locale's century (the year divided by 100 and truncated to
an integer) as a decimal number (00 to 99).

d Displays the day of month as a decimal number (01 to 31).

D Displays the date in the format mm/dd/yy

e Displays the day of the month as a decimal number (1 to 31 in a 2-digit
field with leading space fill).

H Displays the hour as a decimal number (00 to 23).

I Displays the hour as a decimal number (01 to 12).

j Displays the day of year as a decimal number (001 to 366).

m Displays the month of year as a decimal number (01 to 12).

M Displays the minute as a decimal number (00 to 59).

n Inserts a newline character.

p Displays the locale's equivalent of either AM or PM.

r Displays the time (12-hour clock) using AM/PM notation (or the non-
English equivalent) in the format hh:mm:ss AM or hh:mm:ss PM.

S Displays the second as a decimal number (00 to 61).

t Inserts a tab character.

T Displays the time in 24-hour clock format as hh:mm:ss

u Displays the weekday as a decimal number [1,7], with 1 representing
Monday.

U Displays the week number of the year (Sunday is the first day of the
week) as a decimal number (00 to 53).

V Displays the week number of the year (Monday as the first day of the
week) as a decimal number (01 to 53). If the week containing January 1
has four or more days in the new year, then it is considered week 1;
otherwise, it is week 53 or the previous year, and the next week is
week 1.

w Displays the day of the week as a decimal number (Sunday = 0).

W Displays the week number of the year (Monday is the first day of the
week) as a decimal number (00 to 53).

x Displays the locale's appropriate date representation.

X Displays the locale's appropriate time representation.

y Displays the last two numbers of the year as a decimal number (00 to
99).

Y Displays the full year as a decimal number.

Z Displays the time zone name, or no characters if the time zone cannot
be determined.

#include file

#include file will insert the text of a document into the parsed document. The pathname relative to the current directory-- ../ cannot be used in this pathname, nor can absolute paths be used.

Example:
  <!--#include file="doc/disclaimer.txt"-->
would include the contents of the file "disclaimer.txt" in the subdirectory "doc" at the place where this tag occurred.

#echo var

#echo var prints the value of one of the include variables (defined below). Any dates are printed subject to the currently configured timefmt .

Environment variables:

  • DOCUMENT_NAME : The current filename.
  • DOCUMENT_URI : The virtual path to this document (such as /academics/foo/classes.html).
  • DATE_LOCAL : The current date, local time zone. Subject to the timefmt parameter to the config command.
  • DATE_GMT : Same as DATE_LOCAL but in Greenwich mean time.
  • LAST_MODIFIED : The last modification date of the current document. Subject to timefmt like the others.

#echo flastmod

This is almost the same as #echo var="LAST_MODIFIED" except that #echo flastmod="file" prints the last modification date of the specified file in quotes.


Frequently-used applications of SSIs.

Reporting the last time a file was changed

This is accomplished with #echo flastmod or #echo var="LAST_MODIFIED"

You could type the following at the end of any HTML document:
   <!--#flastmod file="whateveryourfilenameis.html"-->
and the date/time (as per anything you've set up in the #config timefmt parameter, if defined) the last time the file was modified will be reported.

Reporting the current URL

Some people like to have the current URL for any page included on the document. They usually just type out "http://www.uh.edu/~userid/myurl.html" into their html files. But what if those documents move? Say you decide that another directory is a better location for a particular group of files? You'll have to edit all of that manually--unless you used SSIs to report the current URL. The relevant directive is:
   <!--#echo var="DOCUMENT_URI"-->
So to correctly report your URL on the UH Central Server, the following text will be replaced with the your current URL:

http://www.uh.edu<!--#echo var="DOCUMENT_URI"-->

Including a footer in your html document

Say you wanted to have a standard footer on every page, much like you can do with a word processing package. You can edit every HTML file and include the information you want, but what if something needs changing? For example, what if your contact information changes? You'd have to edit ALL of your HTML files.

That is, unless your footer text was located in another file. If you were to have <!--#include file="footer.html"--> on every page, all you would have to do is change the contents of "footer.html" and all the pages that reference it would be "updated" dynamically! (Tip: consider a combination of all these SSI applications in your footer; all .html documents can contain SSIs regardless of how they are called)

For more information on SSIs, go to NCSA's tutorial. (Note: Not all SSI features are implemented on www.uh.edu for various reasons.)