Putting it all together

In simple terms, how does AxKit work? AxKit registers with Apache a "handler". In Apache terms this is a module that works in a particular part of the request phase (which cover things like Authentication, Type checking, Response, and Logging). When a request for a file comes in, AxKit does some very 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 using Apache's configuration methods described above, it's quite possible to apply this only to certain parts of your web site.

When an XML file is detected, the next step is to call any plugin modules that determine the media type and/or stylesheet preference. Media type chooser plugins normally look at the User-Agent header, or at the Accept header, however its possible to use any method at all to determine the media type. Stylesheet choosers exist currently based on Path Info (this is a path following the filename, so you could request myfile.xml/mystyle), querystring (for example myfile.xml?style=mystyle), and file suffix (myfile.xml.mystyle).

The final part, and the most significant part, is the plumbing together of all the stylesheets with the XML file in the right order, implementing cascading where appropriate, and also to "do the right thing" with regards to the cache. One "leg-up" we have on Cocoon here is that AxKit invalidates the cache when external entities (parsed or unparsed) change too. This allows modular stylesheets 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 Stylesheets

AxKit uses two separate methods for mapping XML files to stylesheets. The primary method is to use the W3C recommendation at http://www.w3.org/TR/xml-stylesheet. This specifies that a <?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 stylesheet. The actual details of how all this works are defined in TR/REC-html40 (which has just recently been superceded by html 4.01). The second method of mapping XML files to stylesheets 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>, <Directory> 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.

AxKit then uses the type of the stylesheet (in the type="..." attribute of the <?xml-stylesheet?> directive, or the first parameter of the AxAddDefaultStyleMap option) to decide on a module to use to process that type of file. Again this is slightly different to Cocoon 1.x, which requires special <?cocoon?> directives to be added to your XML files to determine the processor module to use. The type is then mapped to a module using another Apache configuration option: AxAddStyleMap. Again, this directive can appear anywhere within Apache's configuration structure. This allows you to try different modules for your processing of the same file (for example, you might like to try both XSLT processors to see which suits your needs best).

Choosing a Stylesheet

In the course of examining the options of which stylesheets to choose, often a single XML file (or a DefaultStyleMap - see above) can provide more than one option. There are two important parts of this to consider. The first is choosing from multiple stylesheets based on media type, and stylesheet preference. The Media type of a stylesheet must always match the requested media type, or be of media type "all", however it's worth noting here that Cocoon provides many alternative media types to the W3C's specification list, such as "wap", "lynx", "explorer" and "netscape". The merits of this are debatable. The stylesheet preference is based on 3 types of stylesheet: A persistant stylesheet, a preferred stylesheet and an alternate stylesheet. Persistant stylesheets declarations contain no title="..." attribute, preferred stylesheets contain a title="..." attribute, but have alternate="no" (or no alternate="..." attribute), and alternate stylesheets contain a title="..." attribute and have explicitly set alternate="yes".

AxKit always applies persistant stylesheets, and will apply alternate stylesheets only if a plugin has determined that one should be displayed, otherwise the preferred stylesheets are used. This all seems rather confusing and long winded, but it allows a very modular system, and also allows for wonderful flexibility in choosing stylesheets for users. For example, a plugin could connect to a database and retrieve the correct alternate stylesheet for a particular user based on an authentication token. This would allow users to change the whole look of their favourite web site, and AxKit will do all the hard work for you.

Cascading Stylesheets

It's easy to get confused by the term "stylesheet" here. A quick read of this might make it seem like all they are good for is transforming static XML files into further static XML files. This is especially the case if all you can picture is XSL(T) (or even CSS). However stylesheets in AxKit's terms can do anything, provided you can build a Language module to parse it. The concept of stylesheets in AxKit replace all the stages in Cocoon: Producer, Processor and Formatter. So it becomes possible to, just as in Cocoon, return database results, format add tags, and format the result to WAP, HTML or any possible format.

The term cascading here therefore refers to the case of one stylesheet's results "cascading" into the next. With AxKit there are a number of ways to achieve that. The first and simplest method is to have all your stylesheets based on DOM, and produce DOM trees. When all the stylesheets have finished processing, AxKit takes care to dispose of your DOM tree and output the results to the user agent.

The second method of cascading is to simply cascade the textual results of your output. This is necessary with modules like Sablotron where there is no DOM tree available. Modules further down the processing stream are able to parse this string directly (provided they are designed to work this way) as XML, and continue processing.

The final, and possibly most interesting method, is to use "end-to-end SAX". This is where AxKit sets up a chain of SAX handlers to process the document with. AxKit stylesheet languages based on SAX are responsible for simply sending on SAX events to the next SAX handler up the chain (they are provided a SAX handler to pass events to on construction). The final SAX handler in the chain simply outputs its results to the browser. This doesn't sound particularly interesting, until you consider that this end-to-end system starts outputting data to the browser immediately as soon as parsing begins. This system allows database modules to not build DOM trees in memory, which can be resource consuming, but to simply fire SAX events, and the output from the database will appear as results are available. Cocoon 2 will have a system similar, if not identical, to this.