HotWired's XSSI Extensions
by W. T. Monkey
Apache's XSSI (eXtended server-side includes) is an extremely useful tool for Web developers because it offers a simple, efficient way to do basic Web page scripting. For example, Webmonkey relies heavily on XSSI to control many aspects of the pages you see on the site. In fact, the page you're reading right this second features all kinds of XSSI.
If you were to try to recreate Webmonkey's pages, however, you'd find yourself outta luck. A lot of what Webmonkey does on its pages is simply not possible with the standard version of mod_include (the Apache module that includes XSSI), which has some substantial limitations. To get around some of these limitations, a HotWired engineer, Brian Slesinsky, wrote a special extended version of mod_include (no, we don't call it XXSSI). The Wired version of mod_include adds two new directives (parse_form and random) and extends the existing echo directive.
With these new commands at our fingertips, we Webmonkeys can perform all kinds of neat little tricks with our pages. To get an idea of some of the things the HotWired mod_include can do, read on. If you already know you want it, however, feel free to cut to the chase and download and install the thing right away.
What It Can Do
Random DirectiveIf you take a look at Webmonkey's frontdoor, you'll see the random directive in action. Hit reload a couple of times and keep your eyes on the space right underneath the Search button. See how the image changes each time? That's random directive hard at work. What we did was set a variable and then give it low and high parameters. That way, when the user reloads the page, a different image or piece of text swaps in based on what the random variable comes up with.
Here's the code that makes it so:
<!--#random var="rnd" low="1" high="3" --><!--#if expr="$rnd=1" -->
-do stuff-
<!--#elif expr="$rnd=2" -->
-do stuff-
<!--#elif expr="$rnd=3" -->
-do stuff-
<!--#endif -->
Pretty nifty, eh?
parse_form
Have you ever noticed how when you're clicking around Web sites, there's always a bunch of seemingly meaningless stuff in the query string (y'know, the random characters that come after the question mark in the URL)? Well, we can't explain all of it since it's not all XSSI (it could be the work of ASP, Perl, or some strange proprietary language). But we can show you what's going on in our query string. Fortunately for you (and us), our use of parse form is fairly simple: We just use it to track pageviews and to dynamically generate a little page layout. To see a nice, straightforward example of this, take a look at the Elbow Grease archive.
Roll your cursor over the links for this month's Elbow Greases. You can see that the URL stays almost exactly the same. But if you look carefully, the part after the question mark is changing. Here's what one of the full URLs looks like:
http://www.hotwired.com/webmonkey/mail/elbo_archive/templ.html?M=02&D=15&Y=99Every link is the same except for the stuff that follows the question mark. The HTML file templ.html is a template that formats every page the same way. In that file, we have a virtual include that looks like so:
<!--#include virtual="${form_Y}/elbogrease.${form_M}-${form_D}.htmlf" -->Here's what's happening: At the top of templ.html, we placed the <!--#parse_form --> directive, which says, "Hey, there's something in the query string for me to get!" Then parse_form creates variables from the query string, adding "form_" to the beginning (unless you tell it not to). In our query string we have M = 02, D = 15, and Y = 99. After the page has been parsed, our virtual include now looks something like this:
<!--#include virtual="99/elbogrease.02-15.htmlf" -->The virtual include knows which page to get, and you get to read that issue of Elbow Grease you accidentally deleted from your inbox.
Sounds good, no? Are you jealous? Do you wish you could do something similar with your pages? Well, now you can. For a limited time only, we're passing Brian's hard work along to you (released under the Webmonkey Public License). This offer is not available in stores. You need to download and install the HotWired mod_include yourself.
Documentation for parse_form
The parse_form directive reads form variables from the QUERY_STRING and uses them to create environment variables. By separating these variables into pairs (see the example below), it becomes possible to pass more than one piece of information from page to page. To avoid conflicts with existing environment variables, each new variable is prefixed by form_.
To customize the way parse_form works, here are two optional parameters (though in most cases they shouldn't be needed):
var="varname":
If this parameter is included in the directive, parse_form will read the form variables from varname instead of QUERY_STRING. You'd use this if you want to use some other variable, such as "PATH_INFO."prefix="string"
If this parameter is included, parse_form will use string instead of form_ as the prefix when creating environment variables. You'd use this if the default FORM_ conflicts with some other variable you have or if you just feel like it or if you don't want to add FORM_ to everything.Examples
Now let's take a look at what you can do with these commands. Suppose you set the following variables:
Then this command ...QUERY_STRING = X=3&Y=4
FOO = Z=10
<!--#parse_form -->... will result in the creation of the following variables:And this command ...form_X = 3
form_Y = 4
<!--#parse_form var="FOO" prefix="QQQ" -->... will result in the following variable:QQQZ = 10Installation
To enable this extension, simply add "-DUSE_PARSE_FORM" to the "EXTRA_CFLAGS" section of Apache's Configuration file.
Bugs
If QUERY_STRING contains the same variable twice in a row (e.g., "X=3&X=4"), #parse_form will create two environment variables with the same name. Only the first instance is accessible from XSSI.
Documentation for #random
This new directive makes it possible to set a variable to a random integer in the specified range. Here are the parameters you'll use with this directive:var="varname"
This parameter specifies the name of the variable to set.low="integer"
Use this parameter to set the low end of the range.high="integer"
Use this parameter to set the high end of the range.Example
Here's how you might use this directive:
<--#random var="FOO" low="1" high="6" -->You can combine #random with #if statements to choose HTML text at random. For example, you could set the page's background color at random with code that would look a little something like this:Here is a random number between one and six: <--#echo var="FOO"-->.
<!--#random var="X" low="1" high="3" --><!--#if expr="$X=1" -->
<body bgcolor="#ff0000">
<!--#elif expr="$X=2" -->
<body bgcolor="#00ff00">
<!--#elif expr="$X=3" -->
<body bgcolor="#0000ff">
<!--#endif -->
Installation
To enable this extension, add "-DUSE_RANDOM_SSI" to the "EXTRA_CFLAGS" section of Apache's Configuration file.
Bugs
There's no safeguard to ensure low <= high.
Documentation for #echo
#echo is a standard XSSI directive that simply prints a variable. It goes a little something like this:var="varname" (unchanged)Brian's extension adds two new options to give you more control over what's printed:
This is just the name of the variable to be printed.default="string" (new)
If this parameter is set and the variable is undefined, string will be printed instead of "(none)."escape="html" (new)
< becomes <
If this parameter is set, the following substitutions will be made when the variable is printed:> becomes >
& becomes &
" becomes "
Example
Suppose this code is executed:<!--#set var="FOO" value="<p>" -->"View Source" will show this:<p>First: <!--#echo var="FOO" -->
<p>Second: <!--#echo var="FOO" escape="html" -->
<p>First: <p><p>Second: <p>
The output of the first #echo gets interpreted as a paragraph tag, while output of the second #echo is displayed as plain text.
Bugs
There's no way to turn off this extension except by editing the C code in mod_include.c.
And that should do it. You now have the technology to rebuild your pages the Webmonkey way using the HotWired mod_include. Use it in good health!
W. T. Monkey likes tools and he's nobody's fool. He never bites people. Except for that one time. And Kristin isn't that upset.