Server-side includes: an example

Hello, browser "" from host "" at IP number on .

The document you are viewing is "." Its Web address is http://, and it was last modified on . The size of the file is bytes.

The information in the preceding two paragraphs was dynamically generated. If you reload the page after a minute, you will see the time change. If you load the page on a different day, from a different location, with a different browser, the first paragraph will be modified appropriately. As you can imagine, there are some advantages in having Web pages that interact with the user in this way.

How is this done? If you use the "View Source" feature of your browser, you will be no wiser, because the Web server is actually interpreting the code in the page before it sends the information to your browser.

In the ordinary course of events, when you click on a link to a Web page, the host server simply ships off the contents of the page to your Web browser, which is then responsible for formatting the information and displaying it. However, the technique of "Server-Side Includes" makes the host computer of the Web page pre-process the information before sending it off to the client browser.

On the computers in the Department of Mathematics at Texas A&M University, server-side includes are enabled in a limited way for files that end in the special extension .html (rather than the usual .html). The source code that produced the first dynamic paragraph above looks like this:

Hello, browser "<!--#echo var="HTTP_USER_AGENT"-->" from host "<!--#echo var="REMOTE_HOST"-->" at IP number <!--#echo var="REMOTE_ADDR"--> on <!--#config timefmt="%A, %B %e, %Y at %l:%M %p"--> <!--#echo var="DATE_LOCAL"-->.

The server recognizes each string of characters between the delimiters <!--# and --> as a special instruction to be interpreted before sending the page off to the browser. For example, the line <!--#echo var="HTTP_USER_AGENT"--> says to insert ("echo") the value of the environment variable HTTP_USER_AGENT into the file. (This variable holds the name of the Web browser that requested the page, so it has a value like "Mosaic," or "Mozilla," or "Lynx.")

The string <!--#echo var="DATE_LOCAL"--> says to insert the current date and time, formatted in a certain way as specified by the instruction <!--#config timefmt="%A, %B %e, %Y at %I:%M %p"-->. For example, %A designates the day of the week, and %Y designates the year. The date and time format specification parameters are the ones used by the Unix strftime command, which you can read about in the Unix manual pages by executing the command man strftime in a terminal window.

The code for the second dynamically generated paragraph above looks like this:

The document you are viewing is "<!--#echo var="DOCUMENT_NAME"-->." Its Web address is http://<!--#echo var="SERVER_NAME"--><!--#echo var="DOCUMENT_URI"-->, and it was last modified on <!--#config timefmt="day %w of week %W of year %y of the 20th century at %T"--> <!--#echo var="LAST_MODIFIED"-->. The size of the file is <!--#config sizefmt="bytes"--> <!--#fsize virtual="../math696/server-side.html"--> bytes.

The variables DOCUMENT_NAME, SERVER_NAME, and DOCUMENT_URI, and LAST_MODIFIED are self-explanatory. The line fsize virtual calls for the size of the file specified by the given virtual path (relative to the server root). The code config sizefmt="bytes" specifies that the size of the file be returned in bytes; the alternative sizefmt="abbrev" gives the file size rounded to the nearest kilobyte.

Exercise

Use server-side includes to put a line on your home page saying "This page last updated on ..." with the date automatically generated.

Note: since your home page might be either index.html or index.html, it is preferable to cite the URL of your home page as simply /~your.name/. The server will then automatically choose whichever of index.html and index.html is available.

It is common to put a "last-modified" date on each Web page, because it is helpful to people browsing the pages to let them know if the information is current. In principle, you could use server-side includes to generate last-update information for all your pages, but the extra work for the server tends to slow down delivery of pages to browsers. If you use emacs as your editor, you might like to try the html-helper-mode package, which can time-stamp your pages automatically every time you edit them.

In principle, the technique of server-side includes could be employed to execute any program on the host via the exec feature, but this feature is usually turned off by the system administrator for security reasons.