<oo>→<dh> Digital humanities

Maintained by: David J. Birnbaum (djbpitt@gmail.com) Last modified: 2023-01-08T19:23:14+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:

and be coded as:

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

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

A few guidelines for preparing the file to be included:

• The file does not have to be valid or well-formed HTML. For example, a boilerplate header might contain an <h1> header and a <p>, with no common root elements. That isn’t well-formed XML or HTML (which requires that everything be wrapped in a single root element), but it’s fine for a file to be included because what matters for validation is that after the inclusion is processed the combination is valid. The menu above contains three sibling elements, two horizontal rule (<hr>) elements with a <p> between them.
• The file to be inserted must not include an XML declaration (the line beginning <?xml that <oXygen/> creates at the beginning of regular XML or XHTML files) or other HTML boilerplate. What you are creating is some fragmentary HTML code; it is not an HTML page.
• The first S in SSI stands for server (server-side include), and that means that the include instruction is processed only when a web server (like the one on Obdurodon) delivers the page to a browser. This means that if you won’t see the included content if you open your page in a browser directly from the file system. To verify that your include is being processed correctly, you must upload the files (the included file and the one that includes it) to Obdurodon and open it from there.

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.xhtml" -->

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:

• The value in quotation marks should be the path to the file you want to include. If it’s in the same directory as the file into which you are going to insert it, the path consists of just the filename. If it is in another directory, you have to tell the system where to find it. I usually put my included files in their own subdirectory (called inc) under my main project directory, so the value I would use is inc/menu.xhtml. You can put your files wherever you want, but you have to tell the system how to find them.
• White space matters. There can be no space between the comment start tag (<!--) and the include instruction (#include). There must be a space before the comment end tag (-->).

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.xhtml 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.xhtml" </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.