Apache's eXtended Server Side Includes

Server-side includes allow web developers to reuse content across an entire site employing a simple but powerful structure. This tutorial illustrates how to use Apache eXtended Server Side Includes (XSSI) to create composite web sites and moderately complex, refined web applications without having to resort to more intricate frameworks. After introducing the basics, it shows several techniques that will give you an idea of what you can achieve with XSSI, but I will not address configuration issues. (For some pointers, see the section titled XSSI Resources.) XSSI is by no means a new web technology: server-side includes came about more than a decade ago. Nevertheless, XSSI is a workhorse and can prove indispensable while developing and maintaining dozen of sites.

Apache XSSI Advantages

Technically speaking, XSSI elements are instructions embedded into web documents. Traditionally this meant plain, standard (X)HTML pages; however, adding XSSI to any text-based document is straightforward. While Apache httpd serves static pages without any processing, the server must parse XSSI pages and then, in turn, execute the XSSI instructions and transmit the final result. Although this is similar to what other dynamic content-generation technologies use, many people consider XSSI a lackluster framework. Many web developers resort to more sophisticated technologies--dynamic content management systems such as PHP-Nuke on the one hand and web site development and delivery engines including Mason, Cold Fusion, and Lotus Notes/Domino on the other--and discount XSSI as "simplistic" and "limited." This is, to some extent, true. For example, XSSI does not allow you to connect to databases or perform mathematical operations. Nevertheless, this is by no means the whole story. XSSI has many features, including pattern matching. Many web sites work just fine without a database back end, especially if they use the database simply to store documents. In fact, you can even build a light content management system using XSSI.

XSSI has several advantages over other server-side technologies:

Easy to learn

A small learning curve makes XSSI accessible to people with limited programming experience. XSSI is programmer-efficient because it requires little if any debugging.

Mature

Well-tested code and a stable API make future surprises unlikely.

Lightweight

XSSI can deliver popular features such as printer-friendly versions, article partitioning, and hierarchical menus without client-side scripting or a database back end. Maintenance becomes easier--and cheaper.

Efficient

Contrary to early-day warnings that XSSI would bog down a web server, XSSI is probably the most resource-efficient of all dynamic technologies. For example, according to the Apache Hello World Benchmarks (see XSSI Resources), mod_include, the base module implementing XSSI in Apache, can serve more Hello World pages per second than other dynamic content-generation technologies, including PHP, Perl (ASP, Embperl, mod_perl, and CGI.pm), JSP, Mason, HTML::Template, and the Template Toolkit. The tests showed that there are only two ways you can deliver a Hello World page faster than with XSSI: transmitting a static page or using a custom-made, dedicated Hello World Apache module written in C.

Secure

In particular, if you do not include the output of arbitrary web server executable programs.

Ubiquitous

Present in virtually all Apache installations, because its implementation is a base module.

Complementary

Combined with web site templates, XSSI can decrease maintenance time and increase sitewide consistency. Furthermore, if necessary it is easy to integrate with client-side technologies, including cascaded style sheets, JavaScript, and other dynamic objects such as Flash and Java applets.

Priceless

As it's part of the Apache open source code, you can always enhance it if you need to.

Forward-looking

It can integrate with any text-based document, including XML and RSS.

XSSI Variables

XSSI has a small but powerful set of instructions that you can pick up in just a few hours. For example, to set the value of the variable who to the string World, use

<!--#set var="who" value="World" -->

After initializing who, you can recall its value anywhere in a page. For example, to display its value, use the echo instruction:

<!--#echo var="who"-->

XSSI variables are of a single type only: character strings. There are no integers, floats, and the like. Although you can assign a number to a variable, Apache XSSI does not handle it any differently than a letter-only string. Clearly, you cannot use XSSI to develop an online mortgage calculator. Listing 1 shows the Apache XSSI version of a Hello World page, which displays the value of who twice: once in the document <title> and later in the main body, <h4>.

Listing 1. Variable assignment and substitution

<html>

<head>

<!--#set var="who" value="World" -->

<title>Hello <!--#echo var="who" -->!</title>

</head>

<body>

<h4>Hello <!--#echo var="who" -->!</h4>

</body>

</html>

Besides programmer-defined variables, Apache makes more than 30 environment variables accessible through your code (see XSSI Resources) and gives you access to values passed as arguments to your XSSI code. Effectively, you can customize presentation and content based on a wide variety of parameters: browser make and version, user location or network domain, time of day, and user-specified information. You can always get a listing of the environment variables by embedding the printenv instruction in any (X)HTML document:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 

   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html>

<head>

<title>The Apache Environment Variables</title>

</head>

<body>

<pre>

<!--#printenv -->

</pre>

</body>

</html>

Content Inclusion

The most common use of XSSI is file inclusion. Professionally designed web sites feature navigational aids, copyright notices, disclaimers, and other items that appear on every page. With XSSI you can store this content once and use it from any page on the site. This allows you to incorporate future updates and modifications virtually instantaneously. Listing 2 shows how to add a menu on the top of the Hello World page.

Listing 2. File inclusion

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 

   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html>

<head>

<!--#set var="who" value="World" -->

<title>Hello <!--#echo var="who" -->!</title>

</head>

<body>

<!--#include file="top-menu.html"-->



<h4>Hello <!--#echo var="who" -->!</h4>



</body>

</html>

When a user requests the document shown in Listing 2, Apache will replace the file inclusion instruction (in bold) with the contents of the file top-menu.html (Listing 3), located in the same directory.

Listing 3. (X)HTML fragment used as an included menu

<p>Hello:  <a href="hello-world.shtml">World</a> - Africa -  

   Antarctica - America -Asia - Europe - Oceania</p>

Included files typically contain (X)HTML fragments only, not complete documents: reusable, common content, such as a navigational menu, makes a good (X)HTML fragment to store once and include throughout the site. When Apache receives a request for the document in Listing 2, it will parse Listing 2; process and execute the XSSI instructions (one variable assignment, two variable substitutions, and one file inclusion), effectively stitching together Listing 2 and Listing 3; and, finally, send the final output shown in Listing 4, which is a valid (X)HTML document, to the browser for display (Figure 1).

Listing 4. After Listing 2 and Listing 3 are processed, this is the final output sent to the requesting browser

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 

   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html>

<head>

<title>Hello World!</title>

</head>

<body>



<p>Hello: <a href="hello-world.shtml">World</a> -Africa - 

   Antarctica - America - Asia - Europe - Oceania</p>



<h4>Hello World!</h4>

</body>

</html>

Figure 1. "Hello World!" in the browser

Experienced web site authors may have noticed that XSSI syntax looks as if it is enclosed in (X)HTML comments. This is not an accident: XSSI elements are actually formatted just like SGML comments, which is a big advantage. First, if due to some misconfiguration the unparsed document is sent to the browser, it will not display the directives. Second, this format works well with both plain-text editors and WYSIWYG web authoring software. Finally, it means that documents written in any markup language stemming from SGML, including XML, can incorporate XSSI naturally.

[1] [2] [3] Next