<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet href="/docbook_screen.xps" type="application/x-xpathscript"
title="default"?>
<?xml-stylesheet href="/docbook_print.xps"
type="application/x-xpathscript" title="print" alternate="yes"?>
<!DOCTYPE article [
<!ENTITY prompt "&#x25; ">
<!ENTITY grammar SYSTEM "grammar">
]>
<article>

<artheader>
	<title>Getting Started with AxKit</title>
	
	<author>
		<firstname>Matt</firstname>
		<surname>Sergeant</surname>
		<affiliation>
			<address><email>matt@sergeant.org</email></address>
		</affiliation>
	</author>
	
	<copyright>
		<year>2000</year>
		<holder role="mailto:matt@sergeant.org">Fastnet Software Ltd</holder>
	</copyright>

	<abstract>
		<para>This document explains how to get started building your
		web site with AxKit.</para>
	</abstract>
</artheader>

<sect1>
<title>First Steps</title>
<para>
The first thing to do is to get AxKit downloaded and installed. AxKit is
available from <ulink
url="http://xml.sergeant.org/download/">xml.sergeant.org/download</ulink>.
Please make sure you download the latest version, as AxKit is improving
regularly, and works on the basis of "release early, release often". For
this reason it is also worth joining the AxKit mailing list to hear about
updates.
</para>
<para>
Next the installation. Currently there is no automated installation for
AxKit. However AxKit follows the basic Perl module installation
semantics as detailed in the
<citerefentry><refentrytitle>perlmodinstall</refentrytitle></citerefentry>
perl manual page. To save you following that page, here are the details.
First, unpack the archive:
<informalexample>
<screen>
&prompt;<userinput>gunzip -c AxKit-&lt;version>.tar.gz | tar xv</userinput>
</screen>
</informalexample>
Then <literal>cd</literal> to the directory created and build the
software:
<informalexample>
<screen>
&prompt;<userinput>perl Makefile.PL</userinput>
&prompt;<userinput>make</userinput>
&prompt;<userinput>make test</userinput>
</screen>
</informalexample>
Finally, <literal>su</literal> to the root account and install:
<informalexample>
<screen>
&prompt;<userinput>su</userinput>
<prompt>password:</prompt>
root &prompt;<userinput>make install</userinput>
</screen>
</informalexample>
</para>
<para>
This gives us the AxKit perl modules installed on our system. To install
AxKit into our Apache httpd we first need mod_perl installed. Installing
mod_perl is beyond the scope of this document. There are many varied
ways of installing mod_perl, and numerous different versions of Apache
out there (such as the Stronghold Apache server). Instead I'll simply
point out a few resources:
<itemizedlist>
	<listitem>The official mod_perl pages: <ulink
	url="http://perl.apache.org/"
	>http://perl.apache.org/</ulink></listitem>
	<listitem>The mod_perl guide: <ulink
	url="http://perl.apache.org/guide"
	>http://perl.apache.org/guide</ulink></listitem>
	<listitem>The guide's section on installation: <ulink
	url="http://perl.apache.org/guide/install.html"
	>http://perl.apache.org/guide/install.html</ulink></listitem>
	<listitem>The apache homepage: <ulink
	url="http://www.apache.org/httpd.html"
	>http://www.apache.org/httpd.html</ulink></listitem>
	<listitem>Stronghold: <ulink url="http://www.c2.net/"
	>http://www.c2.net</ulink></listitem>
	<listitem>IBM HTTP Server: <ulink
	url="http://www.software.ibm.com/webservers/httpservers"
	>http://www.software.ibm.com/webservers/httpservers</ulink></listitem>
</itemizedlist>
</para>
<para>
Now once mod_perl is installed into your Apache server and you've tested
the successful installation (best achieved by using a
<literal>HEAD</literal> request to the browser and checking for the
mod_perl header in the <literal>Server:</literal> line), we need to add
AxKit to the Apache server at server startup time so that our
AxKit configuration directives are recognised. To do this, add the
following line to your httpd.conf file:
<informalexample>
<programlisting>
PerlModule AxKit
</programlisting>
</informalexample>
You will need to restart Apache for this to take affect.
</para>
<para>
That's AxKit installed. Of course it doesn't do anything until we
configure it. So, on to the next step.
</para>
</sect1>

<sect1>
<title>A Simple AxKit Project</title>
<para>
We'll now go through the steps involved in creating your own AxKit XML
project. We'll build up a simple home page example, and allow delivery
of that home page to web browsers in 2 alternate styles, and also
delivery to WAP capable devices. Along the way we'll build in some
interactive content telling the user the current time the page was
requested. To do all of this we'll use the W3C standard language XSLT
and the Apache Project's XSP language, which you can learn more about
<ulink url="http://www.plenix.com/xsp/">here</ulink> (not that all of
the XSP samples outside of the AxKit web pages show Java code, whereas AxKit
only supports Perl in it's XSP pages).
</para>
<para>
Before we start writing our XML pages and the XSL transformations, we
need to setup a new directory on the web server to work in. There
are two options with that, the easiest is to create a directory under
your document root and use a <filename>.htaccess</filename> file to set
your configuration up. However your server might not allow .htaccess
files for performance reasons (although I personally find the
performance penalty negligable when using .htaccess files). Lets first
build our directory, assuming our document root is
<filename>/usr/local/apache/htdocs/</filename>:
<informalexample>
<screen>
&prompt;<userinput>cd /usr/local/apache/htdocs</userinput>
&prompt;<userinput>mkdir -m 0755 axkit_test</userinput>
</screen>
</informalexample>
Note the directory mode allowing the no-privileges web user to read the
directory.
</para>
<para>
Now we can build our XML file.
Lets start by designing a simple specification for our home page. In XML
terms we call that a DTD, which simply says what tags can come where. By
designing a DTD this way, instead of writing our pages in HTML we write
them to our design, and generate the HTML using templates. This allows
us to change the appearance of our entire web site by simply changing
our templates. Here's a simple home page DTD that we'll be using:
<informalexample>
<programlisting><![CDATA[
<!ELEMENT page (head, body)>

<!ELEMENT head (title)>

<!ELEMENT title (#PCDATA)>

<!ELEMENT body (section*)>

<!ELEMENT section (title, para*)>

<!ENTITY % maintags "#PCDATA|link|ul|ol|emphasis">

<!ELEMENT para (&maintags;)*>

<!ELEMENT link (#PCDATA)>
<!ATTLIST link url CDATA #REQUIRED>

<!ELEMENT ul (li)*>
<!ELEMENT ol (li)*>

<!ELEMENT li (&maintags;)*>

<!ELEMENT emphasis (#PCDATA)>
]]></programlisting>
</informalexample>
</para>
<para>
To anyone new to XML that might appear a confusing mess - like stumbling
upon some Perl code for the first time, so lets have an example of
something we can produce with this:
<informalexample>
<programlisting><![CDATA[
<page>
<head>
	<title>My First Home Page</title>
</head>
<body>
	<section>
	<title>Hello!</title>
	<para>Welcome to my home page. Here are a few things you can find
	from here:
	<ul>
		<li><link url="pets.xml">My Pets Page</link></li>
		<li><link url="bikes.xml">My Page about Bikes</link></li>
		<li><link url="girls.xml">Why I hate girls</link></li>
	</ul>
	</para>
	</section>
</body>
</page>
]]></programlisting>
</informalexample>
Save this as index.xml in our new axkit_test directory.
</para>
<para>
This is a very simple page, and if you've been working with HTML up
until this point you might want to scream and tell me it's going to look
incredibly ugly. But the point is separation of content from style. We
use the XML file to create our content, and the stylesheets to make the
content look good in different formats. This flexible approach allows us
to automate the task of building a "printer friendly" version of our
page, or a version of our page for WAP capable devices.
</para>
<para>
Now lets add in some <emphasis>interactivity</emphasis>, to show that
with AxKit it is possible to build more than just static documents. With
AxKit and XSP (XML Server Pages) it is possible to create custom tags
for interactive content, so that you can truly separate out the job of
page design and programmed content. However if you prefer, you can also
use in-line code within your XML. Here we shall demonstrate adding in a
custom tag and designing our own tag library.
</para>
<para>
Lets add in a new section immediately after the
<literal>&lt;/section></literal> tag in the above file:
<informalexample>
<programlisting><![CDATA[
	...
	<section>
	<title>Display Time</title>
	<para>
	The current time where I am is: <util:time_now/>.
	</para>
	</section>
	...
]]></programlisting>
</informalexample>
We'll worry about implementing the <literal>&lt;util:time_now></literal>
tag later.
</para>

<para>
Now we 
</para>

</sect1>
</article>
