Example 1. Deciding the SportPage Page-Handler

A request URI is scanned from the end to the beginning looking for a matching Java page-handler class:

http://cbc.ca/olympics/bio/snowboarding/deadhead/jim.bo

this url gets scanned for DeadheadPageHandler, then SnowboardingPageHandler and finally settles on BioPageHandler. This PageHandler is dynamically loaded and given the current page context (a Map of $varname=object pairs) which the handler can freely modify before the page starts to render.

The most common use of special page handlers is to restructure the page layout by changing the context variables specifying the sidebars, pages or any other context variables.

The page handler may also add other variables, for example, a BioPageHandler might take the $path as an XML document and pre-loads it as a globally accessible JDOM object that the /bio page templates can share.

The following code sample shows how a global $dom variable bound to a shared JDOMFile object might be used in a template:

#set ($root = $dom.rootElement)
#set ($sp = $root.getChild("sport"))
#set ($sport = $sp.getAttribute("name").value)
#set ($athlete = $sp.getChild("athlete"))

#set ($ch = $athlete.getChild("career_highlights"))
#set ($chs= $ch.getChildren("point"))
#foreach ($point in $chs)
	   #show($point)
#end

In practice, however, this method is not as useful as it seems and it locks the types of content to specific topic areas. A more flexible method is to define dot-variable beans, which can be specified globally or per-topic, and then use these beans to access documents by passing in the $path pathinfo. The above example would be modified only slightly, by inserting the following code at the top:

#set ($dom = $xml.dom( $path ))

The javabean dot-variables *.bean lets you map any java beans to variables; in this case, $xml has been bound to the DOMFileFactory which provide the means to fetch documents from the $path. If the javabean uses data caching and/or is a singleton (or stashes itself in the application properties), there is very little overhead in using this method.