An XPathScript Mini-Reference

Code is separated from output in XPathScript using the <% %> delimiters.

Perl expression results can be sent to the browser either using print() if inside a <% %> section, or via <%= code %>.

The following XPath functions are imported for your use:

• findnodes($path, [$context])
• findvalue($path, [$context])
• findnodes_as_string($path, [$context])
• apply_templates( $path, [$context])
• apply_templates( @nodes )
• import_template( $uri )

The first three methods are documented more completely in the XML::XPath manual pages.

Apply templates examines the contents of the local $t hash reference for elements names. For example, when encountering a <foo> element via apply_templates, XPathScript will try to find a transformation hash in the key $t->{'foo'}.

Import template can be used to pull in an external XPathScript template file. $uri should be a path to the stylesheet to be included. The function returns an anonymous subroutine that when executed will run the stylesheet. The anonymous subroutine takes two arguments, which makes it ideal to plug into a testcode entry, for example:

$t->{BODY}{testcode} = import_template("/xps/bodystyle.xps");

If you want to include a stylesheet anyway (not as part of a testcode setup), just write it as normal, and include a line like this in the parent stylesheet:

import_template("/xps/bodystyle.xps")->();

The value in $t->{'foo'} above is a hash reference with the following optional keys:

• pre
• post
• prechildren
• postchildren
• prechild
• postchild
• showtag
• testcode

If a value is not found in $t for the current element, then the element is output verbatim, and apply_templates performed on all its children. Except in the case where a $t->{'*'} value exists, which is a "catchall" transformation specification. This might be a useful place to add some testcode to output a warning to the error log.

If a value is found in $t for the current element then the tag itself is not displayed unless $t->{<element_name>}{showtag} is set to a true value.

testcode is a reference to a subroutine (often constructed as an anonymous subroutine). The subroutine is called with two parameters: The current node and a localised hash reference to store new transformations for this node and this node only. The return value from this subroutine must be one of:

• 1 - process this node and all children
• -1 - process this node but not the children of this node
• 0 - do not process this node or its children
• 'string' - any string (other than "1", "0" or "-1") is equivalent to 1, except rather than processing the node's children, it processes the nodes found by executing findnodes('string', $node) where $node is the current node. Obviously 'string' has to be a valid XPath expression.

XPathScript stylesheets can be modularised using SSI #include directives. The code in #included files is added verbatim into the current code at the position of the include. This allows you to use this fact to override defaults (as we saw in the first example where the template for ulink is overridden).