Digital humanities


Maintained by: David J. Birnbaum (djbpitt@gmail.com) [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2021-12-27T22:03:54+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 space 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 unless you tell it to do that for the individual file. To do that for the file that contains the inclusion instruction (not the menu file; rather, the one which will contain the menu after the inclusion instruction is processed), you need to set the x bit, which permits your file to execute a process (the including of the HTML for your menu). When a user attempts to load a file with the x bit set, the system knows that any include instructions inside it need to be processed. To do that:

That’s it! If you load 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.2/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. The SSI exec command can be useful, but because it is inherently insecure, its use requires certain security precautions. 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.