<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="index.xsl"?> <data title="mod-xslt documentation" > <chapter title="what is mod-xslt" id="1" > <section headline="Introduction" > <paragraph>Do you always install software without knowing what it is? Or are you beeing a bad little geek and reading this before hand ;->? Well whatever, here's the jist of it:</paragraph> <paragraph>mod-xslt is an apache module for the new 2.0 series of the webserver, that runs more websites than any other. It is a filter, a concept new to Apache in this version.</paragraph> <paragraph>You are probably already guessing from the name and the fact that it is a filter, that it filters XML-data with the help of XSLT. And gues what, you are right. XSLT is a wonderful language for transforming XML-data into just about anything you could want. And this module helps out by enabling web-developers to seperate the look of a site from the data contained in it.</paragraph> </section> <section headline="What is used for the transformation?" > <paragraph>Good question! I decided against Xalan/Xerces, what a lot of people might think would be the logical option to use libxml2/libxslt by Daniel Veillard, a Red Hat guy based in France. Why did I make that decision? Well it is actually quite simple: Xalan/Xerces are complicated and slow due to their Java acestry. Libxml2/libxslt are fast and easy due to their plain C implementation.</paragraph> </section> </chapter> <chapter title="Installing" id="2" > <section headline="Installing the Libraries" > <paragraph>There are 2 libraries required for mod-xslt: libxml2 and libxslt. If you use a Redhat system these are usually already installed. However I do suggest you upgrade to the RPM's I provide on the mod-xslt site. The reason being, that older versions (including the one with Redat-7.3) are missing the support for the media-type attribute of the xsl:output node. I already submitted a patch to Daniel Veillard, which has been accepted, so this may cease to be an issue sooner or later. If you don't care about this feature which allows you to set the mimetype of your output, and are content with outputting either text/html, text/xml or texl/plain, you can just go ahead and use the versions that came with your system.</paragraph> </section> <section headline="Installing Apache" > <paragraph>I do provide an RPM-package at the mod-xslt site. Feel free to use that if you wish. Aside from that you can use any source for your Apache installation, as long as you make sure apache is installed under /usr/local/apache. If you want to install it somewhere else feel free, but be aware that you will need to mess with the mod-xslt makefile if you do. (Not really a problem, + I am there to help if need be).</paragraph> </section> <section headline="Installing the RPM" > <paragraph>I just finished the packaging of mod-xslt so from now on it is probably easiest to install the RPMs provided via <link href="http://www.mod-xslt.com/" /> or via Sourceforge. This will take care of everything you need to do.</paragraph> <paragraph>You should take care of the following few things though. The closer you do the install of mod-xslt to the install of Apache, the better, since I use diff/patch to modify the httpd.conf file. Furtherore I am making some assumptions on your setup. I assume Apache is installed at /usr/local/apache. If you don't have Apache installed yet, I suggest you use the RPM I provide on the mod-xslt site as well, since it has the right settings preconfigured.</paragraph> </section> <section headline="Installing from a tarball" > <paragraph>Do the usual set of make and make install. That should do it. But check the sections above. All warnings, assumptions, etc apply here as well!</paragraph> </section> </chapter> <chapter title="Configuring" id="3" > <section headline="The basics" > <paragraph>The basics should have been done by the install-process. But in case they weren't or not correctly, here is the jist of what needs to happen:</paragraph> <paragraph>LoadModule XSLT modules/mod-xslt.so</paragraph> <paragraph>AddOutputFilterByType XSLT text/xml</paragraph> <paragraph>AddType text/xsl xsl</paragraph> </section> <section headline="Custom Directives" > <paragraph>XSLTSetStylesheet <mime-type> <href-of-stylesheet> sets the default stylesheet for a given directory and mime-type (You could attach mod-xslt to any mimetype as log as what gets to it is wellformed XML (even if it isn't no harm done the data will just be passed through (INEFFICIENT!!)))</paragraph> <paragraph>XSLTUnSetStylesheet <mime-type> reverses the effect of the above. This is necessary since Directives for directories are inherited!</paragraph> </section> </chapter> <chapter title="Using" id="4" > <section headline="xml-stylesheet" > <paragraph>The xml-stylesheet Porcessing instruction is used to assign a stylesheet to an XML-File. This is standard in XML and should be the general way to go about it. Just be aware, that the type pseudo-attribute needs to be set to either text/xml or text/xsl. </paragraph> </section> <section headline="xslt-stylesheet" > <paragraph>xslt-stylesheet is a custom Processing instruction I implemented. It is used just like the xml-stylesheet PI except it takes a pseudo-attribute "useragent" instead of type. This is the User-Agent string passed by the browser and allows you to define a stylesheet depending on the browser that makes the request. </paragraph> <paragraph>I am planning on making this quite a bit more versatile, but this has to do for now with an exact match of the User-Agent. If it doesn't match, it doesn't associate the Stylesheet. Also be aware that both xml-stylesheet and xslt-stylesheet work on a first come first serve basis. I.E.: the first match will be used! </paragraph> </section> <section headline="xslt-param" > <paragraph>This is a PI custom for mod-xslt. It is used to specify additional parameters passed to the XSLT-Processor. Additional means in addition the those from the query-string. This is useful for XML coming from a CGI for example.</paragraph> </section> <section headline="xslt-base" >One more custom PI. It sets whether the XSLT should be loaded relative to a file:// URL or a http:// URL. This means if yous pecify a stylesheet with a relative URL what is it relative to. The actual XML-File as given to mod-xslt by r->filename or the requested URL that the user typed in from the browser. Since basing things on the http:// URL means that there is an http:// request fired for the stylesheet as well, this is mostly used for the case where you want to generate the stylesheet dynamically. Therefore file:// is the default. The two vaiations look like: <?xslt-base href="http://"?> and <?xslt-base href="file://"?> </section> </chapter> <chapter title="Thanks and Acknowledgements" id="5"> <section>Thanks to all the people that have tested mod-xslt so far. I received overwhelming feedback from a lot of people. See the THANKS file of the tarball for details. The current list of great individuals is also found at <link href="http://www.mod-xslt.com" >www.mod-xslt.com</link> </section> </chapter> </data>
