mod_xslt README

I have had the need/desire to rework mod_xslt again. This is a wholly new version, that has some distinct differences previous versions. So don't get them confused.

The most notable difference is that there is only one file. I opted for packing it all in one file because I wanted to get closer to what the usual Apache modules look like as well as making mod_xslt a bit simpler as well. Additionally having multiple files always caused messes in istallation for a lot of people.

The other changes are more subtle. For example I opted to remove the reverse serving feature that Gennady Feldman devised. This is not because I think it's not worthwhile, but rather because I thought that it is overkill. I wanted a clean mean xml machine.

Which is, incidentally, also the reason why I removed my very own cookie and exslt handling stuff.

Aside from this, I cleaned the whole thing up. So the code is about 90% different from the last version. I decided to make significantly more use of what Apache provides in terms of memory handling and so on. At the same time becoming a lot cleaner and significantly more stable.

All this reworking has brought out an enhancement from the original version as well.

INSTALLING: I use the apxs tool to compile and install these days.

my command is: 

bash# apxs -c -lxml2 -lxslt -I/usr/local/include/libxml2 mod_xslt.c

to compile. You need to either specify -lxml2 and -lxslt here or load the libraries via the LoadFile directive from httpd.conf. I prefer doing it here. The -I/usr/local/include/libxml2 is necessary in order to tell the compiler where the header files for libxml2 are, since they are somewhot none standard. You can find them using xml2-config.

After that you have to copy the file mod_xslt.so from ./.libs/mod_xslt.so to your modules directory.

INSTALLING: I prepared a little shell-script to automate the compiling and installing for you. it's called ./Makefile.sh
If you have apxs,apachectl,xml2-config and xslt-config in your path and are root just ./Makefile.sh . Otherwise become root and set some environment variables:
APXS="/path/to/apxs"
APACHECTL="/path/to/apachectl"
XMLCONF="/path/to/xml2-config"
XSLCONF="/path/to/xslt-config"
This makes things a bit easier. however if you are having problems try fiddling with the manual installation using apxs directly described above.

BEWARE if you use a threaded MPM you also need to #define NOCACHE if this is set caching is disabled, but the module should be fine with threads. (The old version had absolutely no chance of ever being thread safe)


After that you have to edit httpd.conf. At the end of your LoadModules section insert:

LoadModule mod_xslt modules/mod_xslt.so

After that all you need to do is activate it:

#prevent xsl files from being parsed here (optional but recommended)
AddType text/xsl .xsl

AddOutputFilterByType mod_xslt text/xml

And off you go. That's basically it.

Here are some more directives you can use.

XSLTCache < on | off >  (Default: on) prohibits xsl caching for a directory
XSLTProcess <on | off > (Default: on) turns mod_xslt off for a directory
XSLTDefault < url > Specifies a default Stylesheet for a directory

These 3 can be overridden anywhere where where FileInfo directives are allowed. (i.e.: just about anywhere) If you want to allow these in .htaccess you need to set AllowOverride FileInfo

Now on to the Processing instructions used in mod_xslt itsself:

<?xml-stylesheet type="text/xsl" href="URL"?>

The standard <?xml-stylesheet type="text/xsl" href="URL"?> is of course supported but beware, that you should not use the document part sematic (i.e: <?xml-stylesheet type="text/xsl" href="#stylesheet"?> will break horribly)

There is one more very powerful PI:

<?xsl-stylesheet agent="regex" accept="regex" href="URL" noprocess="yes"?>

You need to specify at least one of agent or accept, but both are OK. If neither is there the PI is ignored. And of course href is mandatory as well.

agent contains a perl-compatible regular expression that is matched againd the User-Agent header. This means it's the same as doing this in stylized-perl:

if ($useragent =~ /regex/) { match is true; }

The same thing holds true for the accept attribute except it matches against the Accept header.

This gives you a quite powerful tool. You can specify via regular expression for which useragent/possible-mime-type which stylesheet is used.
for example, by using this facility you could serve the same xml document to a mobile phone using wap as to a full featured browser such as IE,Mozilla,Safari,Opera,et al.

The order of these Processing instructions is very important. The first one that matches is used. That also means that you can set up some special cases using <?xsl-stylesheet ...?> and then specify a default for the document using <?xml-stylesheet ...?>

The noprocess="yes" attribute is the alternative to specifying an href attribute. It tells mod_xslt not to bother processing this file. So you can use this to let browser at the Client-Side do the xslt transformation instead. This was added to satify a requirement by Edouard Vanbelle and seemed like an excellent idea.

Now that is what I call power!!!

That's it. Now you know it all.

I hope you find this new version useful, and share my joy.

Please let me know what you think. Tell me if it is useful, if it breaks, if you have troubles, or if you have pure bliss. I am really interested in your experiences. they are what keeps me at it.

You can reach me via e-mail at philipp@dunkel.org

No go out and be merry!

Greetings, Philipp Dunkel
Vienna, Austria December 13th 2003
