<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>mod-xslt2 Setup and Usage</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="mod-xslt2 Users and Administrators Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Installation"
HREF="x49.html"><LINK
REL="NEXT"
TITLE="Writing XML for mod-xslt2"
HREF="x413.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>mod-xslt2 Users and Administrators Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x49.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x413.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN181"
>5. mod-xslt2 Setup and Usage</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN183"
>5.1. Apache 1.3.x</A
></H2
><P
>mod-xslt2 can be configured in several ways to be used on apache 1.3.
To choose which one suits best your needs, you need a good knowledge
of how apache works. The following sections will try to give you the basic
knowledge needed to configure mod-xslt2.</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN186"
>5.1.1. Request life</A
></H3
><P
>When requesting a document to an Apache 1.3 server through your browser, apache
<P
></P
><OL
TYPE="1"
><LI
><P
>takes the requested URL and remaps it to a ``file location'', to a path
on the local file system
(as an example, ``http://www.masobit.net/foo/bar.xml'' may become
``/opt/array-00/customers/masobit.net/http/bar.xml'')</P
></LI
><LI
><P
>tries to understand the format the document is written into (it looks for the mime type
of the document)</P
></LI
><LI
><P
>looks for someone or something able to ``read'' the provided document type (an ``handler'')</P
></LI
><LI
><P
>the handler is passed the job to send the document ``over the
wire'' back to the browser. </P
></LI
></OL
>
As an example, when you request a .php file with something like ``www.masobit.net/info.php'',
on our server the first step remaps ``www.masobit.net/info.php'' in something
like ``/opt/array-00/customers/masobit.net/http/info.php''. Apache then looks in the
mime.magic or mime.types (or the AddType directives) for the mime type of the file.
Provided the content of those files and those directives are correct, apache will decide
the requested file is of type ``application/x-httpd-php''.</P
><P
>Apache will then look for a handler able to serve this kind of document, and it will see
that ``application/x-httpd-php'' is handled by the ``libphp4.so'' module.</P
><P
>
Apache will then call a function in this module and let the module directly write the
answer back to the browser.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN200"
>5.1.2. Using the ``AddHandler'' directive</A
></H3
><P
>One good way to let mod-xslt2 handle a request is to use the ``AddHandler'' or
``SetHandler'' directive. </P
><P
>Using those directives you can tell apache you want a particular kind of file
being handled <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>directly</I
></SPAN
> by mod-xslt2. For example,
you could use something like:
<PRE
CLASS="SCREEN"
> AddHandler mod-xslt .xml</PRE
>
To tell apache the handler for all xml files needs to be ``mod-xslt2''. AddHandler can
be even activated on a per directory/per location or per file basis. For example,
you could activate xml parsing in a given directory by using something like:
<PRE
CLASS="SCREEN"
> <Directory "/opt/foo/">>
AddHandler mod-xslt .xml
</Directory></PRE
>
If you want to parse all the files in a given directory as xml files regardless of their extension
you could use something like:
<PRE
CLASS="SCREEN"
> <Directory "/opt/foo/">>
SetHandler mod-xslt
</Directory></PRE
>
AddHandler and SetHandler are the ``fastest'' way to use mod-xslt2. The drawback is
that <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>this method won't work if you set mod-xslt2 up to handle .php files, since they won't be
parsed</I
></SPAN
> by the php module. Infact, as explained previously, apache will call mod-xslt2 instead
of ``libphp4.so'' to send the document back to the browser.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN209"
>5.1.3. Using the XSLT directives</A
></H3
><P
>In case you need to apply stylesheets to dynamically generated documents, you thus need
to use the mechanism provided by mod-xslt2.</P
><P
>This mechanism has nothing to do with the mechanism described in the previous sections
and does not conflict with it. Keep in mind, however, that the following directives need
to be used <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>only if you want to parse dynamically generated files</I
></SPAN
>, like php, perl or
cgi.</P
><P
>Before anything else, you need to enable the XSLT Engine for a given directory, using
the ``XSLTEngine <on|off>'' directive. Once enabled, mod-xslt will be called
for <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>every</I
></SPAN
> file in the given directory that apache will
be required to serve.</P
><P
>However, while coding the module, we had the choice to:
<P
></P
><UL
><LI
><P
>check the mime type of every apache reply, and parse it if it was of type
text/xml.</P
></LI
><LI
><P
>check the mime type only of <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>some</I
></SPAN
> requests, and parse them only if they
were of type text/xml.</P
></LI
></UL
>
Since checking the type of a reply is quite expensive in terms of system resources,
we decided to go with the second choice. You thus need to tell mod-xslt2 which requests
you want it to check for xml output to parse, by using the ``XSLTAddFilter'' parameter.
As an example, if you want to apply an xslt stylesheet to the output of the
php scripts in one of your directories, you need to use something like:
<PRE
CLASS="SCREEN"
><Directory
"/opt/array-00/customers/masobit.net/http/php-xml/">
XSLTEngine on
XSLTAddFilter application/x-httpd-php
</Directory></PRE
>
However, keep in mind that the output of a given script will be parsed
if and only if it outputs xml data and sets the mime type to ``text/xml'',
so, in php, you need to use something like ``header("Content-Type: text/xml")''
before anything else in your scripts.</P
><P
>Remember: you need to use ``XSLTEngine on'' only if you need to parse
dynamic pages. </P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN225"
>5.1.4. Mixing the two</A
></H3
><P
>As a rule of thumb, you can use ``AddHandler'' for any ``static document'' and
``XSLTEngine'' with ``XSLTAddFilter'' with any ``dynamic document''.</P
><P
>A complete example could be the following:
<PRE
CLASS="SCREEN"
>...
LoadModule mxslt_module /usr/lib/apache/mod_xslt.so
AddModule modxslt.c
...
XSLTTmpDir /tmp
# Always parse .xml files using the
# specified stylesheets
AddHandler mod-xslt .xml
# In this directory, some .php scripts
# output xml to be parsed - those
# scripts need to set the ``Content-Type''
# header to text/xml if they want
# a stylesheet to be applied. Otherwise,
# they will be ignored
# header("Content-Type: text/xml")
<Directory /var/www/xml>
XSLTEngine on
XSLTAddFilter application/x-httpd-php
</Directory></PRE
>
In the example above, only php scripts in ``/var/www/xml'' will be parsed
provided they output a Content-Type header set to ``text/xml''. If you
want to parse them regardless of the Content-Type, thus regardless of
the type of data they are outputting, you can use the apache directive
``XSLTAddForce'' with the same syntax of XSLTAddFilter.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN230"
>5.1.5. Loading the module</A
></H3
><P
>Regardless of which method you may decide to use to parse your xml
data, keep in mind you always need to tell apache to load the module.
To do so, add a line like the following to your httpd.conf:
<PRE
CLASS="SCREEN"
>LoadModule mxslt_module /usr/lib/apache/mod_xslt.so
AddModule modxslt.c</PRE
>
Beware that the second parameter must be the full path were mod_xslt
got installed. Since the path is detected by querying ``apxs'', it will
probably be the same as any other apache module. If you don't know where
apache modules are kept on your system, use something like ``apxs -q LIBEXECDIR''
or look to other LoadModule directives in your configuration files.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN234"
>5.1.6. mod-xslt Configuration parameters</A
></H3
><P
> <P
></P
><UL
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTEngine <on|off></I
></SPAN
> per directory, per file, per virtual host or in global
configuration file, allows you to enable or disable XSLT extra features.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTTmpDir <directory></I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, allows you to specify which directory mod-xslt2 will use to
create temporary files. By default, ``/tmp/mod-xslt2'' is used. Keep in mind that
``/tmp/mod-xslt2'' must exist in your system. Path must be absolute: ``/tmp'' good,
``/var/tmp'' good, ``tmp'' <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>bad</I
></SPAN
>, ``./tmp'' <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>bad</I
></SPAN
>.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTAddFilter <MimeType></I
></SPAN
> per directory, per file, per virtual host, or
in global configuration file, tells mod-xslt2 to parse files of the given
mime type as if they were xml files. Keep in mind that the file is parsed only
if the content type is set to ``text/xml''.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDelFilter <MimeType></I
></SPAN
> per directory, per file, per virtual host, or
in global configuration file, tells mod-xslt2 not to parse files of the given mime
type anymore. This is needed since mod-xslt2 per directory configurations are hinerited
from parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTAddForce <MimeType></I
></SPAN
> per directory, per file, per virtual host, or
in global configuration file, tells mod-xslt2 to parse files of the given
mime type as if they were xml files, independently from the resulting content type.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDelForce <MimeType></I
></SPAN
> per directory, per file, per virtual host, or
in global configuration file, tells mod-xslt2 not to parse files of the given mime
type anymore. This is needed since mod-xslt2 per directory configurations are hinerited
from parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTSetStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 to use the given stylesheet
for all files of the given MimeType, independently from any ``<xml-stylesheet...'' or processing
instruction available into the document.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTUnSetStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 to forget about a previous
``XSLTSetStylesheet''. This is needed since mod-xslt2 per directory configurations are hinerited from
parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDefaultStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 that, in case an xml
file does not contain any ``<xml-stylesheet...'' or ``<xslt-stylesheet...'', for
the given MimeType the specified xslt stylesheet should be used.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTNoDefaultStylesheet <MimeType></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 that to forget about
a previous ``XSLTDefaultStylesheet''. This is needed since mod-xslt2 per directory configurations
are hinerited from parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTUnlink <on|off></I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 that temporary files are not to be deleted.
This option was provided to simplify debugging of newly created documents: combined
with a per directory ``XSLTTmpDir'' and using dynamic documents provided by php or
perl, the temporary file will keep the xml document generated by your scripts, simplifying
debugging. You can find the temporary file that generated an error by reading the error
log.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTParam "variable" "value"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to pass the given ``variable'' to the stylesheet
with the indicated ``value''.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTAddRule "stylesheet" "condition"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to use the specified stylesheet if all conditions specified in ``condition''
are met. Any modxslt-stylesheet or xml-stylesheet contained in the document is then ignored, unless the selected stylesheet
is not loadable or does not work, in which case the rule is ignored.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDelRule "stylesheet"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to forget about the rule regarding the specified stylesheet </P
></LI
></UL
> </P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN282"
>5.1.7. Parameters usage examples</A
></H3
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN284"
>5.1.7.1. XSLTSetStylesheet</A
></H4
><P
>XSLTSetStylesheet is most useful when you have .xml documents that do not specify any
xslt stylesheet to be used for the parsing.</P
><P
>You can put all those documents in a given directory on your web server, and then use
something like:
<PRE
CLASS="SCREEN"
><Directory /documents/without/stylesheet>
XSLTSetStylesheet default_stylesheet.xsl
</Directory></PRE
></P
><P
>All the files in /documents/without/stylesheet would then be parsed
using default_stylesheet.xsl, independently from any <?xml-stylesheet
or <?modxslt-stylesheet specifyed in the document.</P
><P
>XSLTSetStylesheet parameters are hierarchically propagated in subdirectories. This
means that if you want to disable one of the stylesheet you previously set, you
need to use XSLTUnSetStylesheet.</P
></DIV
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN291"
>5.1.7.2. XSLTAddFilter and XSLTAddForce</A
></H4
><P
>XSLTAddFilter and XSLTAddForce can be used to tell mod-xslt which files to
parse.</P
><P
>They both take as a first argument a MIME type. This MIME type is used by
mod-xslt to identify the scripts/files that may output xml to be parsed.</P
><P
>So, in order for mod-xslt to parse dynamic documents, you need to tell him
which ``kind of documents'' may output xml.</P
><P
>Weel, those ``dynamic documents'', however, may decide not to output xml
and output something else.</P
><P
>XSLTAddFilter thus tells mod-xslt to watch a given mime type, verify if
the output is xml, and only if it is, parse it into something else.</P
><P
>XSLTAddForce, instead, watches a given mime-type, and it tells mod-xslt
to parse the output in any case, even if it doesn't look like xml. This
instruction may be used if you have cgi or dynamic scripts which output
the wrong mime type.</P
></DIV
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN299"
>5.1.7.3. XSLTAddRule</A
></H4
><P
>XSLTAddRule has been added since mod-xslt 1.3.6, snapshot >= 2004100100.
This parameter allows you to specify a stylesheet to be used for all
documents selected by the apache directive being used only if the
specified condition, written as a mod-xslt expression (see the
dedicated section), is met.</P
><P
>Rules are checked by mod-xslt in the same order as specified, and
the first one matching specifies the stylesheet to be used to
parse the document, independently from any <xml-stylesheet or
<modxslt-stylesheet being specified in the document.</P
><P
>Here are some examples:</P
><P
><PRE
CLASS="SCREEN"
><Directory /xml>
XSLTAddRule "local://stylesheet_mozilla.php?LANG=$GET[LANG]" "$HEADER[User-Agent] =~ '/mozilla/'"
XSLTAddRule "local://stylesheet_printer.php?LANG=$GET[LANG]" "$GET[format] =~ '/printer/'"
</Directory></PRE
>
Note that the stylesshet can be any of the supported stylesheet kinds, and that mod-xslt performs
variable substitution in the stylesheet URL.</P
><P
>Also note that in case the stylesheet contains errors or is not loadable for any reason, the rule
is ignored and parsing goes on using the stylesheets specified by the document.</P
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN307"
>5.1.8. Logging</A
></H3
><P
>In order to process requests, mod-xslt2 needs to create temporary files. Temporary
files are used to process dynamic requests, and contain the XML that got to mod-xslt2
to be parsed. It is often useful to know which temporary file was associated with which
request, especially if the unlinking of temporary files is disabled.</P
><P
>mod-xslt2 saves the name of the temporary file being used in a ``request note''
that can be retrieved by using something like ``%{mod-xslt-tmp}n" in the ``LogFormat'' directive,
with something like:
<PRE
CLASS="SCREEN"
>LogFormat "%v %h %l %u %t \"%r\" %>s %b
(%{mod-xslt-tmp}n)" mxslt_format
CustomLog logs/mod-xslt2.log mxslt_format</PRE
> </P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN312"
>5.1.9. Increasing performance</A
></H3
><P
>The only way in apache 1.3.x to intercept the output of other modules is
to provide a suitable file descriptor where to store data.</P
><P
>Since mod-xslt2 is part of apache itself, a pipe is impossible to use,
unless we fork apache one more time, slowing things down.</P
><P
>The simplest approach has thus been used: creating a temporary file,
let other modules write the replies in there, and then parse the temporary
file. However, by using temporary files, we hit I/O performance issues.</P
><P
>One of the greatest performance improvements would thus be to mount
a ramdisk (either a ``shm'' or ``rd'' in linux), over the directory used
by mod-xslt2 for temporary files.</P
><P
>Other methods are under investigation and may get supported in future versions
of mod-xslt2:
<P
></P
><UL
><LI
><P
>Having an external daemon parse data, transmitted from apache through
a unix socket. This will be done after implementing the proxy module,
which is almost the same. This would also be useful to simplify cache
implementation.</P
></LI
><LI
><P
>Provide, as file descriptor, the file descriptor of /dev/null, and use
the ``callback'' provided by apache to store data in memory. In this case,
however, we would hit memory problems for big files. However, other
solutions may be used (mmapping a file? using libxml push method?
does it parse data on the fly or simply keeps the buffers for
later parsing?)</P
></LI
></UL
>
Another performance issue is due to:
<P
></P
><UL
><LI
><P
>external http or ftp connections to fetch .xsl or .dtd files</P
></LI
><LI
><P
>dns lookups to understand if a remote host is in practice
a remote host or a local one</P
></LI
></UL
>
The latest of the two problems can be solved either by using
a faster name resolution mechanism (take a look to nsswitch.conf
or to the hosts file) or by paying some attention while writing
.xml+.xslt file and by explicitly telling mod-xslt2 when to use
local connections (will be explained later on).</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN329"
>5.1.10. Subrequest Issues</A
></H3
><P
>To avoid security and some concurrency issues (see the section about security
concerns), mod-xslt2 for apache 1 tryes
to avoid remote connections as much as possible, specially if those connections
will loop back to the localhost.</P
><P
>However, apache accepts any connection it receives on any of the addresses it
is listening on, and is thus hard to understand which connections will loop
back to the local host.</P
><P
>By default, when mod-xslt2 starts, it tries to understand on which addresses
apache is listening on. However, when you write your apache configuration file,
you have two choices:
<P
></P
><UL
><LI
><P
>Explicitly listing all the ip addresses to listen on (using the
``Listen'' directive with something like ``Listen 127.0.0.1:80''
or by using ``BindAddress'' - which is deprecated by the apache
group)</P
></LI
><LI
><P
>Just specify one or more ports, and let apache listen on all
interfaces on all ip addresses (simply using the ``Port'' directive
without any ``Listen'', or by using one or more ``Listen'' with
something like ``Listen 80 8080'')</P
></LI
></UL
>
In the first case, mod-xslt2 will use the ip addresses provided
with the ``Listen'' directive to detect remote connections.</P
><P
>However, if you use the ``Listen'' directive by just specifing the port(s)
to listen on or you just use the ``Port'' directive, mod-xslt2 will have
to try to understand which are all the ip addresses available on the
operating system, which is very system dependent and quite unportable.</P
><P
>At time of writing, mod-xslt2 configure script will try to detect
if the needed functions to get all the ip addresses of the operative
system are available, in which case the autodetection code is
compiled in.</P
><P
>However, if those functions are not available, mod-xslt2 will
complain any time you use the ``Port'' directive or
the ``Listen'' directive without explicitly specifing the ip
addresses to listen on, by printing in the logs something like:
<PRE
CLASS="SCREEN"
>INADDR_ANY is being used without ioctl support -
read mod-xslt2 README!</PRE
>
In this case, just change any ``Listen'' directive you have like
this:
<PRE
CLASS="SCREEN"
>Listen 80 8080</PRE
>
in something like
<PRE
CLASS="SCREEN"
>Listen 127.0.0.1:80 192.168.0.1:80
127.0.0.1:8080 192.168.0.1:8080</PRE
>
where ``127.0.0.1'' and ``192.168.0.1'' are the only ip addresses
apache will listen on. If you don't have any listen directive, just
add them. Watch out that, if you have many ip addresses to listen
on, apache performance will decrease (by listing them all instead). In this
case, the best bet would be to improve mod-xslt2 detection code
and write some that will work on your platform. Please mail me
if you do so, or mail me if you need help in doing so. Unfortunately,
at time of writing, I have access only to ``Debian GNU/Linux'' machines,
and cannot tell if the detection code will work on any other
platform.</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN345"
>5.2. Apache 2.0.x</A
></H2
><P
> mod-xslt support for apache2 has been slowly growing. While it has worked
for the first few releases, it was dropped after a few versions in order to
allow faster development of the library API. Development of
mod-xslt apache2 support started again with version 1.3.4 of the module,
where its support has finally become usable again. Beware, however, that at time
of writing apache2 support is not rock solid and shouldn't be used in production
environments. At this stage of development, user feedbacks are foundamental:
if you have problems or it doesn't work as expected, please take your time to send a nice
email to one of the mod-xslt mailing lists. At this regard, I need to thank
all the people who reported problems using mod-xslt.</P
><P
> At time of writing, there is only one known issue about mod-xslt and apache 2.0.x:
as a filter, it is not very easy for mod-xslt to return status pages different than
those set by the handler (like 404 or 500 pages), and while it works with most document
types, it may not work with _all_ document types (depending on the handler providing the given type).</P
><P
> For example, if a php4 script (where php4 is handled thanks to the php4 apache2handler
sapi) outputs invalid xml code, mod-xslt tries to tell apache2 to output a 500 error
page. However, the mod-xslt request is handled by the php4 handler and the connection is
instead dropped. Other handlers may have similar problems. If you encounter some, please
report them to one of the mailing lists. At time of writing, I have no idea on how to correct
this problem, beshide handling error documents by myself (in mod-xslt) or patching php4
apache2handler. If anyone has suggestions, please contact me.</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN350"
>5.2.1. Configuring Apache 2.0 for mod-xslt</A
></H3
><P
> To use mod-xslt with apache 2.0.x, you just need to
tell apache you want to use mod-xslt, by inserting
a line like the following in your httpd.conf (or apache.conf):
<PRE
CLASS="SCREEN"
> LoadModule mxslt_module /usr/lib/apache2/mod_xslt.so</PRE
>
Where <TT
CLASS="FILENAME"
>/usr/lib/apache2/</TT
> is the path where all your
modules are kept. Note that on <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>most</I
></SPAN
> systems,
apache2 modules are kept in <TT
CLASS="FILENAME"
>/usr/local/libexec</TT
>, so
the correct LoadModule directive should be:
<PRE
CLASS="SCREEN"
> LoadModule mxslt_module /usr/local/libexec/mod_xslt.so</PRE
>
Note however that this path can be changed during apache2 configuration,
so please look to where other modules are kept, or run the command ``apxs2 -q LIBEXECDIR''
or ``apxs -q LIBEXECDIR''.</P
><P
> If you don't know this path, just look for other ``LoadModule'' directives
in your configuration file or run the command ``apxs2 -q LIBEXECDIR'', which
will show you the correct path.</P
><P
> Once you tell apache to load mod-xslt, you need to tell him for which files
you want mod-xslt to be used. To do so, you can use one of the following directives:
<P
></P
><UL
><LI
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>AddOutputFilter mod-xslt <extension>...</I
></SPAN
>
tells apache we want mod-xslt to parse all files with extension ``extension''.</P
></LI
><LI
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>AddOutputFilterByType mod-xslt <mime-type>...</I
></SPAN
>
tells apache we want mod-xslt to parse all files with the specified mime-type.</P
></LI
><LI
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>SetOutputFilter mod-xslt</I
></SPAN
>
tells apache that we want all files in a given directory or location or virtual
host to be parsed by mod-xslt.</P
></LI
></UL
>
Watch out! Just use one of those directives. If you use more than one,
your documents will be parsed more than once, and unless your first pass outputs
.xml to be parsed again, an error will be signaled by mod-xslt. </P
><P
> For example, you may enable mod-xslt in a given directory with something
like:
<PRE
CLASS="SCREEN"
><Directory /this/is/a/directory>
AddOutputFilterByType mod-xslt text/xml
...
</Directory>
</PRE
>
If you know before hand that all files in a given directory should be parsed
using mod-xslt, you may also use something like:
<PRE
CLASS="SCREEN"
><Directory /this/is/another/directory>
...
SetOutputFilter mod-xslt
</Directory>
</PRE
></P
><P
> To have further details about the discussed parameters, please take a look
to the apache manual, http://httpd.apache.org/.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN374"
>5.2.2. mod-xslt Configuration parameters</A
></H3
><P
> <P
></P
><UL
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTSetStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 to use the given stylesheet
for all files of the given MimeType, independently from any ``<xml-stylesheet...'' or processing
instruction available into the document.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTUnSetStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 to forget about a previous
``XSLTSetStylesheet''. This is needed since mod-xslt2 per directory configurations are hinerited from
parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDefaultStylesheet <MimeType> <Stylesheet></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 that, in case an xml
file does not contain any ``<xml-stylesheet...'' or ``<xslt-stylesheet...'', for
the given MimeType the specified xslt stylesheet should be used.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTNoDefaultStylesheet <MimeType></I
></SPAN
> per directory, per file,
per virtual host or in global configuration file, tells mod-xslt2 that to forget about
a previous ``XSLTDefaultStylesheet''. This is needed since mod-xslt2 per directory configurations
are hinerited from parent directories.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTParam "variable" "value"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to pass the given ``variable'' to the stylesheet
with the indicated ``value''.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTAddRule "stylesheet" "condition"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to use the specified stylesheet if all conditions specified in ``condition''
are met. Any modxslt-stylesheet or xml-stylesheet contained in the document is then ignored, unless the selected stylesheet
is not loadable or does not work, in which case the rule is ignored.</P
></LI
><LI
><P
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>XSLTDelRule "stylesheet"</I
></SPAN
> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to forget about the rule regarding the specified stylesheet </P
></LI
></UL
> </P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN399"
>5.2.3. Apache 2.0.x, mod-xslt and PHP4</A
></H3
><P
> In order to use php4 with apache2, you can compile it using
two different SAPI:
<P
></P
><UL
><LI
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>apache2filter</I
></SPAN
> - where php4 is
used as an Apache 2.0.x FILTER
</P
></LI
><LI
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>apache2handler</I
></SPAN
> - where php4 is
used as an Apache 2.0.x HANDLER
</P
></LI
></UL
>
</P
><P
> To know more about the differences between HANDLERs and FILTERs in
apache 2.0.x, please refer to apache 2.0.x documentation.
</P
><P
> To know more about how to compile php4 using the two SAPI or about
the differences between the two, please refer to php4 documentation.
</P
><P
> At time of writing, however, if you compile php4 to run under apache2
it will be compiled using the HANDLER sapi.
</P
><P
> mod-xslt is now being tested using only this SAPI, and only very
old versions of mod-xslt have been tested with the FILTER sapi.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x49.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x413.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Installation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Writing XML for mod-xslt2</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
22a02ab88ee7099ea6d7fdf524536d58
>
files
>
14
