*
XML HandlerXML Handler
The xml handler is used to highlight a chunk of xml text.

The handler is implemented by the XMLHandler class and initialized via the XML Configured Processor. The xml must be well-formed and parseable.

You can either provide the xml to highlight as the content of the tag, or (as of version 0.2) you can specify a xml file and an XPath (like, not strictly XPath syntax) expression to identify an element that should be extracted from the file and highlighted.

Example:
[xml]
<html>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>
[xml]
(As an aside, it was a real pain to do the xml above because all the < characters have to be replaced with a &lt; character entity!)

Becomes:
<html>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>
Another example:
[xml hoglet,data/tag-handlers.xml,/tagHandlers/handler@tag:xml/]
Becomes:
<handler class="org.hoglet.handlers.core.XMLHandler"
         tag="xml">
    <init>
      <src id="hoglet"
         url="d:/development/hoglet/" />

      <templates>
        <wrapper><[CDATA[<div class="source-div"><pre class="source">[[VALUE]]</pre></div>]]></wrapper>
        <attributeNameWrapper><[CDATA[<span class="xml-attribute-name">[[VALUE]]</span>]]></attributeNameWrapper>
        <attributeValueWrapper><[CDATA[<span class="xml-attribute-value">[[VALUE]]</span>]]></attributeValueWrapper>
        <elementNameWrapper><[CDATA[<span class="xml-element-name">[[VALUE]]</span>]]></elementNameWrapper>
        <textWrapper><[CDATA[<span class="xml-text">[[VALUE]]</span>]]></textWrapper>
        <commentWrapper><[CDATA[<span class="xml-comment">[[VALUE]]</span>]]></commentWrapper>
      </templates>
    </init>
  </handler>
 
Handler Options
The handler supports up to 3 anonymous options.

The behaviour of the handler is dependent upon the number of options provided.

3 Options provided
In this case:
  • Option 1 is taken to be a shortcut to a url that should be prefixed to Option 2.
  • Option 2 is taken to be a path that should be appended to Option 1. The combination of Option 1 (expanded to get the real url prefix) and Option 2 constitute the url to use. The url should point to a file that contains the xml to use.
  • Option 3 is taken to be a XPath that is used to identify an element that should be extracted from the file.
Example:
[xml hoglet,data/tag-handlers.xml,/tagHandlers/handler@tag:xml/]
2 Options provided
In this case:
  • Option 1 is taken to be a url that should point to a file to be retreived. A check is also made to see if Option 1 maps to one of the shortcuts known to the handler, if a match is found then the shortcut url is used instead.
  • Option 2 is taken to be a XPath that is used to identify an element that should be extracted from the file.
Example, with Option 1 providing the full url:
[xml http://hoglet.sourceforge.net/data/tag-handlers.xml,/tagHandlers/handler@tag:xml/]
Example, with Option 1 providing a shortcut value to the url:
[xml hoglet,/tagHandlers/handler@tag:xml/]
1 Option provided
In this case:
  • Option 1 is taken to be a url that should point to a file to be retreived. In this case the entire contents of the file is used. A check is also made to see if Option 1 maps to one of the shortcuts known to the handler, if a match is found then the shortcut url is used instead.
Example:
[xml http://hoglet.sourceforge.net/data/tag-handlers.xml/]
Example, using shortcut:
[xml taghandlers/]
 
URLs
Protocols http, https and file are supported for the urls. If no protocol is explicitly provided then file is assumed. Relative file paths are NOT supported.
 
XPaths
A very small subset of XPath is supported to allow the unique identification of an element within the file. Also, the syntax has been modified slightly to allow for seemless integration with hoglet (i.e. so that extensive escaping isn't required within the hoglet tag).

All paths must start with / and thus refer to the root element.

Child elements are separated with /.

You can refer to an attribute by appending @ after the element name (note: DO NOT use [) and then providing the attribute name, i.e. myelement@myattribute. To specify an attribute value append : after the attribute name and then the value. Thus:

> myelement@myattribute:value
 
Shortcuts
To make referencing urls easier the handler supports shortcuts. This is basically a short name that maps to a url prefix (or a full url).

The shortcuts are defined in the init element. The shortcut is defined by using a src element, two attributes id and url are required, the id attribute defines the short name for the shortcut and the url defines the url that it maps to.

Example:
[xml hoglet,data/tag-handlers.xml,/tagHandlers/handler@tag:xml/init/src/]
There is no limit to the number of shortcuts that can be defined. Shortcut names are case-sensitive.

 
XML Initialization
The handler is initialized via an init element (see XML Configured Processor for details).

The init element can optionally contain one or more src elements (see shortcuts).

It should also contain a templates element. Which in turn should contain a wrapper element that contains some wrapper markup. The value: [[VALUE]] is replaced in that markup with the processed/highlighted xml.

For example:
<wrapper><[CDATA[<div class="source-div"><pre class="source">[[VALUE]]</pre></div>]]></wrapper>
The templates element can also, optionally, contain the following elements (each one is effectively a template which is used to wrap part of the xml thus providing the highlighting):
  • elementNameWrapper - this is used to wrap the element name.
  • attributeNameWrapper - this is used to wrap an attribute name.
  • attributeValueWrapper - this is used to wrap an attribute value.
  • textWrapper - this is used to wrap text content, including a CDATA section.
  • commentWrapper - this is used to wrap a comment.
In each of the wrapper templates defined above, they should contain a [[VALUE]] value, that value will be replaced with the relevant value from the xml file.
*