HOME
User Manual |  Mailing Lists | 
  -
»About mod-xslt
»About this site
»Credits
  -
»Join mailing list
»Mailing list archive
  -
»Releases (github)
»Old Versions
»Testing Suite
»Documentation
  -
»Browse GIT (github)
»Report Bugs (github)
  -
»User Manual
»Frequently Asked Questions
»Standards
»Wiki (github)

Users and Administrators Manual

Author:  Carlo Contavalli 
Date: 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.

    | First || Previous || Next || Last |

    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 systems, 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.

    • SetOutputFilter mod-xslt 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 like:
    <Directory /this/is/a/directory>
      AddOutputFilterByType mod-xslt text/xml
      ...
    </Directory>
      
    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:
    <Directory /this/is/another/directory>
      ...
      SetOutputFilter mod-xslt
    </Directory>
      

    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 parent directories.

    • 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:

    • apache2filter - where php4 is used as an Apache 2.x.x FILTER

    • apache2handler - where php4 is used as an Apache 2.x.x HANDLER

    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.

    | First || Previous || Next || Last |
      -
    »Debian GNU
    »Apache Project
    »Gnome libxml2
    »Gnome libxslt
    »Gnome Project
    Introduction
    Installation
    mod-xslt2 Setup and Usage
    Writing XML for mod-xslt2
    Security considerations
    Reporting BUGS / Helping out the project
    License, copyright and...