XSSI Basic Tutorial

Apache’s XSSI (eXtended Server Side Includes) is a very useful tool for Web developers because it offers a simple, efficient way to do basic Web page scripting without taxing your servers system resources unnecessarily. It also does not rely on your visitors browser capabilities like some other client-side scripting languages (i.e. JavaScript). This means that your XSSI code will work no matter what restrictions the visitors browser has set. However, XSSI does have it’s limitations, but when used properly, it can be an incredible asset to both you and your Web site visitors.
What is XSSI
As mentioned above, XSSI stands for eXtended Server Side Includes. The official Apache documentation states that:
“This module provides a handler which will process files before they are sent to the client. The processing is controlled by specially formated SGML comments, referred to as elements. These elements allow conditional text, the inclusion other files or programs, as well as the setting and printing of environment variables.”
Basically this means that when a page is requested by a visitor to the Web site any XSSI commands embedded in that page are interpreted by the Web server before the page is returned. The commands are never seen by the visitor, only the results of them being interpreted. This enables pages to be dynamically generated (the difference between server-side code like XSSI and “dynamic HTML” is that XSSI code is dynamic only at the time the page is requested, while dynamic HTML pages can continue to change once they’re downloaded).

How to Use XSSI
Your account should automatically be set up to use XSSI, no extra configuration is needed. Some online documentation might say you need to use the .shtml extension with your XSSI pages, but that is not required with your WestHost account, you should be able to add XSSI commands to your standard .html or .htm pages. If XSSI is not working on your site, please contact technical support to verify that your account is configured correctly.
The basic structure of an XSSI command is:

That on its own is not very helpful until you learn the different elements and their functions. The official Apache documentation is very thorough, but can be a bit difficult to understand if you’re new to XSSI. We’ll cover a few of the more common uses of XSSI below.
echo

The echo command prints the value of a variable as if you’d simply typed it in as part of your HTML (i.e. if the variable “company” is set to “WestHost,” then <–#echo var=”company” –> will print “WestHost”). We’ll discuss XSSI variables in more depth a little later on.
if, elif, else, endif

These so-called flow-control elements allow you to make documents display differently depending on the variable (such as which browser is being used or the time of day etc…)
The “test condition” is evaluated by Apache and, if it is true, the code following it is executed (if there are XSSI statement following it) or printed (if text/HTML follows it). Test conditions can take various forms, which are detailed in the official Apache documentation.
include

This command inserts the content of another file into the current file. We use this command alot at WestHost to include the many elements of each Web page that is the same on every page (i.e. header, nav bar, side bar, footer, etc…). That way, since every pages shares the same common file, if I need to make an update (i.e. change the copyright date in the footer) I only need to update one file which will update every page on our site.
set

This defines a variable that you will use later on in your code. Below we will look closer at XSSI variables and how to use them.
XSSI Variables
XSSI variables are set in a couple of different ways. You can set your own with the set command, or you can use one of the variables that is set automatically for each browser when it requests a page.
In XSSI code, the variable is referred to either simply by name or with a preceding $. The $ is necessary in contexts in which it’s unclear as to whether it’s a variable. For example, in the echo command <!–#echo var=”variable name” –>, the only thing that can be echoed is a variable (that’s why it says “var=”), so you don’t need the $. On the other hand, in an include statement (<!–#include virtual=”$URL” –>), you need the $ to specify that URL is a variable.
Some of the more useful environment variables are:
HTTP_REFERER

• • This is the page that linked to the current page.

HTTP_USER_AGENT

• • This describes the browser that’s being used. This is how you could server different content to Firefox and Internet Explorer users.

QUERY_STRING

• • If the URL requested has a “?” and some text at the end, this text is stored in this variable.

PATH_INFO

• If the requested URL has extraneous directories at the end, this information is stored in this variable.

There are also several standard XSSI variables, including:
DATE_GMT

• • The current date and time (can be formatted with the config command, we will cover this in more detail later).

DOCUMENT_NAME

• The filename of the document requested by the user.

Putting It All Together
Now that we know the basics, we can start putting it all together to help make our Web pages more efficient and dynamic. Here are a few XSSI examples that we use here at WestHost:
Included Page Elements

• • This was discussed briefly above, but is by far the most used XSSI command on our site. We have every element of a Web page that may be used more than once sliced up into it’s own HTML page. We

do not

• • include the main HTML elements such as the <HTML>, <HEAD>, <TITLE>, etc… tags since those will be included in the main file (since everything we have in the sliced file will be included into the existing file). This has made the maintenance of the Web pages considerably easier and makes the code so much easier to work with as well. There are 2 ways to include a file like this:

File Include

You use the “file=” when the file that will be included is held within the same directory as the file that is calling for it. You can also use the file argument when the file is within a subdirectory of the directory containing the file that is calling it.
Virtual Include

You use the “virtual=” when the file you are calling for is located in a position requiring an address starting at the server root. That’s an academic way of saying the file isn’t in the same directory as the page that is calling it. That forward slash before the first directory is representative of the domain anme (server root). By using that leading slash, the server will add the domain name to the front of the address for you.
Rule of thumb, use the “file=” when the included file is within the same directory as the page that is calling it, use the “virtual=” when it isn’t.
Dynamic Footer Copyright Date
This seems like a small thing, but I used to kind of dread the new year because I would have to go find every single footer file we had and update the copyright date to the new year. Now I just use XSSI to echo the current year from the server clock, as long as that’s set correctly, the date will automatically update in the footer.

To format the date output to just display the year, we had to use the config directive with our XSSI command. Because of the basic nature of this document, we won’t go into an in depth explanation of the config directive as that info is available in detail from the official Apache documentation.
Referer Specific Content
Referer specific content can be used for many different things, such as displaying different welcome messages depending on which site your visitors found you from etc… One specific example of this that we use would be some of our Site Application pages we have at WestHost.
We have created these pages as part of a large list of the many different site applications that come with our hosting packages, and wanted to have a “back” button on the page to make navigating these pages easier for our visitors, but we didn’t want people to use the “back” button if they only found the one page from a search engine (as this would direct the visitor away from the site instead of back to the list of the different site applications). Our solutions was to use XSSI with referer specific content:

The above code first checks to see if the referer address (the page the visitor was on right before the current page) had the text “westhost” in it. If it does (which means they came from a WestHost site) then they should display a “Back Link” that will return them to the previously viewed page, otherwise it just puts a space where the link would be.
Conclusion
As you can see, XSSI has many different uses, and can help you create and manage a very efficient and dynamic Web site. This is just a basic overview of some of the more popular features and commands, for more in depth information, please visit the official Apache documentation.