UIEvolution XML Tag Library Reference
Version 1.0
Copyright 2001-2005 by UIEvolution, Inc. All rights reserved.
UIEvolution XML Tag Library Reference
Version 1.0
Copyright 2001-2005 by UIEvolution, Inc. All rights reserved.
XML has become an incredibly powerful tool for delivering data between computer systems of various architectures and using various operating systems. Today you can find a public XML data feed describing almost anything. Although XML has made the transfer of data between computers very easy, using the information in an XML document can be cumbersome. APIs like SAX (Simple API for XML) and JDOM (Java Document Object Model) have been created to help programmers use XML data within programs, languages like XSL have been created to help Web authors transform XML into other forms, and publishing systems like Cocoon have been created to help content providers deliver XML-based content to the world. None of these technologies, however, provides a lightweight, easily deployable method of delivering dynamic content based on XML data. The UIEvolution XML Tag Library has been designed to fill this need. It allows Web developers to create dynamic content from within JavaServer Pages (JSP) using data from one or more external XML documents.
The UIEvolution XML Tag library is a standard JSP tag library that can be deployed into any context of a compliant JSP container. Once deployed, the tags defined by the library are available to all JavaServer pages in that context.
The Java Archive (JAR) file containing the tag library is actually composed of three distinct components: an XML parsing framework, a lightweight XML document representation, and the tag library itself.
The XML parsing framework uses SAX to enable other components to easily parse XML documents. The lightweight XML document representation used the parsing framework and is a lot like JDOM except that it makes some assumptions and takes some shortcuts to keep runtime overhead to a minimum. The tag library uses the document representation to load an XML document and traverse the information it contains.
Although the UIEvolution XML Tag Library was designed to simplify access to data in XML documents, its abstract concepts and integration with a JSP container cause its use to be non-trivial. This section introduces some of the basic concepts of the tag library and details needed for its deployment in a JSP context.
An XML document being accessed by the UIEvolution XML Tag Library is represented as a tree of nodes containing the document itself, its elements, and their attributes and text, maintaining the order and parent/child relationship of each as it exists in the source document.
Almost all the tags defined by the library do one of two things: they either provide a context for other tags to do their work, or they emit a value into the output of your JSP. Almost all of the tags act within the context defined by another, enclosing tag from the library. The one significant exception to this rule is the document tag, which can exist outside of any other tag.
A context defines a point in the tree representation of an XML document. It can refer to zero, one, or more tree nodes. The body of the context tag will be evaluated for each one of the nodes referenced by the context.
Since the UIEvolution XML Tag Library is always used from within JSP, it must be properly deployed in the servlet context of those pages to be available. This requires two things: the library’s JAR file must be on the classpath for the context and the library must be declared in the deployment descriptor of the context.
Adding the library’s JAR file to the servlet context’s classpath can be as simple as putting the file in the “WEB-INF/lib” directory within the context’s directory.
Declaring the tag library for a given servlet context requires modification to the servlet context’s deployment descriptor. This is found in “WEB-INF/web.xml” within the context’s directory.
The following tags should be added to the deployment descriptor of the context. Generally, the tags should appear just before the closing </web-app> tag, although there are other tags that can appear after these tags in the descriptor file.
<taglib>
<taglib-uri>uiexml-taglib</taglib-uri>
<taglib-location>/WEB-INF/lib/uiexml.jar</taglib-location>
</taglib>
A JavaServer page that uses the UIEvolution XML Tag Library is just like any other JSP with the addition of a taglib directive and the tags themselves. Rather than just explaining the syntax of each tag, several example JSP files will be shown that use the tag library. Each will reference a simple XML document that contains the latest CNET news stories and will process the contents of that document. The examples will start very simply, using only a few basic tags, and will progressively introduce more tags and complexity.
This example displays each story’s title in HTML. It uses four tags from the library: <uiexml:document>, <uiexml:child>, <uiexml:children>, and <uiexml:text>. Each of these tags and their use is explained below.
01: <%@ taglib uri="uiexml-taglib" prefix="uiexml"%>
02: <html>
03: <head>
04: <title>News Titles #1</title>
05: </head>
06: <body>
07: <uiexml:document url="http://rss.com.com/2547-12-0-20.xml">
08: <h3>News Titles #1</h3>
09: <ul>
10: <uiexml:child tag="rss">
11: <uiexml:child tag="channel">
12: <uiexml:children tag="item">
13: <uiexml:child tag="title">
14: <li><uiexml:text/></li>
15: </uiexml:child>
16: </uiexml:children>
17: </uiexml:child>
18: </uiexml:child>
19: </ul>
20: </uiexml:document>
21: </body>
22: </html>
In the example above, line 1 shows how to use the “taglib” directive to tell the JSP container that you want to use the UIEvolution XML Tag Library.
Line 7 shows how to reference an XML document using the tag library. For lines 8 through 19 (right before the closing </uiexml:document> tag), the context for any other XML tags is the document referenced by the “url” attribute of the document tag.
Line 10 sets the context of lines 11 through 17 to the root element of the document; in this case the “rss” element.
Line 11 sets the context of lines 12 through 16 to the first child element of the root element whose tag is “channel”.
Line 12 sets the context of lines 13 through 25 to the set of all child elements of the “channel” element whose tag is “item”. These lines of the JSP file will be evaluated once for each one of these elements (e.g. if there are 12 items, lines 13 through 25 will be evaluated 12 times, each time with a new element as the context).
Line 13 sets the context of line 14 to be the first child of the current item whose tag is “title”.
Line 14 emits a single unordered list item containing the text of the current element. In this case, it’s the “title” element of the current “item” element.
This example will generate the same HTML output as the previous example with the addition of links to news stories, but will do it with fewer, more powerful tags from the tag library. Only lines that are different from the previous example will be discussed. The new tags are <uiexml:descendants>, and <uiexml:child-text>.
01: <%@ taglib uri="uiexml-taglib" prefix="uiexml"%>
02: <html>
03: <head>
04: <title>News Titles #2</title>
05: </head>
06: <body>
07: <uiexml:document url="http://rss.com.com/2547-12-0-20.xml">
08: <h3>News Titles #2</h3>
09: <ul>
10: <uiexml:descendants path="rss/channel/item">
11: <li>
12: <a href='<uiexml:child-text tag="link"/>'>
13: <uiexml:child-text tag="title"/>
14: </a>
15: </li>
16: </uiexml:descendants>
17: </ul>
18: </uiexml:document>
19: </body>
20: </html>
Line 10 replaces the nested <uiexml:child> and <uiexml:children> tags of the previous example with a single <uiexml:descendants> tag. This sets the context for line 11 to be the set of elements whose tag is “item” within the first element whose tag is “channel” within the first item whose tag is “rss” within the XML document.
Line 13 replaces the nested <uiexml:child> and <uiexml:text> tags of the previous example with a single <uiexml:child-text> tag. This emits the text of the first child element of the context whose tag is “title”. The tag on line 12 adds a link using another <uiexml:child-text> tag. The context for this tag is identical to the context of the tag on line 13. Both tags retrieve the text from child elements of the current news item.
This example uses the same information as the previous example, but generates UJML instead of HTML. It also introduces two new tags: <uiexml:descendant> and <uiexml:child-count>.
01: <%@ page contentType="text/xml;charset=UTF-8"%><?xml version="1.0" encoding="UTF-8"?>
02: <!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml-1.4.dtd">
03: <%@ taglib uri="uiexml-taglib" prefix="uiexml"%>
04: <% int index = 0; %>
05: <ujml>
06: <partition>
07: <functions>
08: <function name="beginItems" type="boolean" access="import">
09: <parameters>
10: <var name="count" type="int"/>
11: </parameters>
12: </function>
13: <function name="addItem" type="void" access="import">
14: <parameters>
15: <var name="index" type="int"/>
16: <var name="title" type="string"/>
17: <var name="url" type="string"/>
18: </parameters>
19: </function>
20: <function name="endItems" type="void" access="import"/>
21: </functions>
22: <script>
23: <uiexml:document url="http://rss.com.com/2547-12-0-20.xml">
24: <uiexml:descendant path="rss/channel">
25: if (beginItems(<uiexml:child-count tag="item"/>))
26: {
27: <uiexml:children tag="item">
28: addItem(
29: <%= index++ %>,
30: "<![CDATA[<uiexml:child-text tag='title'/>]]>",
31: "<![CDATA[<uiexml:child-text tag='link'/>]]>");
32: </uiexml:children>
33: endItems();
34: }
35: </uiexml:descendant>
36: </uiexml:document>
37: </script>
38: </partition>
39: </ujml>
Line 1 uses the JSP page directive to tell the JSP container that this page will be generating XML and that it should encode characters as UTF-8 bytes. Although it is hard to tell from the formatting, it is important that there be no characters between the end of this page directive and the XML document declaration. It is also critical that the XML document type declaration appear immediately following the document declaration.
Line 24 uses the <uiexml:descendant> tag to specify the first “channel” element within the first “rss” element of the document. This breaks the previous use of the <uiexml:descendants> tag into two separate tags, the second one being a <uiexml:children> tag. This allows the use of the <uiexml:child-count> tag (described below) and the <uiexml:children> tag to share a common context.
Line 25 uses the <uiexml:child-count> tag to get the number of child elements of the channel element whose tag is “item”. This allows the linking UJML application to properly initialize its internal data structures for the given number of items.
As mentioned earlier, line 27 uses the <uiexml:children> tag to set the context of lines 28 through 31 to the set of child elements of the current context whose tag is “item”.
This section describes each tag available in the UIEvolution XML Tag Library in detail. The purpose for each tag, its syntax, its allowable attributes, whether it creates a value or a context, and its expected context will be described.
Type: value
Context: element
Attributes:
name required Specifies the name of the attribute whose value is desired.
default optional Specifies the default value to use if the attribute is not found on the context element.
Description: This tag is used to emit the value of a given attribute of an element into the output of the page.
Type: context
Context: document or element
Attributes:
tag optional The tag of the child element to select.
attribute optional An attribute of the child element to select.
value optional An attribute value of the child element to select.
Description: This tag selects the first child element of the current context that meets the requirements given by the attributes of this tag.
If no attributes are specified, the first child of the context will be selected.
If a tag is specified, the first child with the given tag will be selected.
If the attribute and value attributes are specified, the first child with a matching attribute name/value pair will be selected.
If all three attributes are given, the first child with the given tag and attribute name/value pair will be selected.
Type: value
Context: document or element
Attributes:
tag optional The tag of the child element to select.
attribute optional An attribute of the child element to select.
value optional An attribute value of the child element to select.
Description: This tag emits the number of child elements of the current context meeting the given requirements into the output of this page.
The child elements counted are selected based on the same criteria as described for the <uiexml:child> tag with the exception that all child elements matching the requirements are included, not just the first.
Type: value
Context: document or element
Attributes:
tag optional The tag of the child element to select.
attribute optional An attribute of the child element to select.
value optional An attribute value of the child element to select.
default optional The value to use if a matching element is not found or if the matching element has no text.
Description: This tag emits the text found on a child element of the current context. The element selection criteria given by the attributes of this tag are the same as those for the <uiexml:child> element.
Type: context
Context: document or element
Attributes:
tag optional The tag of the child element to select.
attribute optional An attribute of the child element to select.
value optional An attribute value of the child element to select.
first optional The zero-based index of the first element to select.
count optional The number of elements to select.
Description: This tag selects all children of the current context that match the requirements given by the tag, attribute, and value attributes. In addition, the children selected from the matching set can be limited by first index and total count, allowing paging behavior within a large set of elements.
The element selection criteria given by the attributes of this tag are the same as those for the <uiexml:child-count> tag. From the selected set, the “first” and “count” attributes can be used to select a range of those elements.
Type: context
Context: document or element
Attributes:
path required The path of the element to select.
Description: This tag selects a single element whose tag path matches that given. It is the equivalent to multiple, nested <uiexml:child> tags with each tag specifying a single component of the path using its “tag” attribute.
Type: context
Context: document or element
Attributes:
path required The path of the elements to select.
first optional The zero-based index of the first element to select.
count optional The number of elements to select.
Description: This tag is similar to the <uiexml:descendant> tag except that it selects all children of the second to last component of the path whose tag matches the last component of the path. It is equivalent to a <uiexml:children> tag nested within a <uiexml:descendant> tag.
Type: context
Context: none
Attributes:
url required The URL of the documents to parse.
Description: This tag provides an initial context for all other tags. The document specified by the “url” attribute is parsed and made available to all XML tags nested within this tag.
Type: context
Context: any
Attributes:
select required The select expression for all documents to select.
Description: This tag selects a set of nodes based on the given select expression. The expression is loosely based on the XPath specification, allowing selection of children, parent, or attribute nodes.
Currently four of the XPath axes are supported in the select expression: child, parent, self, and attribute. For each of these axes, only the abbreviated syntax is supported. The syntax for each is shown below.
|
Axis |
Syntax |
|
Child |
child-tag |
|
Parent |
.. |
|
Self |
. |
|
Attribute |
@attribute-name |
If only the child axis is used in the select expression, this tag behaves similarly to the <uiexml:descendants> tag, with one important exception. Where the <uiexml:descendants> tag searches for children of the first descendent specified by all but the last component of the path, the <uiexml:for-each> tag will select all children of all descendants specified by all but the last component of the select expression.
Type: value
Context: element
Description: This tag emits the tag of the enclosing element context.
Type: value
Context: element
Attributes:
default optional Specifies the default value to use no text is available.
Description: This tag emits the text of the enclosing element context.
Type: value
Context: element or attribute
Description: This tag emits the value of the enclosing context. If the context is an element, its text is used. If the context is an attribute, its value is used.