AxKit - XML Application Server

Matt Sergeant

This document is a guide to the ins and outs of using AxKit

AxKit - XML Application Server

AxKit is an XML Application Server, written using the mod_perl framework. At it's core, AxKit provides the developer with many ways to setup server side XML transformations. In reality, this allows you to rapidly develop sites that use XML, allowing delivery of the same content in different formats, and also to allow you to change the layout of your site very easily, due to the forced separation of content from presentation.

This appendix gives an overview of the ways you can put AxKit to use on your mod_perl enabled server. It is not a complete description of all the capabilities of AxKit. For more detailed information, please take a look at the documentation provided on the AxKit web site at http://axkit.org/. Commercial support and consultancy services for AxKit are available at http://axkit.com/.

The key benefit to using XML application servers is their support for W3C recommendations. There are many templating technologies available in the Perl world, but only XSLT is a W3C recommendation [F]1[/F] . Because XML is a de-facto standard,it breaks down the barriers between people using Java or Perl or Python, because ultimately we are all working with the same data formats. Plus we also have the advantage that many tools are built, or being built, for writing XML and XSLT, allowing designers and developers to use the tools of their choice for authoring their content. Other benefits include a well designed scaleable architecture, flexible site layout options, and simple to build dynamic web applications.

Installing and Configuring

While we aim to make the AxKit installation as simple as possible, there are many configuration options that allow you to customize your installation. So in this section we aim to get you started as quickly as possible. This section assumes you already have mod_perl and Apache installed and working. See the Chapter X if this is not the case. This section does not cover installing AxKit on Win32 systems, for which there is an ActiveState package at <URL>.

First download the latest version of AxKit, which you can get either from your local CPAN archive, or from the AxKit download directory at http://axkit.org/. Then type the following:

% gunzip -c AxKit-x.xx.tar.gz | tar xvf -
% cd AxKit-x.xx.tar.gz
% perl Makefile.PL
% make
% su
% make test install

If perl Makefile.PL warns about missing modules, notably XML::XPath, make a note of the missing modules and install them from the CPAN. AxKit will run without the missing modules, but without XML::XPath it will be impossible to run the examples below [F]2[/F].

Now we need to add some simple options to the very end of our httpd.conf file:

PerlModule AxKit
AddHandler axkit .xml
AddHandler axkit .xsp
AddHandler axkit .dkb
AxDebugLevel 10
PerlSetVar AxXPSInterpolate 1

Note that the first line: PerlModule AxKit must occur in your httpd.conf outside of any runtime configuration blocks, otherwise Apache cannot see the AxKit configuration directives and you will get errors when you try and start the httpd.

Now if you have XML::XPath installed (try perl -MXML::XPath -e0 on the command line to check), (re)start your Apache server. You are now ready to begin publishing transformed XML with AxKit!

Your First AxKit Page

Now we're going to see how AxKit works by transforming an XML file containing data about Camelids (note the dubious Perl reference) into HTML.

First you will need a sample XML file. Open the text editor of your choice and type the following:

<?xml version="1.0"?>
<dromedaries>
  <species name="Camel">
    <humps>1 or 2</humps>
    <disposition>Cranky</disposition>
  </species>
  <species name="Llama">
    <humps>1</humps>
    <disposition>Aloof</disposition>
  </species>
  <species name="Alpaca">
    <humps>(see Llama)</humps>
    <disposition>Friendly</disposition>
  </species>
</dromedaries>

Save this file in your web server root (normally /path/to/apache/htdocs/) as test.xml.

Now we need a stylesheet to transform that to HTML. For this first example we are going to introduce XPathScript, an XML transformation language specific to AxKit. Later we will give a brief introduction to XSLT.

Create a new file and type in:

<%
$t->{'humps'}{pre} = "<td>";
$t->{'humps'}{post} = "</td>";
$t->{'disposition'}{pre} = "<td>";
$t->{'disposition'}{post} = "</td>";
$t->{'species'}{pre} = "<tr><td>{\@name}</td>";
$t->{'species'}{post} = "</tr>";
%>
<html>
<head>
<title>Know Your Dromedaries</title>
</head>
<body>
  <table border="1">
    <tr><th>Species</th>
        <th>No. of Humps</th>
        <th>Disposition</th></tr>
    <%= apply_templates('/dromedaries/species') %>
  </table>
</body>
</html>

Save this file as test.xps.

Now to get the original file test.xml to be transformed on the server with text.xps we need to somehow associate that file with the stylesheet. Under AxKit there are a number of ways to do that with varying flexibility. The simplest way is to edit your test.xml file, and immediately after the <?xml version="1.0"?> declaration, add the following:

<?xml-stylesheet href="test.xps"
                 type="application/x-xpathscript"?>

Now assuming the files are both in the same directory under your httpd document root, you should be able to do a request for text.xml and see in your browser server side transformed XML. Now try changing the source XML file, and watch AxKit detect the change next time you load the file in the browser.

If things go wrong...

If you don't see HTML in your browser, but instead get the source XML in your browser (in Internet Explorer you will see a tree based representation of the XML, and in Mozilla or Netscape you will see all the text in the document joined together), then you will need to check your error log. AxKit sends out varying amounts of debug information depending on the value of AxDebugLevel (which we set to the maximum value of 10). If you can't decipher the contents of the error log, contact the AxKit User's mailing list at axkit-users@axkit.org with details of your problem.

How does it work?

The stylesheet above specifies how the various tags work. The ASP <% %> syntax delimits Perl code from HTML. You can execute any code within the stylesheet, however here we are making use of the special XPathScript $t hash ref. This specifies the names of tags, and how they should be output to the browser. There are several options for the second level of the hash, and here we see two of those options: pre and post. This specifies quite simply, what appears before the tag, and what appears after it. These values in $t only take affect when we call the apply_templates() function, which iterates over the nodes in the XML, executing the matching values in $t.

XPath

One of the key specifications being used in XML technologies is XPath. This is a little language used within other languages for selecting nodes within an XML document. The initial appearance is similar to that of Unix directory paths. In the above example we can see the XPath /dromedaries/species, which starts at the root of the document and finds first the dromedaries root element, then the species children of the dromedaries element. Note that unlike Unix directory paths, XPaths can match multiple nodes, so in the case above, we select all of the species elements in the document.

Documenting all of XPath here would take up many pages. The grammar for XPath allows many constructs of a full programming language, such as functions, string literals, and boolean expressions, but it is important to know that the syntax we are using to find nodes in our XML document is not just something invented for AxKit!

Dynamic Content

AxKit has a flexible tool for creating XML from various data sources such as relational databases, cookies, and form parameters, called eXtensible Server Pages, or XSP. This technology was originally invented by they Apache Cocoon team, and we share their syntax [F]3[/F]. This allows easier migration of projects to and from Cocoon.

XSP is an XML based syntax that uses namespaces to provide extensibility. In many ways this is like the Cold Fusion model, of using tags to provide dynamic functionality. One of the advantages of using XSP is that it is impossible to generate invalid XML, which makes it ideal for use in an XML framework like AxKit.

The XSP framework allows you to add in extra tags into your XML to provide custom functionality. These extra tags are called taglibs. By using taglibs, rather than embedding Perl code in your XSP page, you can further build on AxKit's separation of content from presentation, by separating out logic too. There are several taglibs that are available for AxKit's XSP engine already on CPAN.

Handling Form Parameters

The AxKit::XSP::Param taglib allows you to easily read form and querystring parameters within an XSP page. The following example shows how a page can submit back to itself. To allow this to work, the following needs to be added to your httpd.conf:

AxAddXSPTaglib AxKit::XSP::Param

Then the XSP page is:

<xsp:page
 xmlns:xsp="http://apache.org/xsp/core/v1"
 xmlns:param="http://axkit.org/NS/xsp/param/v1"
 language="Perl"
>
<page>
  <xsp:logic>
  if (<param:name/>) {
    <xsp:content>
     Your name is: <param:name/>
    </xsp:content>
  }
  else {
    <xsp:content>
      <form>
        Enter your name: <input type="text" name="name" />
        <input type="submit"/>
      </form>
    </xsp:content>
  }
  </xsp:logic>
</page>
</xsp:page>

The most significant factor about the above is how we freely mix XML tags with our Perl code, and the XSP processor figures out the right thing to do depending on context. There is a consequence of this, in that the XSP page itself must be valid XML, so the following would generate an error:

<xsp:logic>
my $page = <param:page/>;
if ($page < 3) { # ERROR: less-than is a reserved character in XML
 ...
}
</xsp:logic>

In order to get around this restriction, there are a number of ways we can code this in XML. The simplest is just to reverse the expression to if (3 > $page), because the greater-than sign is valid within an XML text section. Another way is to encode the less-than sign as &lt;, which will be familiar to HTML authors.

The other thing to notice is the <xsp:logic> and <xsp:content> tags. The former defines a section of Perl code, while the latter allows you to go back to processing the contents as XML output. It is also worth noting that the <xsp:content> tag is not always needed. Because the XSP engine inherently understands XML, you can omit the <xsp:content> tag when the immediate child would be an element, rather than text. Two examples would be:

<xsp:logic>
if (<param:name/>) {
  # xsp:content needed
  <xsp:content>
  Your name is: <param:name/>
  </xsp:content>
}
</xsp:logic>

versus the case when there is a surrounding non-XSP tag:

<xsp:logic>
if (<param:name/>) {
  # no xsp:content tag needed
  <p>Your name is: <param:name/></p>
}
</xsp:logic>

Note that the initial example, when processed only by the XSP engine, will output the following XML:

<page>
  <form>
    Enter your name: <input type="text" name="name" />
    <input type="submit"/>
  </form>
</page>

This needs processed with XSLT or XPathScript to be reasonably viewable in a browser, however the point is that you can re-use the above page as either HTML or WML just by applying different stylesheets.

Handling Cookies

AxKit::XSP::Cookie is a taglib interface to Apache::Cookie (part of the libapreq package). The following example demonstrates both retrieving and setting a cookie from within XSP. In order for this to run, the following option needs to be added to your httpd.conf:

AxAddXSPTaglib AxKit::XSP::Cookie

And the XSP page is:

<xsp:page
 xmlns:xsp="http://apache.org/xsp/core/v1"
 xmlns:cookie="http://axkit.org/NS/xsp/cookie/v1"
 language="Perl"
>
<page>
  <xsp:logic>
  my $value;
  if ($value = <cookie:fetch name="count"/>) {
    $value++;
  }
  else {
    $value = 1;
  }
  </xsp:logic>
  <cookie:create name="count">
    <cookie:value><xsp:expr>$value</xsp:expr></cookie:value>
  </cookie:create>
  <p>Cookie value: <xsp:expr>$value</xsp:expr></p>
</page>
</xsp:page>

This page introduces the concept of XSP expressions, using the <xsp:expr> tag. In XSP, everything that returns a value is an expression of some sort. In both of the above examples we have used a taglib tag within a Perl if() statement. These tags have both been expressions, even though they don't use the <xsp:expr> syntax. In XSP, everything understands its context, and tries to do the right thing. This way, the following three examples would work as expected:

<cookie:value>3</cookie:value>

<cookie:value><xsp:expr>2 + 1</xsp:expr></cookie:value>

<cookie:value><param:cookie_value/></cookie:value>

We see this as an extension of how Perl works - the idea of "Do What I Mean", or DWIM.

Sending Email

With the AxKit::XSP::Sendmail taglib it is very simple to send email from an XSP page. This taglib combines email address verification using the Email::Valid module, along with email sending using the Mail::Sendmail module (which will interface either to an SMTP server, or direct to the sendmail executable). Again, to allow usage of this taglib, the following line must be added to httpd.conf:

AxAddXSPTaglib AxKit::XSP::Sendmail

Then sending email from XSP is as simple as:

<xsp:page
 xmlns:xsp="http://apache.org/xsp/core/v1"
 xmlns:param="http://axkit.org/NS/xsp/param/v1"
 xmlns:mail="http://axkit.org/NS/xsp/sendmail/v1"
 language="Perl"
>
<page>
  <xsp:logic>
  if (!<param:email/>) {
    <p>You forgot to supply an email address!</p>
  }
  else {
    my $to;
    if (<param:subopt/> eq "sub") {
      $to = "axkit-users-subscribe@axkit.org";
    }
    elsif (<param:subopt/> eq "unsub") {
      $to = "axkit-users-unsubscribe@axkit.org";
    }
    <mail:send-mail>
     <mail:from><param:user_email/></mail:from>
     <mail:to><xsp:expr>$to</xsp:expr></mail:to>
     <mail:body>
      Subscribe or Unsubscribe <param:user_email/>
     </mail:body>
    </mail:send-mail>
    <p>(un)subscription request sent</p>
  }
  </xsp:logic>
</page>
</xsp:page>

The only thing missing here is some sort of error handling. When the sendmail taglib detects an error (either in an email address, or in sending the email), it throws an exception.

Handling Exceptions

The exception taglib, AxKit::XSP::Exception, is used to catch exceptions. The syntax is very simple, rather than allowing different types of exceptions, it is currently a very simple try/catch block. To use the exceptions taglib, the following has to be added to httpd.conf:

AxAddXSPTaglib AxKit::XSP::Exception

Then we can implement form validation using exceptions:

<xsp:page
 xmlns:xsp="http://apache.org/xsp/core/v1"
 xmlns:param="http://axkit.org/NS/xsp/param/v1"
 xmlns:except="http://axkit.org/NS/xsp/exception/v1"
 language="Perl"
>
<page>
 # form validation:
 <except:try>
  <xsp:logic>
  if ((<param:number/> > 10) || (0 > <param:number/>)) {
    die "Number must be between 0 and 10";
  }
  if (!<param:name/>) {
    die "You must supply a name";
  }
  # Now do something with the params
  </xsp:logic>
  <p>Values saved successfully!</p>
  <except:catch>
   <p>Sorry, the values you entered were
      incorrect: <except:message/></p>
  </except:catch>
 </except:try>
</page>

The exact same try/catch (and message) tags can be used for sendmail, and for ESQL (see below).

Utilities Taglib

The AxKit::XSP::Util taglib includes some utility methods for including XML, from the filesystem, from a URI, or as the return value from an expression (normally an expression would be rendered as plain text, and so a "<" character would be encoded as "&lt;"). The AxKit Util taglib is a direct copy of the Cocoon Util taglib, and as such uses the same namespace as the Cocoon Util taglib: http://apache.org/xsp/util/v1.

Executing SQL

Perhaps the most interesting taglib of all is the ESQL taglib, which allows you to execute SQL queries against a DBI compatible database, and provides access to the column return values as strings, scalars, numbers, dates, or even as XML (the latter uses the Util taglib, which must be installed in order to be able to use the ESQL taglib). Like the sendmail taglib, the ESQL taglib throws exceptions when an error occurs. One point of interest about the ESQL taglib is that it is a direct copy of the Cocoon ESQL taglib [F]4[/F], again helping you to port projects to or from Cocoon. As with all the other taglibs, ESQL requires the addition of the following to your httpd.conf:

AxAddXSPTaglib AxKit::XSP::ESQL

An example ESQL usage which reads data from an address book table is below. This page demonstrates how it is possible to re-use the same code for both our list of addresses, and viewing a single address in detail.

<xsp:page
 language="Perl"
 xmlns:xsp="http://apache.org/xsp/core/v1"
 xmlns:esql="http://apache.org/xsp/SQL/v2"
 xmlns:except="http://axkit.org/NS/xsp/exception/v1"
 xmlns:param="http://axkit.org/NS/xsp/param/v1"
 indent-result="no"
>
<addresses>
 <esql:connection>
  <esql:driver>Pg</esql:driver>
  <esql:dburl>dbname=phonebook</esql:dburl>
  <esql:username>postgres</esql:username>
  <esql:password></esql:password>
  <except:try>
  <esql:execute-query>
   <xsp:logic>
   if (<param:address_id/>) {
    <esql:query>
     SELECT * FROM address WHERE id =
     <esql:parameter><param:address_id/></esql:parameter>
    </esql:query>
   }
   else {
    <esql:query>
     SELECT * FROM address
    </esql:query>
   }
   </xsp:logic>
   <esql:results>
    <esql:row-results>
     <address>
      <esql:get-columns/>
     </address>
    </esql:row-results>
   </esql:results>
  </esql:execute-query>

<except:catch>
 Error Occured: <except:message/>
</except:catch>
</except:try>
     </esql:connection>
    </addresses>
    </xsp:page>

The result of running the above through the XSP processor is:

<addresses>
 <address>
  <id>2</id>
  <last_name>Sergeant</last_name>
  <first_name>Matt</first_name>
  <title>Mr</title>
  <company>AxKit.com Ltd</company>
  <email>matt@axkit.com</email>
  <classification_id>1</classification_id>
 </address>
</addresses>

More XPathScript Details

XPathScript aims to provide the power and flexibility of XSLT as an XML transformation language, without the restriction of XSLT's XML based syntax. Unlike XSLT, XPathScript only outputs plain text (XSLT has special modes for outputting in text, XML and HTML). This has advantages in being a lot easier to learn than XSLT for people coming from a Perl background, however XPathScript is not a W3C specification (although XPath, which XPathScript uses, is a W3C recommendation).

XPathScript follows the basic ASP syntax for introducing code, and outputting code to the browser; use <% %> to introduce Perl code, and <%= %> to output a value.

The XPathScript API

Along with the code delimiters XPathScript provides stylesheet developers with a full API for accessing and transforming the source XML file. This API can be used in conjunction with the delimiters above to provide a stylesheet language that is as powerful as XSLT, and yet provides all the features of a full programming language (in this case, Perl, but I'm certain that other implementations such as Python or Java would be possible).

Extracting Values

A simple example to get us started, is to use the API to bring in the title from a docbook article. A docbook article title looks like this:

<article>
 <artheader>
  <title>XPathScript - A Viable Alternative to XSLT?</title>
  ...

The XPath expression to retrieve the text in the title element is:

/article/artheader/title/text()

Putting this all together to make this text into the HTML title we get the following XPathScript stylesheet:

<html>
<head>
 <title><%= findvalue("/article/artheader/title") %></title>
</head>
<body>
  This was a DocBook Article. 
  We're only extracting the title for now!
<p>
The title was: <%= findvalue("/article/artheader/title") %>
</body>
</html>

Again we see the XPath syntax being used to find the nodes in the document, along with the function findvalue(). Similarly a list of nodes can be extracted (and thus looped over) using the findnodes() function:

...
<%
for my $sect1 (findnodes("/article/sect1")) {
  print $sect1->findvalue("title"), "<br>\n";
  for my $sect2 ($sect1->findnodes("sect2")) {
    print " + ", $sect2->findvalue("title"), "<br>\n";
    for my $sect3 ($sect2->findnodes("sect3")) {
      print " + + ", $sect3->findvalue("title"), "<br>\n";
    }
  }
}
%>
...

Here we see how we can apply the find* functions to individual nodes as methods, which makes the node the context node to search from, so $node->findnodes("title") finds <title> child nodes of $node.

Declarative Templates

We have already seen declarative templates in our "First AxKit Page" above. The $t hash is the key to declarative templates. The apply_templates() function iterates over the nodes of your XML file, applying the templates defined in the $t hash reference as it meets matching tags. This is the most important feature of XpathScript, because it allows you to define the appearance for individual tags without having to do your own iteration logic. We call this declarative templating.

The keys of $t are the names of the elements, including namespace prefixes where appropriate. When apply_templates() is called, XPathScript tries to find a member of $t that matches the element name.

The following sub-keys define the transformation:

• pre

  the output to occur before the tag.

• post

  the output to occur after the tag.

• prechildren

  the output to occur before the children of this tag are written.

• postchildren

  the output to occur after the children of this tag are written.

• prechild

  output to occur before every child element of this tag.

• postchild

  output to occur after every child element of this tag.

• showtag

  set to a false value (generally zero) to disable rendering of the tag itself.

• testcode

  code to execute upon visiting this tag.

More details about XPathScript can be found on the AxKit web page, at http://axkit.org/.

XSLT

One of the most important technologies to come out of the W3C is XSLT, or, Extensible Stylesheet Language Transformations. XSLT provides a way to transform one type of XML document into another using a language written entirely in XML. XSLT works by allowing developers to create one or more template rules that are applied to the various elements in the source document to produce a second, transformed document.

While the basic concept behind XSLT is quite simple (apply these rules to the elements that match these conditions), the finer points of writing good XSLT stylesheets is a huge topic that we could never hope to cover here. We will instead provide a small example that illustrates the basic XSLT syntax.

First, though, we need to configure AxKit to transform XML documents using an XSLT processor. For this example, we will assume that you already have the Gnome XSLT library (libxml2 and libxslt, available at http://xmlsoft.org/) and its associated Perl modules installed on your server.

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

Adding this line to your httpd.conf file tells AxKit to process all XML documents with a stylesheet processing instruction whose type is "text/xsl" with the LibXSLT language module.

Anatomy Of An XSLT Stylesheet

All XSLT stylesheets contain the following:

• An XML declaration.

• An <xsl:stylesheet> element as the document's root element.

• A template rule that matches the root-level element of document to be processed.

Consider the following bare-bones stylesheet:

<?xml version="1.0"?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="1.0">
  <xsl:template match="/">
    <!-- the content for the output document contained here -->
  </xsl:template>
</xsl:stylesheet>

Note that the root template (defined by the match="/" attribute) will be called without regard for the contents of the XML document being processed. As such, this the best place to put the top-level elements that we want to include in the output of each and every document being transformed with this stylesheet.

Template Rules And Recursion

Let's take our basic stylesheet and extend it to allow us to transform the following DocBook XML document (which we will call camelhistory.xml) into HTML:

<?xml version="1.0"?>
<book>
<title>Camels: An Historical Perspective</title>
<chapter>
  <title>Chapter One</title>
  <para>
     It was a dark and <emphasis>stormy</emphasis> night...
  </para>
</chapter>
</book>

First we need to alter the root template of our stylesheet:

<xsl:template match="/">
  <html>
    <head><xsl:copy-of select="/book/title"/></head>
    <body>
      <xsl:apply-templates/>
    </body>
  </html>
</xsl:template>

Here we have created the top-level structure of our output document and copied over the book's title element into the head element of out HTML page. The <xsl:apply-templates/> element tells the XSLT processor to pass the entire contents of the current element (in this case the <book> element, since it is the root-level element in the source document) on for further processing.

Now we need to create template rules for the other elements in the document:

<xsl:template match="chapter">
  <div class="chapter">
    <xsl:attribute name="id"><xsl:value-of 
    select="title"/></xsl:attribute>
    <xsl:apply-templates/>
  </div>
</xsl:template>
<xsl:template match="para">
  <p><xsl:apply-templates/></p>
</xsl:template>

Here we see more examples of recursive processing. The <para> and <chapter> elements are transformed into <div> and <p> elements and the contents of those elements are passed along for further processing. Note also that the XPath expressions used within the template rules are evaluated in the context of the current element. So, when we select the value of the title element to create the id attribute for the div tag, we are really saying "select the value of the title element that is a child of the current chapter element".

While this sort of recursive processing is extremely powerful, it can also be quite a performance hit and is only necessary for those cases where the current element contains other elements that need to be processed. If we know that a particular element will not contain any other elements, we need only return that element's text value.

<xsl:template match="emphasis">
  <em><xsl:value-of select="."/></em>
</xsl:template>
<xsl:template match="chapter/title">
  <h2><xsl:value-of select="."/></h2>
</xsl:template>
<xsl:template match="book/title">
  <h1><xsl:value-of select="."/></h1>
</xsl:template>
</xsl:stylesheet>

Look closely at the last two template elements. Both match a <title> element, but one defines the rule for handling titles whose parent is a book element, while the other handles the chapter titles. In fact, any valid XPath expression, XSLT function call, or combination of the two can be used to define the match rule for a template element.

Finally, we need only save our stylesheet as docbook-snippet.xsl. Once our source document is associated with this stylesheet (see the section titled Putting It Together in this appendix), if we point our browser to camelhistory.xml we will get the following output:

<?xml version="1.0"?>
<html>
  <head>
    <title>Camels: An Historical Perspective</title>
  </head>
  <body>
    <h1>Camels: An Historical Perspective</h1>
    <div class="chapter" id="Chapter One">
      <h2>Chapter One</h2>
      <p>
         It was a dark and <em>stormy</em> night...
      </p>
    </div>
  </body>
</html>

Learning More

We have only scratched the surface of how XSLT can be used to transform XML documents. For more information, see the following resources:

• The XSLT Specification: http://www.w3.org/TR/xslt

• Miloslav Nic's XSLT Reference: http://www.zvon.org/xxl/XSLTreference/Output/index.html

• Jeni Tennison's XSLT FAQ: http://www.jenitennison.com/xslt/index.html

Also note that the complete set of files for the above example XSLT code is available at http://axkit.org/examples/book-xslt.tar.gz

Putting Everything Together

The last key peice to AxKit is how everything is tied together. We have a clean separation of logic, presentation and content, but we've only briefly introduced using processing instructions for setting up the way a file gets processed through the AxKit engine. A generally better and more scalable way to work is to use the AxKit configuration directives to specify how to process files through the system.

Before introducing the configuration directives in detail, it is worth looking at how the W3C sees the evolving web of new media types. The HTML 4.0 specification defined 8 media types:

• screen - the default media type, for normal web browsers.

• tty - a media type for tty based devices (e.g. the lynx web browser).

• printer

• handheld

• braille - for braille interpreters

• tv - for devices such as Microsoft's WebTV and Sony's Playstation2 that have a TV based browser.

• projection - for projectors

• aural - for devices that can convert the output to spoken words

AxKit allows you to plug in modules that can detect these different media types, allowing you to deliver the same content in different ways. For finer grained control, you can use named stylesheets (where you might have a printable page output to the screen media type, as seen on many magazine sites such as http://take23.org/ for displaying multi-page articles).

For example, to map all files with extension .dkb to a DocBook stylesheet, you would use the following directives:

<Files *.dkb>
AxAddProcessor text/xsl /stylesheet/docbook.xsl
</Files>

Now if you wanted to display those DocBook files on WebTV as well as ordinary web browsers, but you wanted to use a different stylesheet for WebTV, you would use:

<Files *.dkb>
  <AxMediaType tv>
    AxAddProcessor text/xsl /stylesheets/docbook_tv.xsl
  </AxMediaType>
  <AxMediaType screen>
    AxAddProcessor text/xsl /stylesheets/docbook_screen.xsl
  </AxMediaType>
</Files>

Now let's extend that to chained transformations. Lets say you wanted to build up a table of contents the same way in both views. One way you could do it is to modularize the stylesheet. However it's also possible to chain transformations in AxKit, simply by defining more than one processor for a particular resource:

<Files *.dkb>
  AxAddProcessor text/xsl /stylesheets/docbook_toc.xsl
  <AxMediaType tv>
    AxAddProcessor text/xsl /stylesheets/docbook_tv.xsl
  </AxMediaType>
  <AxMediaType screen>
    AxAddProcessor text/xsl /stylesheets/docbook_screen.xsl
  </AxMediaType>
</Files>

Now the TV based browsers will see DocBook first tranformed by docbook_toc.xsl, then the output of that transformation would be processed by docbook_tv.xsl.

This is exactly how we would build up an application using XSP:

<Files *.xsp>
  AxAddProcessor application/x-xsp .
  <AxMediaType tv>
    AxAddProcessor text/xsl /stylesheets/page2tv.xsp
  </AxMediaType>
  <AxMediaType screen>
    AxAddProcessor text/xsl /stylesheets/page2html.xsp
  </AxMediaType>
</Files>

This resolves the earlier issue we had where the XSP did not output HTML - instead it output something entirely different. Now we can see why - because this way we can build dynamic web applications that work easily on different devices!

There are 4 other config directives similar to AxAddProcessor, which take an additional parameter specifying a particular way to examine the file being processed. These each take an additional parameter to facilitate the match.

• AxAddRootProcessor

  takes a root element name to match the first (root) element in the XML document. For example:

  AxAddRootProcessor text/xsl article.xsl article

  Would process all XML files with a root element of <article> with the article.xsl stylesheet.

• AxAddDocTypeProcessor

  processes XML documents with the given XML public identifier.

• AxAddDTDProcessor

  processes all XML documents that use the DTD given as the third option.

• AxAddURIProcessor

  processes all resources at the matching URI (which is a Perl regexp).

  This option was added for two reasons - firstly that the <LocationMatch> directive is not allowed in a .htaccess file, and secondly that the built in Apache regular expressions are not terribly powerful (for example they cannot do negative matches).

Finally, the <AxStyleName> block allows you to specify named stylesheets. An example that implements printable/default views of a document might be:

<AxMediaType screen>
  <AxStyleName #default>
    AxAddProcessor text/xsl /styles/article_html.xsl
  </AxStyleName>
  <AxStyleName printable>
    AxAddProcessor text/xsl /styles/article_html_print.xsl
  </AxStyleName>
</AxMediaType>

By mixing the various embedded tags, it is possible to build up a very feature rich sitemap of how your files get processed.

Footnotes

1 The W3C calls it's approved specifications "Recommendations", rather than "standards", because they are an industry consortium, rather than a standards body. However most people consider thier recommendations to be standards, because they almost always become de-facto standards.

2 AxKit is very flexible in how it lets you transform the XML on the server, and there are many modules you can plug in to AxKit to allow you to do these transformations. For this reason, the AxKit installation does not mandate any particular modules to use, instead it will simply suggest modules that might help when you install AxKit.

3 While we share the XSP syntax with Cocoon, Cocoon allows you to embed Java code in your XSP, while AxKit only allows you to embed Perl code.

4 AxKit and Cocoon's ESQL taglibs are identical apart from a few minor deviations, such as how columns of different types are returned, and how errors are trapped (in Cocoon there are ESQL tags for trapping errors, whereas AxKit uses exceptions).

List of Links