How AxKit Works

May 24, 2000

Matt Sergeant

How AxKit Works

Table of Contents



How AxKit Works

Mapping XML Files to Style Sheets

Choosing a Style Sheet

Cascading Style Sheets

Setting up AxKit


AxKit registers two "handlers" with Apache in order to do its work. In Apache terms, these are modules that work in various parts of the request phase (which covers things like Authentication, Type checking, Response, and Logging). When a request for a file comes in, AxKit does some quick checking to see if the file is XML. The main checks performed are to see if the file extension is .xml, and/or to check the first few characters of the file for the <?xml?> declaration. If the file is not XML, AxKit lets Apache deliver the file as it would normally. Note that it's possible to only apply AxKit to certain parts of your web site.

When an XML file is detected, the next step is to call plugin modules to determine the media type and/or style sheet preference. Media type chooser plugins normally look at the User-Agent header, or possibly at the Accept header. However, it's possible to define any method at all to determine the media type.

The existing style sheet choosers are based on examining the path info (this is a path following the filename, so you could request myfile.xml/mystyle), query string (for example myfile.xml?style=mystyle), and file suffix (myfile.xml.mystyle).

The final part is plumbing together all the style sheets with the XML file in the right order, implementing cascading where appropriate, and also "doing the right thing" with regards to the cache. AxKit invalidates the page cache when external entities (parsed or unparsed) change, as well as when the original document is altered. This allows modular style sheets to change only part of their make-up and ensure that changes to these sub-components cause a re-build of the cache.

Mapping XML Files to Style Sheets

AxKit uses two separate methods for mapping XML files to style sheets. The primary method is that specified in the W3C Recommendation at This specifies that an <?xml-stylesheet?> processing instruction at the beginning of the XML file (after the <?xml?> declaration, and before the first element) defines the location and type of the style sheet.

The second method of mapping XML files to style sheets is used when no usable <?xml-stylesheet?> directives are found in the XML file. This uses a DefaultStyleMap option in your Apache configuration files. These directives can be used anywhere within Apache's <Files>, <Location>, and <Directory> sections, and .htaccess configuration system. In this way it's possible to define complex mapping rules for different file types and locations in whichever manner pleases you, without having each XML file individually specify its style sheet.

AxKit then uses the type of the style sheet (in the type="..." pseudo-attribute of the <?xml-stylesheet?> processing instruction, or the first parameter of the DefaultStyleMap option) to decide which module to use to process the file. Types are mapped to a module using another Apache configuration option: AddStyleMap. Again, this directive can appear anywhere within Apache's configuration structure. This allows you to try different modules for processing the same file.

Choosing a Style Sheet

Often, AxKit will have more than one style sheet option for serving a particular file. How does it choose which one to use?

The choice is made based on media type and on "style sheet preference." For a style sheet to be chosen for the file currently being served, the media types must match, or the style sheet must have a type of "all."

Style sheet preferences are slightly more complex. AxKit has three concepts of style sheets: persistent, preferred, or alternate. Without drowning in detail here, this facility allows a processor further up the "pipeline" to determine a style sheet -- so, for instance, a user could personalize their look and feel by determining which style sheet was applied.

Cascading Style Sheets

It's easy to get confused by the term "style sheet" here--in AxKit they are not restricted to XSLT sheets, and are best thought of as general processing and transformation stages. Style sheets in AxKit's terms can do anything, provided you can build a Language module to parse it. This includes the function of creating original XML content, as well as transforming and formatting it. So it becomes possible to, for instance, retrieve database results, add tags, and format the result into WML or HTML.

Cascading refers to the case of one style sheet's results "cascading" into the next (alternatively, you can think of this as a pipeline of processing stages). With AxKit there are a number of ways to achieve this. The first and simplest method is to have all your style sheets based on DOM, and produce DOM trees. When all the style sheets have finished processing, AxKit takes care to dispose of your DOM tree and output the result to the user agent.

The second method of cascading is to simply pass around the textual result of your output. This is necessary with modules like Sablotron where there is no DOM tree available. Modules further down the processing stream can parse this result as XML, and continue processing.

The final, and possibly most interesting, method of cascading processing stages is to use "end-to-end SAX." Here, AxKit sets up a chain of SAX handlers to process the document. Each style sheet stage based on SAX simply sends on SAX events to the next SAX handler up the chain. The final SAX handler in the chain simply outputs its results as text to the browser. The key advantage of this end-to-end system is that it starts outputting data to the browser as soon as parsing begins.

This system allows database modules to avoid building DOM trees in memory, which can be very resource intensive, but to simply fire SAX events, and the output from the database will appear as results are available.

Setting up AxKit

Now that we've been through the theory of how AxKit works, it's time to install and start using it. I don't believe in tools like this being hard to use or set up, so provided you can use an editor and modify a few Apache configuration files, installation should be simple.

Obviously, AxKit requires an installed Apache web server. AxKit also requires mod_perl, so if you don't have it already installed, you need to add it into your Apache. Depending on your platform, this can be complex. More information is available at

To install AxKit, first download the distribution. Extract the archive and change to the directory it creates. Then type:

perl Makefile.PL


make test

make install

(If you don't have 'apxs' in your path, mod_perl versions below 1.24 will produce a warning at the first step. This warning can be ignored.)

Once AxKit is installed, you will need to edit your Apache web server's configuration files. First you need to enable AxKit so that Apache understands AxKit's configuration directives, so add the following line to your httpd.conf file:

PerlModule AxKit

Finally, you can add in the core components of AxKit--the XMLFinder and the StyleFinder. These can be added to any .htaccess file, or other Apache configuration file:

PerlTypeHandler Apache::AxKit::XMLFinder

PerlHandler Apache::AxKit::StyleFinder

AxAddStyleMap text/xsl Apache::AxKit::Language::XSLT

The last line associates the type text/xsl with its style sheet code module.

Now you're ready to start serving up XML files. To get started, try looking at the example files in the AxKit distribution.



  • AxKit Home Page

  • AxKit Mailing List

  • AxKit Examples

  • AxKit XPathScript

  • Apache

  • mod_perl

AxKit provides web developers with the tools they need to deliver complex XML-based systems quickly, and eases them into the development process. It provides the power to develop their own system for style sheet negotiation, and also the flexibility to design completely new style sheet languages.

Although AxKit is not finished yet, the majority of the features described above are built and working reliably. The most significant things missing from AxKit are SAX-based style sheet languages (which need to be designed and built--I have a number of ideas for these) and alternate ways to generate the initial XML file (as opposed to filesystem XML). These will be coming in future releases.

As AxKit is an open source project, I hope people will jump in and help. We have the beginnings of an active mailing list, where you can vote on features, help develop them, or simply lurk. We're moving extremely quickly with the features. Developing in Perl allows us to do this, while still maintaining readable code (something I deem very important -- so don't assume because it's written in Perl that it's going to be a ball of spaghetti!). If there's something you'd like to see in AxKit, please join the mailing list and participate in the project.