<oo>→<dh> Digital humanities

Maintained by: David J. Birnbaum (djbpitt@gmail.com) 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:

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:

• The file does not have to be valid or well-formed HTML. For example, a boilerplate header might contain an <hi> 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. 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.

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:

• 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 put my included files in their own subdirectory (called inc) under my main project directory, so the value I would use is inc/menu.html. 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.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:

• Create a command-line connection to Obdurodon. On a PC, you can do that with the SSH client that you use to upload files. On a Mac, launch the Terminal application, which will open a command-line session on your Mac. Inside that window, type ssh -l youruserid -p portnumber obdurodon.org (replacing youruserid with your actual userid on Obdurodon and portnumber with the port number you use for file transfers of Obdurodon [which we don’t publicize for security reasons]). This will connect you to Obdurodon, where you’ll be prompted for your password. If you are asked to accept the session, you should do so.
• Once you are connected to Obdurodon, you’ll see a command line prompt. At the prompt, you need to move to your project directory, which you do by typing cd /var/www/html/projectdir and hitting the Enter key (cd stands for change directory, and you’ll have to replace projectdir with the actual name of your project directory). You can verify that you’ve landed there by typing pwd (print working directory), which should display /var/www/html/projectdir.
• Once you’ve moved to your project directory, type chmod +x filename.html, replacing filename.html with the actual name of the file into which you would like the system to insert your menu or other text. This step sets the x bit on that file, telling the server when someone asks for this page, process any inclusion instructions before you return the page to the user.

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.