XRL Rendering

Home > Books > Architect's Guide to NetKernel > Example Applications > 1060 Forum Guide > XRL Rendering

Deconstructing the XRL Renderer

In the previous section we saw that the rendering of a topic view to XHTML was treated as a black-box. In this section we'll explore how XRL templating is used to compose the XHTML. But before reading on, we suggest you should take the time to read the XRL by Example guide, which provides a step-by-step introduction to XRL's recursive XML composition model.

Welcome back! To recap: in the previous section we deconstructed the topic channel and saw that it consists of a mapping to a beanshell script which sources topic metadata and entries. It then hands off the rendering to the XRL mapper with a request for the topic rendering service with URI ffcpl:/forum/render/topic/. This is done with the following request to the xrl mapper...


//Hand off to XRL mapper to compose the view
req=context.createSubRequest();
req.setURI("active:mapper");
req.addArgument("operand", "ffcpl:/forum/render/topic/");
req.addArgument("operator", "ffcpl:/links.xml");
req.addArgument("entries", entries);
req.addArgument("meta", meta);
req.addArgument("param", param);
result=context.issueSubRequest(req);

This is a request for the mapper to invoke the service "ffcpl:/forum/render/topic/", specified by the operand, and to use the declarative links resource "ffcpl:/links.xml", supplied as the operator, to locate the URI of the service implementation. The script variables entries, meta and param are also passed as named arguments (using the same names) to be relayed to the implementing service as required. This is an example of the mapper pattern.

At this point we need to highlight an interesting subtlety. The mapper is instructed to resolve the service using the links located at ffcpl:/links.xml. However when we look at the module.xml definition we find that the ffcpl:/links.xml is actually dynamically implemented by a service call to a script...

<mapping>
  <!--Dynamically generate links.xml-->
  <rewrite>
    <match>ffcpl:/links.xml</match>
    <to>active:beanshell+operator@ffcpl:/stylemapping/createLinks.bsh</to>
  </rewrite>
        ...

</mapping>

Earlier we showed that the forum-web module uses a pluggable forum-style module to provide styling and image resources - the createLinks.bsh script combines the local static links located in ffcpl:/primary_links.xml with some additional styling links ffcpl:/style/links.xml provided from the style module. But note that the mapper doesn't need to be complicated by this relationship, it requests a single resource that just happens to be dynamically implemented - this is a very flexible decoupling and is an example of the dynamic state pattern.

We'll look further into the relationship between the forum-web and forum-style modules a little later, for now we should recognize that the important structural links are contained in the ffcpl:/primary_links.xml. If you inspect this file you'll see the following link definitions...

<links basepath="ffcpl:/forum/">
    ...
    
  <link>
    <name>topic</name>
    <ext>/render/topic/</ext>
    <int>active:xrl-html-tolerant
            +template@xrl:template_master+content@xrl:entry-list-renderer</int>
    <args>links,param,meta,entries</args>
  </link>
  <link>
    <name>entry-list-renderer</name>
    <int>active:dpml
            +operand@ffcpl:/main/forum/topic/render/entry-list-renderer.idoc</int>
    <args>links,param,meta,entries</args>
  </link>
    ...

</links>

From your reading of the XRL guide you will understand that the ffcpl:/forum/render/topic/ URI is matched to the link named topic and that the XRL mapper will request the active URI specified by the <int> tag. Which is a request to the XRL runtime to populate a template with content suppled from another link 'xrl:entry-list-renderer' (xrl:template_master is the master template and is dynamically supplied from the style module - more on this shortly).

The second link shown is the implementation of xrl:entry-list-renderer and in this case links to a URI to execute the DPML script ffcpl:/main/forum/topic/render/entry-list-renderer.idoc. Notice that with both these links the mapper is instructed to pass through the links, param, meta and entries arguments it received in the external mapper request from the topic-viewer.bsh.

So the big picture is that the topic-viewer.bsh request to the mapper is resolved to an xrl recursion starting with a master template and populated with content from the execution of a DPML rendering script. Let's look at the DPML script...

<idoc>
  <seq>
    <instr>
      <type>xslt</type>
      <operand>this:param:entries</operand>
      <param>this:param:param</param>
      <meta>this:param:meta</meta>
      <operator>ffcpl:/style/topic/style-entry-list.xsl</operator>
      <target>this:response</target>
    </instr>
  </seq>
</idoc>

This script has just a single instruction to perform an XSLT transformation of the entries argument with the XSL style ffcpl:/style/topic/style-entry-list.xsl. The param and meta arguments are supplied as parameters to the XSL transformation. The result is an XHTML block containing the styled entries which is included into the master template by the xrl recursion, the result of which is ultimately returned as the response of 'black-box' mapper request made in the topic-viewer.bsh.