Using web include files and templates on pangea
Last revision August 30, 2011
Table of Contents:
|
The Apache web server on pangea has been configured to support server-side includes. This feature allows the web server to build up a complete web page from pieces. Each piece is written in HTML, but may not be a valid complete page of its own. This allows you to re-use a common piece of code - for example, a navigation bar, or a header, or contact information.
This page, for instance, is built using server-side includes (SSIs). The School of Earth Sciences header, with its standard navigation links, and the navigation menu at the left are both SSIs; they are used over and over in many pages on this web site. Instead of duplicating the HTML code for those features on each page, we simply include them in each page with server-side includes. This allows for easy updating: by changing a single file, we can update the navigation bars of all the pages in the computing section.
You need to have a main page - the one that is referenced as the URL by web browsers - and then one or more pieces that are included in the web page when a browser asks to open the main page. The key idea here is that the included pieces are not actually part of the main page file, and are only included just at the moment when the main page file is opened. The pieces can be modified separately, and those modifications will show up instantly when the main page is opened.
The common pieces that will be included in multiple files are just text files with HTML code; there is nothing unusual about them.
Using server side includes
All HTML pages (.html, .htm, .shtml) on this site can support server-side includes. To use a server-side include, your main page must contain a special "include" directive wherever you want to include another piece of html. This directive has the syntax:
<!--#include virtual="pathname_of_included_piece" -->
You have to replace "pathname_of_included_piece" in this syntax with a Unix style specification of the location of that piece. This does not make a "link" to that file; it actually pulls in the contents of that included file at this exact location in the main page, replacing this special include directive. The resulting source code (as seen by the browser) looks as if the include had been part of the file all along. This merger only occurs as the main page is being read by a browser. The main page on disk is never altered.
The pathname of the included piece tells the server how to find the file containing that piece. It has to refer to another file that pangea can see directly, in other words, a file on an sesfs.stanford.edu file share that has been mounted on pangea, such as your home share or the WWW department/group share. It cannot refer to a file on another web server. You can use either a complete or relative pathname for this included file. Be sure to leave a blank space after this filename and before the --> characters in the include line.
A complete pathname starts with a slash character, and gives all the directories in line that the web server has to traverse to get to the file, starting with the "home directory" of the web site. The web server does not start with the filesystem "root" directory (/), like an ordinary Unix command would, but rather with the home directory of the web site. On pangea, the general web home directory is /WWW. For example, a complete pathname in a server-side include directive for a research group site that looks like /group/abcd/header.html tells the web server to actually look for /WWW/group/abcd/header.html.
Complete pathnames for files in personal web sites on pangea are handled differently. They must begin with /~sunetid, where you must substitute your own SUNet ID for sunetid, but keep the tilde (~) character before it. The web server will then interpret such a complete pathname to start in the WWW folder (directory) of the home share for the user with that SUNet ID. For example, a complete pathname in a server-side include directive in a web page for the personal web site of user "farrell" could look like /~farrell/contact.html. The web server would interpret this to look for the file contact.html in the WWW folder of the home share for the user farrell.
A relative pathname does not start with a slash, and the web server assumes that it should start its search in the same directory as the main page that is making the include. For example, if the file index.html in the directory /WWW/computing/files has a server-side include directive with the simple relative pathname header.html, the web server will look for the file header.html in the directory /WWW/computing/files, which is the same directory where it found the main page.
Other features of server side includes
In addition to incorporating other files into your web pages, SSIs can allow the server to insert other information. For instance, you can have the server echo back the last-modified date of your file:
<!--#echo var="LAST_MODIFIED" -->
This way, a page can automatically show the viewer when it was last updated. More examples of SSI commands can be found on the Apache website.
Note that the ExecCGI feature is disabled on this server; CGI programs cannot be included as SSIs.