By Mitch Wyle

Simplified Order Processing with Apache's mod_qs2ssi

Server-side includes (SSI) are special directives that are embedded as part of your HTML documents. SSI-enabled Web servers automatically replace these directives with computed values. SSI codes specify things like the last modification time of the document, its filename or URL, and other information from environment variables. SSI also lets you include standard inline headers, footers, and other common information that is stored in separate files. This function is the main and most popular purpose of SSI. SSI even lets the HTML in your document execute arbitrary UNIX commands, making the output of these commands appear as part of your document.

Apache is the most-used and most actively developed Web server in current use. Out of the box, Apache comes with the standard mod_include module enabled. Many of us use this module to insert standard headers and footers into our HTML pages using the <!--#include --> construct. However, the module provides many functions in addition to the simple #include parsing. You can set variables, create if-then-else conditional areas of an HTML file, perform string manipulation, and even launch external system commands just as you can in CGI. The documentation that comes with the mod_include module isn't very clear, and the syntax itself is also quite arcane. Regardless, it's a powerful system and simple to use once you get used to it. For this reason, it's more efficient and easier to take advantage of the Apache mod_include SSI capabilities directly in HTML documents instead of writing CGI application programs. Table 1 shows the variety of SSI directives available through the mod_include module. Table 2 shows how to apply formats.

Another great reason to use Apache is the number of modules available for extending the server. Many developers have made their modules available through the Apache distribution itself. Therefore, before you embark upon the expensive investment of crafting a custom solution to your Web service problems, you should look at these modules to see if one or a combination of them could solve your Web scripting problem.

Installing Modules

The Apache source distribution includes a set of contributed modules in a Table 1 shows the variety of SSI directives available through the mod_include module. Table 2 shows how to apply formats.

Another great reason to use Apache is the number of modules available for extending the server. Many developers have made their modules available through the Apache distribution itself. Therefore, before you embark upon the expensive investment of crafting a custom solution to your Web service problems, you should look at these modules to see if one or a combination of them could solve your Web scripting problem.

Installing Modules

The Apache source distribution includes a set of contributed modules in a subdirectory of the distribution called contrib. These modules are neither completely nor officially supported by the entire development team. However, their source licenses are usually identical or at least similar to the Apache "free software" license. The contrib distribution directory consists of both the third-party modules and a set of Makefiles. These Makefiles enable installation of each module using the Apache Program eXtension System (APXS).

The distribution also comes with a top-level Makefile that installs all the modules without enabling them. If you plan to use more than a few of these modules, it's easiest to install them all, then choose the ones you want to enable in the httpd.conf file. The following UNIX commands will extract and install all the modules for you.

$ gunzip < apache-contrib-*.gz | tar xvf -
$ make all install APXS=/usr/local/apache/bin/apxs

Accessing Query Strings

One shortcoming of mod_include is that it has no way to parse out Web form variables that are part of a GET URL. Recall that the part of a GET URL after the ? that contains all those form variables or URL options is also called the "query string."

The module's name, qs2ssi, is an abbreviation for "query strings to server side include." The mod_qs2ssi contributed module was designed to make all of the query strings available as environment variables, empowering SSI codes to use these variables without the need for CGI. It parses out all of the values from a GET Web-form submission and converts them to environment variables that are then available directly to SSI programs from mod_include. The module is also useful to CGI programs written in other scripting languages. Only Web-form variables visible in the URL are parsed. Any HTML Web form that uses <FORM ... METHOD="GET" ... > will work with this module.

mod_qs2ssi can be quite helpful and convenient for beginning Web programmers who don't want to parse through long URLs to extract the Web-form variables, and who are currently not versed in one of the standard parsing systems in a standard CGI scripting language. It's also very useful for those of us who love and use more of the features of Apache's mod_include capability.

A typical use for qs2ssi in conjunction with SSI is to display customized pages based on user input from a Web form. The most common use of SSI is to include standard headers, footers, tables, or sections of Web pages by extracting these sections of the Web pages and saving into a single file. This module adds personalization and customization capabilities to such common files by allowing parameter substitution. This abstraction and parameterization of Web pages is sometimes called page "branding." For example, if you want to provide personal pages for each individual who visits a certain area of your site, you could use this module in conjunction with other custom modules to create a "personalized Web experience" without complex database programming. Instead, you could extract the person's name or other relevant information from the environment variables and serve documents from a user-specific directory.

Another application where this module is quite useful is sending simple Web-form information via email. The concept here is to let a user enter information on a simple Web form, then use this module along with SSI to send the information to a separate application by email. Examples include simple requests for service, Girl Scout cookie orders, comments about a Web site, and so on. Since mod_qs2ssi parses the results of the form submission into environment variables, you can use it to redisplay the values entered and also pass them to an email program. Listing One shows an example cookie order form for a Girl Scout troop that uses this module with SSI. The entire system is just one HTML page. There are no external CGI programs. The form and the action are the same HTML file. A "real world" example in production use is a Cub Scout popcorn order page at www.wyle.org/~syw.

The HTML page is both the order entry form and the order acknowledgement form. After the form is filled out and submitted, the same HTML page displays an order acknowledgement on the Web. The SSI if-then-else construct is used to determine which block of HTML to display, depending on the state of the submit button (the order variable). At the end of the HTML page, all of the environment variables are emailed to Suzie Scout using the SSI exec construct. No CGI programming is necessary at all. The syntax of SSI commands is almost as easy as Visual Basic.

If Suzie starts to receive too many cookie orders (email messages) from this Web form, it's easy for her to add an order-processing program that automatically processes the email submissions. Such a program could also be used to process email orders from people who have email but no Web access.

As this example illustrates, it's not always necessary or even a good idea to have CGI programs process Web-form submissions. Simple, elegant Apache modules like mod_qs2ssi can help get the job done faster and more effectively.

The mod_qs2ssi module in conjunction with SSIs forms the basis of yet another lightweight ASP-like development environment. If you're already using some of the features of SSI to customize your HTML, you should consider exploring more of its features. In this example, we've seen how to capture and process simple Web-form data and send it via email to a back-end application. Using SSI directives, a single HTML file can contain the entry form, the acknowledgement page, and the application that sends the form data for further processing. The real lesson to learn, however, is that before you embark on a large-scale Web development project you should explore the rich set of features built in to both the standard Apache modules and the contributed modules.

---

Mitch is chairman and chief scientist at DataMain, where he is responsible for its high availability and Internet security businesses. He has a Ph.D. in computer science. Mitch is also a Cub Scout leader.