<?xml version="1.0"?>
<?xml-stylesheet href="/stylesheets/docbook_screen.xps"
type="application/x-xpathscript"
media="screen"
title="default"
?>
<?xml-stylesheet href="/stylesheets/docbook_print.xps"
type="application/x-xpathscript"
title="print"
alternate="yes"
?>
<!DOCTYPE article [
<!ENTITY prompt "% ">
]>
<article>
<artheader>
<title>AxKit Quickstart Guide</title>
<author>
<firstname>Kip</firstname>
<surname>Hampton</surname>
<affiliation>
<address><email>khampton@totalcinema.com</email></address>
</affiliation>
</author>
<abstract>
<para>
This document is a <emphasis>quick start</emphasis> 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 <ulink url=
"http://axkit.org/docs/introduction.dkb">Introduction to AxKit</ulink>.
</para>
<para>
</para>
</abstract>
</artheader>
<sect1>
<title>Installing and Configuring AxKit</title>
<para>
This guide presumes that you already have an
<ulink url ="http://www.apache.org/httpd.html">Apache</ulink> httpd server running
<ulink url="http://perl.apache.org/">mod_perl</ulink>. If this is not
the case, please visit the <ulink url
="http://www.apache.org/httpd.html">Apache
</ulink> and <ulink url="http://perl.apache.org/">mod_perl</ulink> pages for
more information.
</para>
<sect2>
<title>Step 1 - Download and Install AxKit</title>
<para>
First, visit the AxKit <ulink url="http://www.axkit.org/download/">
download directory</ulink> and grab the latest tarball. Once you've
downloaded the source, type the following:
<informalexample>
<programlisting>
&prompt; <userinput>tar -zxvf AxKit-x.xx.tar.gz</userinput>
&prompt; <userinput>cd AxKit-x.xx/</userinput>
&prompt; <userinput>perl Makefile.PL</userinput>
&prompt; <userinput>make</userinput>
&prompt; <userinput>make test</userinput>
&prompt; <userinput>make install</userinput>
</programlisting>
</informalexample>
If <literal>perl Makefile.PL</literal> 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.
</para>
</sect2>
<sect2>
<title>Step 2 - Edit Your httpd.conf File</title>
<para>
Add the following lines to your httpd.conf:
<informalexample>
<programlisting>
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
</programlisting>
</informalexample>
</para>
<para>
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 <emphasis>all but the first</emphasis>
configuration directive in a <ulink
url="http://www.apache.org/docs/mod/core.html#location"
><literal><Location></literal></ulink> section. Note that the first
line: <literal>PerlModule AxKit</literal> <emphasis>MUST</emphasis>
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.
</para>
<para>
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!
</para>
</sect2>
</sect1>
<sect1>
<title>Installing the Sablotron XSLT Processor (Optional)</title>
<para>
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 <ulink url="quick_start.dkb?section=3">next section</ulink>.
</para>
<sect2>
<title>Step 1 - Download and Install the Sablotron XSLT
Processor</title>
<para>
Next, fetch either the source or appropriate binary distribution of the
Sablotron XSLT Processor from <ulink url="http://www.gingerall.com/">
www.gingerall.com</ulink>. As of version 0.50, Sablotron requires the shared library version
of the Expat XML parser to be installed before installing Sablotron. Visit <ulink url=
"http://sourceforge.net/projects/expat/">the Expat project page</ulink> for sources and
installation instructions.
</para>
<para>
Installing Sablotron from the source:
<informalexample>
<programlisting>
&prompt; <userinput>tar -zxvf Sablot-x.xx.tar.gz</userinput>
&prompt; <userinput>cd Sablot-x.xx/</userinput>
&prompt; <userinput>./configure</userinput>
&prompt; <userinput>make</userinput>
&prompt; <userinput>make install</userinput>
</programlisting>
</informalexample>
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.
</para>
</sect2>
<sect2>
<title>Step 2 - Install the XML::Sablotron Perl Library</title>
<para>
Next, install XML::Sablotron. You can either install the package by hand or use the CPAN
shell. To install using the CPAN shell type:
<informalexample>
<programlisting>
&prompt; <userinput>perl -MCPAN -e shell</userinput>
&prompt; <userinput>install XML::Sablotron</userinput>
</programlisting>
</informalexample>
To install the packages yourself, get the latest version of the XML::Sablotron Perl package
from <ulink url="http://www.gingerall.com/">www.gingerall.com</ulink>, cd to the
directory you downloaded the tarball to and type:
<informalexample>
<programlisting>
&prompt; <userinput>tar -zxvf XML-Sablot-x.xx.tar.gz</userinput>
&prompt; <userinput>mv XML-Sablot-x.xx/ Sablot-x.xx/</userinput>
&prompt; <userinput>cd Sablot-x.xx/XML-Sablot-x.xx/</userinput>
&prompt; <userinput>perl Makefile.PL</userinput>
&prompt; <userinput>make</userinput>
&prompt; <userinput>make test</userinput>
&prompt; <userinput>make install</userinput>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
<sect1>
<title>Sample Document Transformations</title>
<para>
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.
</para>
<sect2>
<title>Step 1 - A Sample XML Document</title>
<para>
First, you will need a sample XML file. Open the text editor of your choice
and type the following:
<informalexample>
<programlisting><![CDATA[
<?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>
]]></programlisting>
</informalexample>
Save this file as test.xml.
</para>
</sect2>
<sect2>
<title>Step 2 - Create a Stylesheet</title>
<para>
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.
</para>
</sect2>
<sect2>
<title>Using XSLT</title>
<para>
Start a new file and type the following:
<informalexample>
<programlisting><![CDATA[
<?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>
]]></programlisting>
</informalexample>
Save this file as test.xsl.
</para>
</sect2>
<sect2>
<title>Using XPathScript</title>
<para>
Create a new file and type:
<informalexample>
<programlisting><![CDATA[
<%
$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>
]]></programlisting>
</informalexample>
Save this file as test.xps.
</para>
</sect2>
<sect2>
<title>Step 3 - Associate the XML Document with your Stylesheet</title>
<para>
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:
<informalexample>
<programlisting><![CDATA[
<?xml-stylesheet href="test.xsl" type="text/xsl"?>
]]></programlisting>
</informalexample>
Or, if you have chosen the XPathScript sample, use:
<informalexample>
<programlisting><![CDATA[
<?xml-stylesheet href="test.xps" type="application/x-xpathscript"?>
]]></programlisting>
</informalexample>
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.
</para>
</sect2>
<sect2>
<title>Step 4 - Finishing Up</title>
<para>
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.
</para>
<para>
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 <ulink url="http://www.axkit.org/">AxKit homepage</ulink>.
</para>
</sect2>
<sect2>
<title>If Things Go Wrong</title>
<para>
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 <ulink url=
"http://axkit.org/faq.xml">AxKit FAQ</ulink>, and the AxKit User's <ulink url=
"http://axkit.org/cgi-bin/ezmlm-cgi/4">mailing list archives</ulink>.
</para>
</sect2>
</sect1>
<sect1>
<title>Other Resources</title>
<sect2>
<title>mod_perl</title>
<para>
<itemizedlist>
<listitem><ulink url="http://perl.apache.org">mod_perl Homepage</ulink>
</listitem>
<listitem><ulink url="http://perl.apache.org/guide/">mod_perl Guide
</ulink>
</listitem>
<listitem><ulink url="http://www.modperl.com/">Writing Apache Modules
with Perl and C</ulink>
</listitem>
<listitem><ulink url="http://take23.org/">mod_perl News and Information</ulink>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<title>XSLT</title>
<para>
<itemizedlist>
<listitem><ulink url="http://www.w3.org/Style/XSL/">W3C Specification
</ulink></listitem>
<listitem><ulink url="http://www.xml.com/pub/Guide/XSLT">XSLT Resources at XML.com
</ulink></listitem>
<listitem><ulink url="http://www.mulberrytech.com/quickref/index.html">Mulberry
Technologies' XPath and XSLT quick reference card (PDF).</ulink></listitem>
<listitem><ulink url="http://www.zvon.org/xxl/XSLTreference/Output/index.html">An
expanded XSLT reference from zvon.org.</ulink></listitem>
<listitem><ulink url="http://www.xslt.com/">XSLT.com</ulink></listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<title>XPathScript</title>
<para>
<itemizedlist>
<listitem><ulink url="http://axkit.org/docs/xpathscript/guide.dkb">XPathScript - A Viable
Alternative to XSLT?</ulink></listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</article>