Kip Hampton

khampton@totalcinema.com

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. 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. First, visit the AxKit download directory and grab the latest tarball. Once you've downloaded the source, type the following: &prompt; tar -zxvf AxKit-x.xx.tar.gz &prompt; cd AxKit-x.xx/ &prompt; perl Makefile.PL &prompt; make &prompt; make test &prompt; 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. Add the following lines to your httpd.conf: PerlModule AxKit SetHandler perl-script PerlHandler AxKit AxAddStyleMap application/x-xpathscript Apache::AxKit::Language::XPathScript # 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! 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. 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: &prompt; tar -zxvf Sablot-x.xx.tar.gz &prompt; cd Sablot-x.xx/ &prompt; ./configure &prompt; make &prompt; 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. Next, install XML::Sablotron. You can either install the package by hand or use the CPAN shell. To install using the CPAN shell type: &prompt; perl -MCPAN -e shell &prompt; 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: &prompt; tar -zxvf XML-Sablot-x.xx.tar.gz &prompt; mv XML-Sablot-x.xx/ Sablot-x.xx/ &prompt; cd Sablot-x.xx/XML-Sablot-x.xx/ &prompt; perl Makefile.PL &prompt; make &prompt; make test &prompt; make install 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: 1 or 2 Cranky 1 (sort of) Aloof (see Llama) Friendly ]]> Save this file as test.xml. 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. Start a new file and type the following:

Species	No of Humps	Disposition

]]> Save this file as test.xsl. Create a new file and type: {'humps'}{'pre'} = ""; $t->{'humps'}{'post'} = ""; $t->{'disposition'}{'pre'} = ""; $t->{'disposition'}{'post'} = ""; $t->{'species'}{testcode} = sub { my $node = shift; my $t = shift; $t->{pre} = '' . findvalue('@name', $node) . ''; $t->{post} = ""; return 1; } %> <%= apply_templates('/dromedaries/species') %>

Species	No. of Humps	Disposition

]]> Save this file as test.xps. 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: ]]> Or, if you have chosen the XPathScript sample, use: ]]> 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. 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. As I stated in the introduction, this is document is designed to walk someone through the AxKit instalation process, 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. mod_perl Homepage mod_perl Guide Writing Apache Modules with Perl and C mod_perl News and Information W3C Specification XSLT Resources at XML.com Mulberry Technologies' XPath and XSLT quick reference card (PDF). An expanded XSLT reference from zvon.org. XSLT.com XPathScript - A Viable Alternative to XSLT?