mod_xsl -- An inets module to tranform XML documents generated by mod_esi

mod_xsl is an inets module that allows XSL transformations on XML documents generated by mod_esi. The stylesheet selection is based on the document type and the environment of the http query (user agent, accept, query string, etc.). The module uses an XSL Engine, for instance sablotron_adapter, to carry out the actual XSL transformation.

Original version of this documentation at LFCIA lab, University of A Coruña, Spain

Mirror at SourceForge

Motivation

When developing monet, a flexible monitoring tool for the VoDka project, we needed a way of generating monet output to different devices: standard browsers, text-only browsers, wap-enabled terminals, and so on. Generating monet output as XML documents and then transforming them using an XSL engine with rules to choose the appropriate XSL style became an elegant and effective solution.

How does it work?

For each document type (as stated in the XML Document's DOCTYPE declaration), mod_xsl requires a set of possible transformations. Each of these transformations, among other things, consists of a predicate that checks whether the XSL stylesheet is valid given the current http environment. mod_xsl is in charge of choosing the appropriate stylesheet from both the document type and the environment and replacing the response by transforming it using the chosen XSL and an XSL Engine (i.e., sablotron_adapter).

Downloading

mod_xsl-0.2.tar.gz
Alternatively, you can get it from the sourceforge project page.

In addition, you will need the following software:

Erlang (that was easy to guess)
An Erlang XSL engine, such as sablotron adapter. You can also get it from sourceforge.

Installation

Compiling
You should install the XSL engine (for instance, sablotron_adapter) in first place.
Before compiling mod_xsl, you should make available the include httpd.hrl.
```
   ln -s %%ERLANG_SOURCES_PATH%%/lib/inets-2.5.X/httpd.hrl src/httpd.hrl
```
Then, compile mod_esi:
```
   make
```

Testing

To check if mod_xsl is working you can use the examples provided in the priv directory. Type from Unix shell:

  make test
  erl -config priv/server_root/inets

Change the configuration priv/server_root/conf/httpd.conf in order to set the correct parameters for the XSL engine

XslEngine sablotron_xsl_engine /usr/lib/erlang/lib/sablotron_adapter-1.1/bin/sablotron_adapter

from Erlang shell:

  code:add_path("./ebin").
  code:add_path("./priv/server_root/src").
  application:start(inets).

try the following URLs:

  http://localhost:8001/erl/test/employees
  http://localhost:8001/erl/test/staffmember
  http://localhost:8001/erl/test/publications

Installing
Check if the installation directory is set properly and then:
```
  make install
```

Configuration

To properly use mod_xsl you have the following directives that can be included in the inets configuration file:

XSL Engine
mod_xsl needs a module to perform the actual XSL tranformation. The selection of the XSL Engine is established with the XslEngine directive:
XslEngine XSL_ENGINE INIT_STRING
where XSL_ENGINE is an Erlang module implementing the XSL Engine and INIT_STRING is a string for the initialization of the engine (XSL_ENGINE:start(INIT_STRING)). For instance, if sablotron_adapter is used as XSL Engine, the configuration file should have:
XslEngine sablotron_xsl_engine SABLOTRON_ADAPTER_PATH
where SABLOTRON_ADAPTER_PATH is the path of the port adapter for the sablotron library.
XSL Rules
In order to choose the approriate XSL stylesheet, mod_xsl must be configured with a set of rules to establish the selection procedure. The rules are declared in the inets configuration file with the XslRules directive:
XslRules RULEPATH (RULEFILE)+
where RULEPATH is the base path for the rules files and RULEFILE is a collection of rules with the following format:
{ENTITY, DESCRIPTION, MIMETYPE, XSLFILE, CONDITION}.
- ENTITY is the document type as stated in the (*must have*) DOCTYPE declaration of the XML document
- DESCRIPTION is a string with a small description of the rule
- MIMETYPE is the expected MIME type of the transformed result
- XSLFILE is the filename of the XSL stylesheet
- CONDITION is a functional argument that checks a dictionary [{Key,Value}] feeded with header environment, query string, etc. to determine if the stylesheet can be applied. It can be:
  - Function: one predicate with no extra arguments (definition in mod_xsl_stdpreds)
  - {Function,ExtraArg}: one predicate with an extra argument (definition in mod_xsl_stdpreds)
  - {Module,Function,ExtraArg}: one predicate with an extra argument defined in module Module.
  Some predefined predicates:
  - Trivial ones
    - always
    - never
  - Pattern-matching: {match, {Symbol,RegExp}}. The rule can be applied if Symbol exists in the dictionary and its value matches RegExp. For example, {match, {"User-Agent", "Mozilla"}}
  - Combinatory predicates: build complex predicates from simpler ones
    - {neg, Predicate}. Negation of Predicate
    - {any, [Predicate]}. True if any predicate in the list is true
    - {all, [Predicate]}. True if all predicate in the list are true
    For example, the following condition is true when the browser (user agent) is either a Mozilla-like (Internet Explorer, Netscape) or Lynx:
    
    {any, [{match, {"User-Agent", "Mozilla"}}, {match, {"User-Agent", "Lynx"}}]}
  - Some commodity predicates are also predefined in mod_xsl_stdpreds:
    - mozilla
    - netscape
    - iexplorer
    - iexplorer_pocketpc
    - lynx
    - links
    - w3m
    - wml
    - nokia7110
    - alcatel301
    - {user_agent, UA}
    Thus, the previous example can be written as {any, [mozilla,lynx]}
All the rules for the current document type are checked sequentially; the first matching rule will be applied. If none, the content type text/xml; doctype=DOCTYPE is added to the response header.
XSL Hook
The dictionary [{Key,Value}] used for testing the predicates is initially built from both query string parameters and http header; the XslHook directive allows applications to change/delete/add {Key,Value} pairs. XslHook HookModule HookFunction
where HookFunction/1 is exported in HookModule. The parameter of this function is the current dictionary and it delivers a (maybe) modified version. This mechanism allows, for instance, to include application dependant information (such as user preferences) based upon some parameter already present in the dictionary such as a session identifier. The following example illustrates the idea:
```
   add_user_preferences(Dict) ->
      case httpd_util:key1search(Dict, "session_id") of
        undefined ->
           Dict;     %% no session
        SessionId ->
           get_application_dependant_preferences(SessionId) ++ Dict
      end.
```
Thus, application-dependant {Key,Value} can be added to the XSL context (say, for example, [{"news_style","verbose"}, {"frames","no"}]). For debugging purposes, a hook is included with mod_xsl; it prints out the current dictionary.
XslHook xsl_debug_hook show

Known Limitations

Even though inets' responses can be arbitrarily deep lists (perhaps including binaries in the middle), the mod_xsl scanner will only succeed if the xml document prologue is a plain list of chars. Thus, try to create responses like this:

     "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n" ++
     "<!DOCTYPE employees>" ++ 
     TheRestOfTheXmlDocument

Ya, I could flatten the whole response and convert the binaries to lists, but that is quite expensive if documents are large 8-{

You should see also...

Related tools:

sablotron_adapter, an Erlang adaptation of the C++ XSL library sablotron that can be used as XSL Engine with mod_xsl.
erlatron, a clustered version of the sablotron adaptation.

Some examples of mod_xsl at work:

monet, a distributed monitoring tool. Its output is generated as XML documents and then transformed using mod_xsl.

Víctor M. Gulías

Last modified: Fri May 18 15:14:46 CEST 2001

This page served from