Users and Administrators ManualDate: 2013/04/25 23:57:16
mod-xslt2 is a web server module able to transform xml documents
in any format using xslt stylesheets. It implements server side
transformation of xslt stylesheet.
Apache 2.x support is now considered stable (2.0, 2.2, ...), thanks to all
the people who provided feedbacks on mod-xslt mailing lists.
At time of writing, there is only one known issue about mod-xslt and apache 2.x.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).
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.
To use mod-xslt with apache 2.x.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):
LoadModule mxslt_module /usr/lib/apache2/modules/mod_xslt.so
Where /usr/lib/apache2/ is the path where all your
modules are kept. Note that on most
apache2 modules are kept in /usr/local/libexec, so
the correct LoadModule directive should be:
LoadModule mxslt_module /usr/local/libexec/mod_xslt.so
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''.
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.
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:
AddOutputFilter mod-xslt <extension>...
tells apache we want mod-xslt to parse all files with extension ``extension''.
AddOutputFilterByType mod-xslt <mime-type>...
tells apache we want mod-xslt to parse all files with the specified mime-type.
Note that the mime-type should indicate which files we want mod-xslt to parse.
Most common values are text/xml or application/xml, depending upon the configuration
of your system.
tells apache that we want all files in a given directory or location or virtual
host to be parsed by mod-xslt.
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.
For example, you may enable mod-xslt in a given directory with something
AddOutputFilterByType mod-xslt text/xml
Note that on most system both .xml and .xsl files are considered of
mime type application/xml. We often suggest to change that default
and set the mime type of .xml files to text/xml and of .xsl files
of text/xsl. You can usually use constructs like ``AddType text/xml .xml''
to force a mime type of text/xml to .xml files...
If you know before hand that all files in a given directory should be parsed
using mod-xslt, you may also use something like:
To have further details about the discussed parameters, please take a look
to the apache manual, http://httpd.apache.org/.
It is important to note that it is possible to block mod-xslt from parsing
a particular document by using the SetEnvIf parameter and the SetEnv family
of configuration directives. mod-xslt will infact NOT
perform any transformation if the ``no-xslt'' environment variable is set.
XSLTSetStylesheet <MimeType> <Stylesheet> 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.
XSLTUnSetStylesheet <MimeType> <Stylesheet> 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
XSLTDefaultStylesheet <MimeType> <Stylesheet> 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.
XSLTNoDefaultStylesheet <MimeType> 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.
XSLTParam "variable" "value" 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''. Those variables are accessible from the stylesheet using the mod-xslt2 extension
value-of, with something like: <mxslt:value-of select="$MODXSLT[variable]" ... look to the variable
substitution paragraph for more details...
XSLTAddRule "stylesheet" "condition" 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.
XSLTDelRule "stylesheet" per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to forget about the rule regarding the specified stylesheet
XSLTDebug category, category, category, ... per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to print (in the log files) the debugging messages corresponding to the specified categories. Note that
any given message can be part of more than one category. It will be outputted only if all the categories are to be outputted according to this
parameter. Currently defined categories are: config (parsing of configurations), debug (useful when running gdb, debugging crashes or trying to find
errors in the debug system itself), flags (if enabled, the category of the messages/mask is also outputted in integer format), libxml (parsing done by libxml),
parser (parsing of PI and mod-xslt expressions at top of .xml files), proto (related to HTTP protocol, headers, and so on), rules (for apache1, output debugging
messages related to application of *Rules*), sapi (output messages related with the interaction of the specified SAPI), variables (output messages regarding
parsing and handling of variables), verbose0, verbose1, verbose2 (to enable outputting of messages at verbosity 0, 1, and 2).
XSLTDebugMask <number> per directory, per file, per virtual host or in
global configuration file, tells mod-xslt2 to print (in the log files) the debugging messages corresponding to the specified categories. This is exactly like
the XSLTDebug parameter, but allows to specify which messages to output as an integer. The integer represents the OR of the integer value corresponding to each
category whose output is desired. Note that internally mod-xslt maps every debug category to an int, and every category is mapped to a ``name'', as indicated
above. This parameter is useful when you either want to output all messages (specify -1 as the number) or when there is some category of messages that has not
been assigned a str name yet. Have a look into modxslt0/modxslt-debug.h, mxslt_debug_e, to see the mapping betweween categories and parameters.
XSLTDisableSignature<number> per directory, per file, per virtual host or in
global configuration file, doesn't do anything, for backward compatibility only.
In order to use php4 with apache2, you can compile it using
two different SAPI:
To know more about the differences between HANDLERs and FILTERs in
apache 2.x.x, please refer to apache 2.0.x documentation.
To know more about how to compile php4 using the two SAPI or about
the differences between the two, please refer to php4 documentation.
At time of writing, however, if you compile php4 to run under apache2
it will be compiled using the HANDLER sapi.
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.