Jakarta Project: XTags Library

Version: 1.0

Table of Contents

Overview

XTags implements an XSLT-like JSP tag library to allow navigating, processing and styling of XML documents directly in JSP. In many ways XTags is like XSLT implemented in JSP allowing you to seamlessly work with JSP, custom tags, JavaBeans and the whole J2EE platform from inside a single piece of JSP!

XTags makes heavy use of the XPath expression language. For a good tutorial on XPath you could try the either the Zvon tutorial or the specification.

XTags is currently built on top of dom4j the flexible open source XML framework for the Java platform. Though increasingly XTags will use a pluggable XPath engine to support the travesal of DOM and Java Beans too.

To begin with you need to parse an XML document from somewhere. You can parse a variety of sources of XML documents from local resources, the output of JSP or external web services.

You can parse the body of the tag

    <xtags:parse>
        <root>
            <child/>
        </root>
    </xtags:parse>

Or parse an absolute URL via the "url" attribute

    <xtags:parse url="http://something.com"/>

You can parse a web app resource using an absolute URI relative to the web-app context using the "uri" attribute

    <xtags:parse uri="/data/foo.xml"/>

Or you can use a URI relative to the the current JSP file

    <xtags:parse uri="foo.xml"/>

Then for more complex requirements such as parsing the output of a piece of JSP, when we get to JSP 1.2, we'll be able to do...

    <xtags:parse>
        <jsp:include page="foo.jsp"/>
    </xtags:parse>

Until then you can use the IO tag library to make these requests such as

    <xtags:parse>
        <io:request url="/foo.jsp"/>
    </xtags:parse>

Though the above would result in a seperate HTTP request which would loose all page, request and session scope state. So if it must be in the same request the following should work though care should be taken to avoid scripting variable clashes

    <xtags:parse>
        <%@ include file="/foo.jsp" %>
    </xtags:parse>

To parse the output of an XML-RPC (or SOAP) call, using the IO taglib you could do the following.

    <xtags:parse>
        <io:xmlrpc url="/xmlrpc_echo.jsp">
         <io:pipe>
          <methodCall>
             <methodName>examples.getStateName</methodName>
             <params>
                <param>
                   <value><i4>41</i4></value>
                   </param>
                </params>
             </methodCall>
         </io:pipe>
        </io:xmlrpc>

    </xtags:parse>

Once you have a document parsed you can navigate around its structure using XPath expressions in a similar manner to that used in XSLT.

Loops are as follows (an optional variable id can be specified to define a scriptlet expression inside the loop):-

  <xtags:forEach select="expression">
    ...
  </xtags:forEach>

Simple conditional branching is:-

  <xtags:if test="booeanExpression">
    ...
  </xtags:if>

More complex conditional branching is:-

  <xtags:choose>
    <xtags:when test="booeanExpression">
      ...
    </xtags:when>
    <xtags:when test="booeanExpression2">
      ...
    </xtags:when>
    <xtags:otherwise>
      ...
    </xtags:otherwise>
  </xtags:choose>

Expression evaluation

  <xtags:valueOf select="expression"/>

Defining scriptlet variables

  <xtags:variable id="variableName" select="expression"/>

All these tags are very similar to their XSLT equivalents, so anyone who's done XSLT before should find them familiar. There's also an <xtags:style> tag which performs complete XSL transform in one tag.

XPath expressions can use variables with the syntax $foo. XTags binds these variables to either page/request/session/application scope attributes or request parameters which allows xtags to be used as a conditional logic scripting language too - even without the existence of XML documents.

For example, the following JSP would branch logically based on the value of the (say) request parameter "param":-

  <xtags:choose>
    <xtags:when test="$param='a'">
      current param is 'a'
    </xtags:when>
    <xtags:when test="$param='b'">
      current param is 'b'
    </xtags:when>
    <xtags:otherwise>
      no valid param selected
    </xtags:otherwise>
  </xtags:choose>

XTags even supports the <xtags:stylesheet> <xtags:template> and <xtags:applyTemplates> tags from XSLT too though the body of a template must be an Action object or a seperate JSP file.

Requirements

This custom tag library depends on a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher and also requires a distribution of dom4j and log4j. To be able to use the <xtags:style> tag then a distribution of JAXP is required along with an XSLT implementation such as xalan.jar and crimson.jar

Configuration

Follow these steps to configure your web application with this tag library:

• Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application.
• Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application.
• Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

  <taglib>
    <taglib-uri>http://jakarta.apache.org/taglibs/xtags-1.0</taglib-uri>
    <taglib-location>/WEB-INF/xtags.tld</taglib-location>
  </taglib>
  

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/xtags-1.0" prefix="xtags" %>

where "xtags" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

Tag Reference

See the example application xtags-examples.war for examples of the usage of the tags from this custom tag library.

Java programmers can view the java class documentation for this tag library as javadocs.

Review the complete revision history of this tag library.