Thu Aug 11 22:39:58 2005

Using XSP in AxKit

Abstract

This article covers the XSP technology within AxKit, how to get started using XSP to create dynamic pages, and a full guide to the XSP syntax.

Introduction

XSP is a server-side technology for embedding code into XML. It belongs to the same family of products as ASP and JSP. However XSP focuses completely on XML, and contains methods for generating XML that make life for the XML programmer easier. XSP is designed to work in the early stages of the XML processing pipeline, often as the very first stage in the processing pipeline. Generally the output from XSP goes on to further stage processing to deliver HTML or WAP. XSP also has powerful database tools that deliver their output in XML for further manipulation.

A simple XSP example that generates the current time looks like this:

<xsp:page xmlns:xsp="http://apache.org/xsp/core/v1"
	xmlns="uri://axkit.org/NS/MyHomePage"
	language="Perl">
	<page>
		<body>
			<heading>Hello World</heading>
			It is now: <xsp:expr>scalar localtime</xsp:expr>
		</body>
	</page>
</xsp:page>

And the output from that example is:

<page xmlns="uri://axkit.org/NS/MyHomePage">
	<body>
		<heading>Hello World</heading>
		It is now: Sat Jun 24 10:46:51 2000
	</body>
</page>

While this isn't going to be displayable by any current browser (unless we're talking about client side XSLT or even CSS), AxKit pipes this into the next stage of transformation, which is likely to be an XSLT processor, to generate HTML or any other format.

Using the XSP constructs, like <xsp:expr> we can build up complex rules and code structures to generate the desired output. XSP includes several tags for making life easier for generating XML, as we'll see later.

The Elements of XSP

We've already mentioned that XSP includes tags for generating XML, and it should be noted that the above <xsp:expr> does not generate text, but a DOM text node. In this section we'll see what tags XSP offers to us, and later we'll see how to put them all together.

First though, its important to know a little bit about how XSP works behind the scenes withing AxKit. Astute readers will have noted that the <xsp:page> tag included a language="Perl" attribute. This is because XSP is language independent. While AxKit only implements XSP with the Perl language, Cocoon has implemented support for Java and Javascript, and other languages are coming online with the Cocoon project soon.

When AxKit parses the XSP page it generates a Perl class - an object oriented Perl module. This class can be considered to have three main sections:

structure - this currently only defines libraries that your XSP code might use, although it is left open for other structural items
logic - this section is for any logic in addition to that which you wish to embed directly within the output. This generally includes function definitions and global variables (although see for some important information on global variables)
content - the main section of XSP occurs as soon as the XSP parser sees a non-XSP tag (which is called the "User root" tag).

A breakdown of how this might look to a perl programmer is as follows:

package MyModule;

# begin structure
use MyLib;
# end structure

# begin logic
sub foo {
	return "bar";
}
# end logic

# begin content
sub handler {
	# generate DOM tree of content output
	...
}
# end content
1;

When an XSP page is executed, assuming the code is already compiled, AxKit attempts to execute the handler() function.

Now that we know what sort of code is behind the execution of XSP, lets get deeper into those sections.

Structure

Structure tags may appear only between the root <xsp:page> tag and the user root tag. The syntax of the structure tag is:

<xsp:structure>
	<xsp:include>MyLib</xsp:include>
</xsp:structure>

This adds the following to the structure section of the compiled class:

use MyLib;

Currently <xsp:include> is the only tag provided for use within the structure section.

Logic

The logic section is freeform, and should generally be used along with an accompanying <![CDATA[...]]> declaration to ensure that your code is not treated as XML. Note that unlike some languages, perl may be particularly prone to having the string "]]>" somewhere in the code, so be aware of that as you work in CDATA sections. A simple solution is to change that to "]] >" - note the extra space.

An example of a logic section might be the definition of a function for providing the current time:

<xsp:structure>
	<xsp:include>Time::Object</xsp:include>
</xsp:structure>

<xsp:logic><![CDATA[
sub mytime {
	my ($time) = @_;
	$time ||= time;
	return Time::Object->new($time);
}
]]></xsp:logic>

Content

The content section consists of automatically generated code based on the non-xsp tags in the document, along with code that has been generated based on the xsp tags.

Currently XSP is DOM based (there are plans to make a SAX based XSP for the obvious performance benefits, but that hasn't been realised yet), and as such for each non-xsp entity in the XML resource, the XSP parser generates code that will create a DOM node. When it sees a tag it generates code to make an element node, when it sees text it generates code to make a text node, and so on. The idea though is not to worry about the code that the XSP parser is generating, and focus on the output that you want.

Since the content section is where most of the work and most of the important parts of your code will occur, we've reserved a whole section of this document to talk about it.

XSP's XML building tags, or "the Content section"

Everything in XSP works around namespaces, so be sure you understand them before trying to start working with XSP. A good place to learn about namespaces is XML.com, where they have some excellent links to namespaces resources, and some good articles.

As soon as XSP sees an element that does not belong to the XSP namespace it knows to start the "content section". This is the main part of the code that generates XML nodes for passing to the next processing stage. Every node prior to the user root node is special to XSP (because by definition, they are part of the XSP namespace). It is also worth noting here that an actual <xsp:page> root element is not a requirement of XSP, however without it there's no way to create logic or structure sections.

Generating Elements and Attributes

Any non XSP tags are generally passed on to the next processing stage verbatim. However it is possible to use logic to determine whether or not certain tags appear:

<xsp:logic>
	if (somecondition()) {
<xsp:content>
		<true_tag/>
</xsp:content>
	} else {
<xsp:content>
		<false_tag/>
</xsp:content>
	}
</xsp:logic>

This example is based on the familiar concept that was brought to use by ASP and similar server side scripting languages, where we must break out of the code section in order to send tags to the browser. The <xsp:content> tag allows us to temporarily break out of the code section that is provided by <xsp:logic>. Note that <xsp:logic> is the same tag as we used outside of the user root element to provide class level logic.

This is rather verbose, so there's another way to achieve the same effect, and this is using the XSP element generator tags:

<xsp:logic>
	if (somecondition()) {
		<xsp:element name="true_tag"/>
	} else {
		<xsp:element name="false_tag"/>
	}
</xsp:logic>

Finally we can get even easier. Because the XML parser knows the difference between tags and text, we can simply use the tag on its own:

<xsp:logic>
        if (somecondition()) {
                <true_tag/>
        } else {
                <false_tag/>
        }
</xsp:logic>

What's interesting about this is that we don't actually need to break out of the "code" mode (the <xsp:content> tag here) to generate the XML tag - the XML parser actually does the hard work for us of figuring out what is a tag and what is Perl. Provided that you are aware of the limitations of this, such as not being able to use a CDATA section when we want to do this, and being aware that < and & signs need to be escaped, it is a very powerful concept.

Building attributes is equally simple:

<xsp:content>
	if (somecondition()) {
		<xsp:element name="true_tag">
			<xsp:attribute name="myattr">My Value</xsp:attribute>
		</xsp:element>
	} else {
		<xsp:element name="false_tag">
			<xsp:attribute name="myattr">Other Value</xsp:attribute>
		</xsp:element>
	}
</xsp:content>

Note how the tag to generate the attribute occurs as a child of the tag that creates the element.

Putting this all together now, given that somecondition() returns true, the resulting output is:

<true_tag myattr="My Value">
</true_tag>

Not particularly interesting, until we realise that this is just one stage in the processing pipeline, and the next stage is probably an XSLT stylesheet that transforms <true_tag> into something with meaning to the browser, such as a table or text of some sort.

Generating comments, text and processing instructions

Generation of nodes is not limited to elements (and attributes). We can use the same techniques to generate comments, text and processing instructions. The benefits of this seem dubious, until you realise that again we can generate these things without breaking out of the "code" section, and just use XML tags.

The tags to generate these types of nodes follow the same pattern as generating elements, so I'll cover this with a single example:

<xsp:content>
	# some perl code ...
	<xsp:text>Hello World</xsp:text>
	<xsp:comment>Why am I here?</xsp:comment>
	<xsp:pi target="process-me">With some data</xsp:pi>
</xsp:content>

The result from the above is:

Hello World
<!--Why am I here?-->
<?process-me With some data?>

Caching

You can cache XSP pages at the dynamic level only. This means you can cache the output of your XSP script, but you cannot cache the output of the following XSLT stages. We'll work on that though :-)

By default the output of XSP pages is not cached for obvious reasons. To turn on caching you need to implement the has_changed() method in your XSP page. This class method is passed an mtime in seconds since the epoch, and must return true/false depending on whether it has changed since that epoch.

<xsp:page xmlns:xsp="http://apache.org/xsp/core/v1">
<xsp:logic>
sub has_changed {
    my ($class, $mtime) = @_;
    # logic to determine if we changed since $mtime
    return 1; # this is the default. Return 0 for cached data
}
...

Now that is rather blanket caching, as the same page with different parameters will return identical cache results. In order to change that we implement the cache_params method and return a string containing the parameters that we are caching. For example if we cache based on everything in the querystring:

<xsp:page xmlns:xsp="http://apache.org/xsp/core/v1">
<xsp:logic>
# always cache, rely on cache_params to determine whether cache is present.
sub has_changed { 0 }
sub cache_params {
    my ($class, $r, $cgi) = @_;
    # args contains the unparsed querystring
    return $r->args;
}
...

This is the basics of XSP caching. To do anything more complicated you could create your own Apache::AxKit::Cache object and output that using <util:include-expr> from the AxKit::XSP::Utils tag library. But that is beyond the scope of this document - ask about it on the mailing list.

Real World Example

Conclusion

We've seen the capabilities of XML Server Pages, and we've seen a simple real world example, however we've only really touched upon the power of XSP. The real power actually comes in when we get into taglibs. Taglibs allow us to design custom tags that we can insert into our pages, that provide us with extended functionality. This allows us to finally reach towards the ubiquitous goal of having developers work on the taglibs, and designers work on XSP's by inserting your company's custom tags.

Taglibs provide the real power of XSP, and yet their implementation is not rocket science, in fact anyone who has already been reading other AxKit documentation will be intimately familiar with the tools to generate taglibs: stylesheets. We use stylesheets to build taglibs by developing stylesheets that transform our custom tags, and just our custom tags into valid XSP code, we can leverage our current development tools to build dynamic XML applications. Please read the section on the SQL taglib to see how we can build XSP's that connect to relational databases.

Edit This Page / Show Page History /