Sun Oct 31 21:28:04 2004

Abstract

This document is a quick start guide designed to help developers deliver transformed XML with AxKit as quickly as possible. As such, many of the finer points of AxKit's extremely robust interface will not be covered. For a more descriptive introduction, please see Matt's Introduction to AxKit.

Installing and Configuring AxKit

This guide presumes that you already have an Apache httpd server running mod_perl. If this is not the case, please visit the Apache and mod_perl pages for more information.

Step 1 - Download and Install AxKit

First, visit the AxKit download directory and grab the latest tarball. Once you've downloaded the source, type the following:

%  tar -zxvf AxKit-x.xx.tar.gz
%  cd AxKit-x.xx/
%  perl Makefile.PL
%  make
%  make test
%  make install

If perl Makefile.PL warns about missing modules, make a note of these dependencies and install the corresponding Perl packages before proceeding with the AxKit installation. AxKit will not be properly installed, otherwise.

Step 2 - Edit Your httpd.conf File

Add the following lines to your httpd.conf:

PerlModule AxKit
SetHandler perl-script
PerlHandler AxKit
AxAddStyleMap application/x-xpathscript Apache::AxKit::Language::XPathScript
AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT

# add the following only if you intend to install Sablotron
AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot

Don't worry that this looks like AxKit will deliver all of your files, if it doesn't detect XML at the URL you give it, it will let the httpd deliver it as normal. If you're still concerned, put all but the first configuration directive in a <Location> section. Note that the first line: PerlModule AxKit MUST occur in your httpd.conf so that it is parsed in the parent httpd process. This is because it adds configuration directives to the entire Apache httpd. If you do not do this you will get SEGFAULTs.

Now, stop and restart your Apache server and assuming you've had no trouble with the steps above, you are now ready to begin publishing transformed XML with AxKit!

Installing the Sablotron XSLT Processor (Optional)

This section assumes that you will be installing the Sablotron XSLT processor along with AxKit. If you want to see AxKit in action but do not want to install Sablotron you may safely skip to the next section.

Step 1 - Download and Install the Sablotron XSLT Processor

Next, fetch either the source or appropriate binary distribution of the Sablotron XSLT Processor from www.gingerall.com. As of version 0.50, Sablotron requires the shared library version of the Expat XML parser to be installed before installing Sablotron. Visit the Expat project page for sources and installation instructions.

Installing Sablotron from the source:

%  tar -zxvf Sablot-x.xx.tar.gz
%  cd Sablot-x.xx/
%  ./configure
%  make
%  make install

Please note that Sablotron build process described here covers versions 0.50. Consult the INSTALL and README files that shipped with the version you downloaded for details and possible changes.

Step 2 - Install the XML::Sablotron Perl Library

Next, install XML::Sablotron. You can either install the package by hand or use the CPAN shell. To install using the CPAN shell type:

%  perl -MCPAN -e shell
%  install XML::Sablotron

To install the packages yourself, get the latest version of the XML::Sablotron Perl package from www.gingerall.com

, cd to the directory you downloaded the tarball to and type:

%  tar -zxvf XML-Sablot-x.xx.tar.gz
%  mv XML-Sablot-x.xx/ Sablot-x.xx/
%  cd Sablot-x.xx/XML-Sablot-x.xx/
%  perl Makefile.PL
%  make
%  make test
%  make install

Sample Document Transformations

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.

Step 1 - A Sample XML Document

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 (sort of)</humps>
      <disposition>Aloof</disposition>
    </species>
    <species name="Alpaca">
      <humps>(see Llama)</humps>
      <disposition>Friendly</disposition>
    </species>
</dromedaries>

Save this file as test.xml.

Step 2 - Create a Stylesheet

Now, create the stylesheet to transform your XML document. If you have chosen to install Sablotron or one of the other XSLT processors that AxKit supports you may use either the XSLT or XPathScript samples below . If you have not installed an XSLT processor skip directly to the XPathScript example.

Using XSLT

Start a new file and type the following:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:template match="/">
  <html>
  <head><title>Know Your Dromedaries</title></head>
  <body>
    <table bgcolor="eeeeee" border="1">
    <tr>
    <th>Species</th>
    <th>No of Humps</th>
    <th>Disposition</th>
    </tr>
    <xsl:for-each select="dromedaries">
      <xsl:apply-templates select="./species" />
  </xsl:for-each>
  </table>
  </body>
  </html>
</xsl:template>
<xsl:template match="species">
  <tr>
  <td><xsl:value-of select="@name" /></td>
  <td><xsl:value-of select="./humps" /></td>
  <td><xsl:value-of select="./disposition" /></td>
  </tr>
</xsl:template>
</xsl:stylesheet>

Save this file as test.xsl.

Using XPathScript

Create a new file and type:

<%
$t->{'humps'}{'pre'} = "<td>";
$t->{'humps'}{'post'} = "</td>";
$t->{'disposition'}{'pre'} = "<td>";
$t->{'disposition'}{'post'} = "</td>";
$t->{'species'}{testcode} = sub {
    my $node = shift;
    my $t = shift;
    $t->{pre} = '<tr><td>' . findvalue('@name', $node) . '</td>';
    $t->{post} = "</tr>";
    return 1;
}
%>

<html>
<head>
        <title>Know Your Dromedaries</title>
</head>
<body bgcolor="white">
    <table bgcolor="eeeeee" 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.

Step 3 - Associate the XML Document with your Stylesheet

Next, re-open the test.xml file and add the following just after the <?xml version="1.0"?> declaration. If you have selected the XSLT example, add:

<?xml-stylesheet href="test.xsl" type="text/xsl"?>

Or, if you have chosen the XPathScript sample, use:

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

Note that this line is telling AxKit which stylesheet to use and which handler to use for that stylesheet. Now, save the test.xml file and quit your editor.

Step 4 - Finishing Up

You are now ready to deliver your little zoological XML data file as formatted HTML! Just copy or move the XML and stylesheet files into the same directory under your httpd DocumentRoot. Then, point your browser to http://your-server.com/path/to/test.xml and you should see your data nicely formatted in an HTML table.

Congratulations, you are now well on the road to adding XML, XSLT, XPathScript and AxKit to your developmental toolbelt. For more information about AxKit's advanced features, please visit the AxKit homepage.

If Things Go Wrong

As I stated in the introduction, this document is designed to walk someone through the AxKit instalation process, then, on to serving transformed documents as quickly and simply as possible. Depending upon your setup, installing AxKit may require some special attention to get it to sanely co-exist with some of the other tools that you may be using. If you've had any trouble while following the steps outlined here, please consult the AxKit FAQ, and the AxKit User's mailing list archives.