/usr/man/cat.3/AxKit.3.Z(/usr/man/cat.3/AxKit.3.Z)

NAME

       AxKit - an XML Application Server for Apache

DESCRIPTION

       AxKit provides the user with an application development environment for
       mod_perl, using XML, Stylesheets and a few other tricks. See
       http://axkit.org/ for details.

SYNOPSIS

       In httpd.conf:

           # we add custom configuration directives
           # so this *must* be in httpd.conf *outside* of
           # all run time configuration blocks (e.g. <Location>)
           PerlModule AxKit

       Then in any Apache configuration section (Files, Location, Directory,
       .htaccess):

           # Install AxKit main parts
           SetHandler AxKit

           # Setup style type mappings
           AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
           AxAddStyleMap application/x-xpathscript \
                   Apache::AxKit::Language::XPathScript

           # Optionally set a hard coded cache directory
           # make sure this is writable by nobody
           AxCacheDir /opt/axkit/cachedir

           # turn on debugging (1 - 10)
           AxDebugLevel 5

       Now simply create xml files with stylesheet declarations:

           <?xml version="1.0"?>
           <?xml-stylesheet href="test.xsl" type="text/xsl"?>
           <test>
               This is my test XML file.
           </test>

       And for the above, create a stylesheet in the same directory as the
       file called "test.xsl" that compiles the XML into something usable by
       the browser. If you wish to use other languages than XSLT, you can,
       provided a module exists for that language. AxKit does not internally
       have a built-in XSLT interpreter, instead it relies on interfaces to
       other Perl modules. We currently have interfaces in the core package to
       XML::Sablotron, XML::LibXSLT, and XML::XSLT.

CONFIGURATION DIRECTIVES

       AxKit installs a number of new first class configuration directives for
       you to use in Apache's httpd.conf or .htaccess files. These provide
       very fine grained control over how AxKit performs transformations and
       sends its output to the user.

       Each directive below is listed along with how to use that directive.

       AxCacheDir

       This option takes a single argument, and sets the directory that the
       cache module stores its files in. These files are an MD5 hash of the
       file name and some other information. Make sure the directory you spec-
       ify is writable by either the nobody user or the nobody group (or what-
       ever user your Apache servers run as). It is probably best to not make
       these directories world writable!

           AxCacheDir /tmp/axkit_cache

       AxNoCache

       Turn off caching. This is a FLAG option - On or Off. Default is "Off".
       When this flag is set, AxKit will send out Pragma: no-cache headers.

           AxNoCache On

       AxDebugLevel

       If present this makes AxKit send output to Apache's error log. The
       valid range is 0-10, with 10 producing more output. We recommend not to
       use this option on a live server.

           AxDebugLevel 5

       AxTraceIntermediate

       With this option you advise AxKit to store the result of each transfor-
       mation request in a special directory for debugging. This directory
       must exist and must be writeable by the httpd. The files are stored
       with their full uri, replacing slashes with '|', and appending a number
       indicating the transformation step.  '.0' is the xml after the first
       transformation.

           AxTraceIntermediate /tmp/axkit-trace

       AxDebugTidy

       With this option you advise AxKit to tidy up debug dumps like XSP
       scripts or the XML files generated by AxTraceIntermediate. Be aware
       that this can slow down requests considerably, but often it is much
       easier to spot errors with this enabled.

           AxDebugTidy On

       AxStackTrace

       This FLAG option says whether to maintain a stack trace with every
       exception.  This is slightly inefficient, as it has to call caller()
       several times for every exception thrown, but it can give better debug-
       ging information.

           AxStackTrace On

       AxLogDeclines

       This option is a FLAG, it is either On, or Off (default is Off). When
       AxKit declines to process a URI, it gives a reason. Normally this rea-
       son is not sent to the log, however if AxLogDeclines is set, the reason
       is logged. This is useful in figuring out why a particular file is not
       being processed by AxKit.

       If this option is set, the reason is logged regardless of the AxDebu-
       gLevel, however if AxDebugLevel is 4 or higher, the file and line num-
       ber of where the DECLINE occured is logged, but not necessarily the
       reason.

           AxLogDeclines On

       AxAddPlugin

       Setting this to a module, will load that module and execute the handler
       method of the module before any AxKit processing is done.

       This allows you to setup things like sessions, do authentication, or
       other actions that require no XML output, before the actual XML pro-
       cessing stage of AxKit.

           AxAddPlugin MyAuthHandler

       There is also a companion option, AxResetPlugins, because plugin lists
       persist and get merged into directories, so if you want to start com-
       pletely fresh, use the following:

           AxResetPlugins
           AxAddPlugin MyFreshPlugin

       Note: as with other options that take a module, prefixing with a "+"
       sign will pre-load the module at compile time.

       AxGzipOutput

       This allows you to use the Compress::Zlib module to gzip output to
       browsers that support gzip compressed pages. It uses the Accept-Encod-
       ing HTTP header and some information about User agents who can support
       this option but don't correctly send the Accept-Encoding header. This
       option allows either On or Off values (default being Off). This is very
       much worth using on sites with mostly static pages because it reduces
       outgoing bandwidth significantly.

           AxGzipOutput On

       AxTranslateOutput

       This option enables output character set translation. The default
       method is to detect the appropriate character set from the user agent's
       Accept-Charset HTTP header, but you can also hard-code an output char-
       acter set using AxOutputCharset (see below).

           AxTranslateOutput On

       AxOutputCharset

       Fix the output character set, rather than using either UTF-8 or the
       user's preference from the Accept-Charset HTTP header. If this option
       is present, all output will occur in the chosen character set. The con-
       version uses the iconv library, which is part of GNU glibc and/or most
       modern Unixes. It is recommended to not use this option if you can
       avoid it. This option is only enable if you also enable AxTranslateOut-
       put.

           AxOutputCharset iso-8859-1

       AxExternalEncoding

       This directive specifies the character encoding used outside of AxKit.
       Internally, AxKit strictly uses UTF-8 (remember that when you write
       Taglibs!), but file names on the file system and URIs requested by
       browsers may use a different encoding, e.g. ISO-8859-15 for most of
       Europe.

       This is a server-global directive, so only use it within <VirtualHost
       ...> containers or on the root level. As a side effect, this option
       allows you to work with non-ASCII chars in URLs even outside of AxKit.
       Some Browsers may send URLs in their local charset although the link
       was encoded in UTF-8, and others always send UTF-8 encoded URLs,
       regardless of link encoding. If you set this option, AxKit will inter-
       cept each request and check if the URL came encoded in UTF-8. If so,
       AxKit transforms it to the character encoding specified here before
       Apache gets to resolve the request, so Apache will find the file, even
       if it is a non-AxKit file.

       Note: This does not effect the _contents_ of documents, they have their
       own encoding specifier (in the <?xml ...?> line). For now, it only
       affects file names and URL processing.

           AxExternalEncoding ISO-8859-1

       AxAddOutputTransformer

       Output transformers are applied just before output is sent to the
       browser.  This directive adds a transformer to the list of transformers
       to be applied to the output.

           AxAddOutputTransformer  MyModule::Transformer

       The transformer is a subroutine that accepts a line to process and
       returns the transformed line.

           package MyModule;
           sub Transformer {
             my $line = shift;
             ...
             return $line;
           }

       An output transformer could be used to add dynamic output to a cached
       page (such as the date and time, or a customer name).

       AxResetOutputTransformers

       Reset the list of output transformers from the current directory level
       down.

          # This directive takes no arguments
          AxResetOutputTransformers

       AxErrorStylesheet

       If an error occurs during processing that throws an exception, the
       exception handler will try and find an ErrorStylesheet to use to
       process XML of the following format:

           <error>
               <file>/usr/htdocs/xml/foo.xml</file>
               <msg>Something bad happened</msg>
               <stack_trace>
                   <bt level="0">
                       <file>/usr/lib/perl/site/AxKit.pm</file>
                       <line>342</line>
                   </bt>
               </stack_trace>
           </error>

       There may potentially be multiple bt tags. If an exception occurs when
       the error stylesheet is transforming the above XML, then a SERVER ERROR
       will occur and an error written in the Apache error log.

           AxErrorStylesheet text/xsl /stylesheets/error.xsl

       AxAddXSPTaglib

       XSP supports two types of tag libraries. The simplest type to under-
       stand is merely an XSLT or XPathScript (or other transformation lan-
       guage) stylesheet that transforms custom tags into the "raw" XSP tag
       form.  However there is another kind, that is faster, and these taglibs
       transform the custom tags into pure code which then gets compiled.
       These taglibs must be loaded into the server using the AxAddXSPTaglib
       configuration directive.

           # load the ESQL taglib and Util taglib
           AxAddXSPTaglib AxKit::XSP::ESQL
           AxAddXSPTaglib AxKit::XSP::Util

       If you prefix the module name with a + sign, it will be pre-loaded on
       server startup (assuming that the config directive is in a httpd.conf,
       rather than a .htaccess file).

       AxIgnoreStylePI

       Turn off parsing and overriding stylesheet selection for XML files con-
       taining an "xml-stylesheet" processing instruction at the start of the
       file. This is a FLAG option - On or Off. The default value is "Off".

         AxIgnoreStylePI On

       AxHandleDirs

       Enable this option to allow AxKit to process directories. Creates an
       XML document with the contents of the requested directory. Look at sam-
       ple output to discover that the format is straightforward and easy to
       understand.

         AxHandleDirs On

       A DTD for the output of AxHandleDirs is at <http://axkit.org/dtd/axhan-
       dledirs.dtd>

       AxStyle

       A default stylesheet title to use. This is useful when a single XML
       resource maps to multiple choice stylesheets. One possible way to use
       this is to symlink the same file in different directories with .htac-
       cess files specifying different AxStyle directives.

           AxStyle "My custom style"

       AxMedia

       Very similar to the previous directive, this sets the media type. It is
       most useful in a .htaccess file where you might have an entire direc-
       tory for the media "handheld".

           AxMedia tv

       AxAddStyleMap

       This is one of the more important directives. It is responsible for
       mapping module stylesheet MIME types to stylesheet processor modules
       (the reason we do this is to make it easy to switch out different mod-
       ules for the same functionality, for example different XSLT proces-
       sors).

           AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
           AxAddStyleMap application/x-xpathscript \
               Apache::AxKit::Language::XPathScript
           AxAddStyleMap application/x-xsp \
               Apache::AxKit::Language::XSP

       If you prefix the module name with a + sign, it will be pre-loaded on
       server startup (assuming that the config directive is in a httpd.conf,
       rather than a .htaccess file).

       AxResetStyleMap

       Since the style map will continue deep into your directory tree, it may
       occasionally be useful to reset the style map, for example if you want
       a directory processed by a different XSLT engine.

           # option takes no arguments.
           AxResetStyleMap

ASSOCIATING STYLESHEETS WITH XML FILES

       There are several directives specifically designed to allow you to
       build a flexible sitemap that specifies how XML files get processed on
       your system.

       Note: <?xml-stylesheet?> directives in your XML files override these
       directives unless you enable the AxIgnoreStylePI option listed above.

       AxAddProcessor

       This directive maps all XML files to a particular stylesheet to be pro-
       cessed with. You can do this in a <Files> directive if you need to do
       it by file extension, or on a file-by-file basis:

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

       Multiple directives for the same set of files make for a chained set of
       stylesheet processing instructions, where the output of one processing
       stage goes into the input of the next. This is especially useful for
       XSP processing, where the output of the XSP processor will likely not
       be HTML (or WAP or whatever your chosen output format is):

           <Files *.xsp>
           # use "." to indicate that XSP gets processed by itself.
           AxAddProcessor application/x-xsp .
           AxAddProcessor text/xsl /stylesheets/to_html.xsl
           </Files>

       AxAddDocTypeProcessor

       This allows you to map all XML files conforming to a particular XML
       public identifier in the document's DOCTYPE declaration, to the speci-
       fied stylesheet(s):

           AxAddDocTypeProcessor text/xsl /stylesheets/docbook.xsl \
                   "-//OASIS//DTD DocBook XML V4.1.2//EN"

       AxAddDTDProcessor

       This allows you to map all XML files that specify the given DTD file or
       URI in the SYSTEM identifier to be mapped to the specified
       stylesheet(s):

           AxAddDTDProcessor text/xsl /stylesheets/docbook.xsl \
                   /dtds/docbook.dtd

       AxAddRootProcessor

       This allows you to map all XML files that have the given root element
       to be mapped to the specified stylesheet(s):

           AxAddRootProcessor text/xsl /stylesheets/book.xsl book

       Namespaces are fully supported via the following syntax:

           AxAddRootProcessor text/xsl /stylesheets/homepage.xsl \
               {http://myserver.com/NS/homepage}homepage

       This syntax was taken from James Clark's Introduction to Namespaces
       article.

       AxAddURIProcessor

       This allows you to use a Perl regular expression to match against the
       URI of the file in question:

           AxAddURIProcessor text/xsl /stylesheets/book.xsl \
                   "book.*\.xml$"

       AxResetProcessors

       This allows you to reset the processor mappings at from the current
       directory level down.

           AxResetProcessors

       From this directory down you can completely redefine how certain types
       of files get processed by AxKit.

       <AxMediaType>

       This is a configuration directive block. It allows you to have finer
       grained control over the mappings, by specifying that the mappings
       (which have to be specified using the Add*Processor directives above)
       contained within the block are only relevant when the requested media
       type is as specified in the block parameters:

           <AxMediaType screen>
           AxAddProcessor text/xsl /stylesheets/webpage_screen.xsl
           </AxMediaType>

           <AxMediaType handheld>
           AxAddProcessor text/xsl /stylesheets/webpage_wap.xsl
           </AxMediaType>

           <AxMediaType tv>
           AxAddProcessor text/xsl /stylesheets/webpage_tv.xsl
           </AxMediaType>

       <AxStyleName>

       This configuration directive block is very similar to the above, only
       it specifies alternate stylesheets by name, which can be then requested
       via a StyleChooser:

           <AxMediaType screen>
               <AxStyleName #default>
                   AxAddProcessor text/xsl /styles/webpage_screen.xsl
               </AxStyleName>
               <AxStyleName printable>
                   AxAddProcessor text/xsl /styles/webpage_printable.xsl
               </AxStyleName>
           </AxMediaType>

       This and the above directive block can be nested, and can also be con-
       tained within <Files> directives to give you even more control over how
       your XML is transformed.

CUSTOMISING AXKIT

       There are some configuration directives that are specifically reserved
       for customising how AxKit works. These directives allow you to specify
       a new class to replace the one being used for certain operations.

       These directives all take as a single argument, the name of a module to
       load in place of the default. They are:

           AxConfigReader
           AxContentProvider
           AxStyleProvider
           AxCacheModule

       The ConfigReader module returns information about various configuration
       options. Currently it takes most of its information from the above men-
       tioned configuration directives, or from PerlSetVar.

       The Provider modules are the means by which AxKit gets its resources
       from.  ContentProviders deliver up the document to be processed, while
       StyleProviders are used to get the data for any stylesheets that will
       be applied.  The default Provider for each simply picks up files from
       the filesystem, but alternate providers could pull the information from
       a DBMS, or perhaps create some XML structure for directories. There
       currently exists one alternate Provider module, which allows AxKit to
       work as a recipient for Apache::Filter output. This module is
       Apache::AxKit::Provider::Filter.

       The Cache module is responsible for storing cache data for later
       retrieval.

       Implementing these is non trivial, and it is highly recommended to join
       the AxKit-devel mailing list before venturing to do so, and to also
       consult the source for the current default modules. Details of joining
       the mailing list are at http://axkit.org/mailinglist.xml

KNOWN BUGS

       There are currently some incompatibilities between the versions of
       expat loaded by Apache when compiled with RULE_EXPAT=yes (which is a
       default, unfortunately), and XML::Parser's copy of expat. This can
       cause sporadic segmentation faults in Apache's httpd processes. The
       solution is to recompile Apache with RULE_EXPAT=no (later Apache's have
       implemented this as --disable-rule=expat). If you have a recent
       mod_perl and use mod_perl's Makefile.PL DO_HTTPD=1 to compile Apache
       for you, this option will be enabled automatically for you.

/usr/man/cat.3/AxKit.3.Z(/usr/man/cat.3/AxKit.3.Z)

NAME

DESCRIPTION

SYNOPSIS

CONFIGURATION DIRECTIVES

ASSOCIATING STYLESHEETS WITH XML FILES

CUSTOMISING AXKIT

KNOWN BUGS

MORE DOCUMENTATION

SEE ALSO