Digital humanities


Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2017-03-14T23:52:07+0000


Server side includes (SSI)

Why use server side includes?

Server side includes (SSIs) make it possible to include repeated (boiler-plate) text in a set of web pages. A common application of SSIs involves incorporating the same header or footer or menu in all pages on a project site. If that information is coded into the individual pages, any change requires changes in all of the pages individually. With SSIs, you can put the repeated text in its own file and instruct the web server to insert that information into all of your pages in a particular location. If you then change the information, you can make the change in just one place, the file to be inserted, and the change will propagate to all pages that have been configured to include it.

Creating the file to be included in your pages

Suppose you want to include the same menu in all of your pages. Instead of adding the HTML that represents the menu to each page individually, you can create a separate file that contains nothing but the menu, which you upload to the server. For example, a menu might look like:


Main | Texts | Analysis | About


and be coded as:

<hr/>
<p><a href="index.html">Main</a> | <a href="texts.html">Texts</a> | 
<a href="analysis.html">Analysis</a> | <a href="about.html">About</a></p>
<hr/>

Create this as a separate document and save it with its own filename, perhaps something like menu.html.

A few guidelines for preparing the file to be included:

Creating a place in your other pages for the included information

In each page where you want to insert your include file (in our example, a menu), insert the following line in the place in the document where you want the inclusion to appear:

<!--#include virtual="menu.html" -->

This is an XML comment, but it’s a special type of comment that will be understood by the web server as an instruction to insert the contents of some other file in place of the instruction. A few details:

Uploading the files

Once you’ve created the file where you want to insert the included information and the file that contains the information to be included (menu.html in our example), upload them both to your project directory on Obdurodon the way you usually upload files. If you have a separate subdirectory for your included files, put the menu there and be sure that the include instruction points to it.

Telling the server about the include

By default the web server doesn’t process include instructions for all files. How it knows when to process include instructions and when not to can vary from host to host, and Obdurodon is configured so that if the file that does the including has the extension .xhtml, you don’t have to do anything further, and the server will process the included file automatically. That doesn’t happen automatically with files that have the extension .html, or anything else other than .xhtml, though, and if you need an inclusion in a non-.xhtml file, ask us about the procedure and we’ll explain it.

Once you’ve uploaded the files, you can test the results by loading the page in a web browser. The text from the included file should appear in place of the include instruction.

Using SSIs in HTML files you create with XSLT

The preceding strategy is fine when you type up your HTML directly in <oXygen/>, but how about when you use XSLT to generate the HTML? You can’t just write the include instruction like a literal result because the XSLT that does the processing will think (correctly) that it’s a comment, and won’t copy it into the output.

The way you work around this is with a comment constructor, along the lines of:

<xsl:comment>#include virtual="menu.html" </xsl:comment>

The preceding code tells the XSLT processor create an XML comment in the output at this location, and set its contents to whatever the contents of the <xsl:comment> element might be.

Other SSI functionality, and a note about security

The main use we make of SSIs involves inserted HTML fragments, as in the menu example above, but SSIs have additional functionality, which you can read about at http://httpd.apache.org/docs/2.4/howto/ssi.html.

For security reasons, we do not permit the use of the SSI exec command on Obdurodon unless you have your code reviewed in advance by an instructor. If you think you need it for some reason, let us know, we’ll explore other options with you, and if SSI exec turns out to be the right solution, we’ll work with you to ensure that you implement it safely.