XRL Guide

Guide to using XML Reference Linker System

XRL XML Reference Linker

XRL is an XML pull runtime for combining XML as a recursive series of pulled include evaluations and URI translations. It consists of a set of accessors that provide a mechanism for flexible creation and serving of static or dynamic content.

It consists of three distinct parts:

mapper which maps an external uri space to an internal uri space. This allows an abitrary URI space such as a website map to be mapped into resources that are stored or generated in a different structure.
xrl which provides a convenient template filling and link resolution operations as well as some convenient low level document manipulation functions. It has the concept of templates and content.
mapper-export which exports all external links in a links document to an external location. This is useful for deploying content on a static web server.

It is implemented using the following accessors: mapper, xrl and mapper-export.

XRL: XrefLinker

Intro

An accessor to perform inclusion of named links, resolution of named links and substitution of fragments.

The intention is to provide a single accessor solution to dynamic content publishing with the problems of recursive template filling, resolution of named external links and specification of title/header/footer fields.

Interface

active:xrl [+template@xrl:template_link_name] [+content@xrl:content_link_name] +links@link_uri [+param@param_uri] +[cookie@cookie_uri]
active:xrl+template@mysite_template_link+content@homepage

Link Document


<links @basepath="ffcpl:/mybase/">
	<link>
		<name>link_name</name>
		<ext>external_uri</ext>
		<int>internal_uri</int>
		<args>param,links,cookie</args>
	</link>
</links>

name is the link name that will be exposed as the uri xrl:link_name.

ext is an external (internet domain) uri which may be relative to the site for the link, if no ext is defined then the link is purely for internal use.

int is an internal (resolved by urii in the sites context) for an internal resource to provide content for this link.

args defines hints as to which arguments to pass to request for the uri if they are available.

URIs may be xrl: scheme in which case they should be recursively evaluated.

Template

The following tags in the namespace xmlns:xrl=”http://1060.org/xrl” will be processed in the template.

tag	description
<xrl:include href=”uri”/>	If the uri is xrl: resolve the named link. Then request the URI passing hinted args, then substitute content into template.
<xrl:include href=”uri”> <fragment/> </xrl:include>	Same as above but param argument will be replaced with fragment inside xrl:include tag.
<a href=”xrl:name” xrl:resolve=”href”>click</a>	If the uri is xrl: resolve the named link. Then substitute the URI into the referenced attribute.
<td style=”background:url('[[xrl:image]]')” xrl:resolve=”style”>hello</td>	Substitute all [[xrl:****]] in the xrl:resolve attribute with an external URI resolved from the link.
<xrl:eval xpath="/html/h1/text()" fallback="'not-found'"/>	Evaluate the given xpath expression to a string and substitute this tag with a the text. If this xpath cannot be evaluated try an evaluate the optional fallback xpath expression. If this fails substitute a zero length string.
<xrl:eval xpath="/html/h1/text()" attribute="href"/>	Evaluate the given xpath expression to a string and add an attribute to the parent element the given attribute name and evaluated value.
<xrl:include xpath=”/html/h1”/>	Evaluate the given xpath expression to a fragment and substitute this tag with the fragment. Copy and pastes fragments around a document.
<xrl:include href=”xrl:content”/>	xrl:content is a special link uri for the content arg passed into the request.

The processing is defined by the following steps:

process all <xrl:include> elements in document order
repeat step one until there are no more <xrl:include> elements
resolve all external links @xrl:resolve
perform all xpath evaluations xrl:include[@xpath] and xrl:eval[@xpath]

Example

template.xml

<html xmlns:xrl="http://1060.org/xrl">
	<head>
		<title><xrl:eval xpath="/html/body/h1"/></title>
		<link href="xrl:1060style" xrl:resolve="href"/>
	</head>
	<body>
		<xrl:include xpath="//img[@name='poweredby']"/>
		<table>
			<tr>
				<td><xrl:include href="xrl:content"/></td>
			</tr>
			<tr>
				<td><xrl:include href="xrl:footer"/></td>
			</tr>
		</table>
	</body>
</html>

links.xml

<links>
	<!--internal links -->
	<link><name>template</name><int>ffcpl:/content/template.xml</int></link>
	<link><name>dynamic</name> <int> active:dpml+operand@ffcpl:/content/dynamic.idoc</int>
	<args>param</args></link>

	<!--published links -->
	<link><name>index</name><ext>/</ext>
	<int>active:xrl-html+template@xrl:template+content@xrl:content1</int>
	<args>links,param</args></link>
	<link><ext>/index.html</ext><int>xrl:index</int></link>

	<!-- external links -->
	<link><name>google</name><ext>http://www.google.com</ext></link>
</links>

XRL: Mapper

Intro

An accessor to take a request and map it to a diferent URI based on a links.xml specification.

Interface

active:mapper+operand@request_uri+@operator@link_uri [+param@param_uri] [+cookie@cookie_uri]

Operation

All incoming requests have their operand URI path looked up as an external uri in the links document and resolved to an internal uri. This can either be a direct lookup or via a chain of named links.

If an operand path cannot be found the mapper attempts to resolve the link xrl:404 and passes a parameter doc of the form:

<error>
<page>operand_path</page>
</error>

If the link xrl:404 cannot be found an exception is thrown by the accessor.

If an error occurs in requesting an internal uri the mapper attempts to resolve the link xrl:500 and passes a parameter doc of the form:

<error>
<page>operand_path</page>
<ex>netkernel_exception_fragment</ex>
</error>

If the link xrl:500 cannot be found an exception is thrown by the accessor.

If an optional <args> element is found in the links doc for an internal request then the specified args are sent to that request.

1060^® NetKernel^TM Documentation
(C) 2003-2004 1060 Research Limited

Send Feedback