XSLT rendering engine

From alfrescowiki

Contents 1 Overview 2 3.3 2.1 Design 2.2 The model passed to the template 2.3 Functions made available to the template 2.3.1 alf:parseXMLDocument 2.3.2 alf:parseXMLDocuments 2.3.3 alf:encodeQuotes 2.4 Making your own functions available

Overview

The XSLT Rendering Engine is designed to allow new renditions of XML content nodes to be created by processing them through an XSL transformation. It was introduced in version 3.3 as one of the first rendering engines available to the core rendition service. This rendering engine has a name of "xsltRenderingEngine" and is represented by the class org.alfresco.repo.rendition.executer.XSLTRenderingEngine

3.3

Design

Like all rendering engines, the XSLT Rendering Engine generates one rendition node from a given source node. It applies an XSL transformation to the source node, and parameters can be supplied to configure the transformation. The first parameters to describe are those that can be used to specify the XSLT itself. All of these three parameters are optional, but one of them must be set for the engine to work:

• PARAM_TEMPLATE: (String) the actual XSLT itself (not a reference)
• PARAM_TEMPLATE_NODE: (NodeRef) the node ref whose cm:content property contains the XSLT
• PARAM_TEMPLATE_PATH: (String) the path to the node whose cm:content property contains the XSLT. The display path is used for this parameter. That is to say "/Company Home/..." as opposed to "/app:company_home/...".

These constants are all defined in the BaseTemplateRenderingEngine class from which both the XSLT Rendering Engine and the Freemarker Rendering Engine are derived. As mentioned earlier, one of them must be specified in all rendering definitions that make use of the XSLT Rendering Engine, and the order in which they are evaluated is the order in which they appear in the list above.

The only other parameter that is specific to templating rendering engines (such as the XSLT Rendering Engine) is PARAM_MODEL. This parameter is a Map object (implementing java.util.Map) that contains entries whose keys are String objects and whose values are Serializable objects. These entries are passed on to the template service as part of the model that is combined with the source node and template to produce the rendition.

The model passed to the template

The model passed by the XSLT Rendering Engine to the template service contains the following entries (as well as any that are provided by PARAM_MODEL):

• alf:date : the current date/time as a java.util.Date object
• alf:source_file_name : the name of the source node (as defined by its cm:name property)
• alf:source_path : the path to the source node
• alf:parent_path : the path to the parent node of the source node
• alf:encodeQuotes : a function that can be called from the XSLT to encode invalid HTML characters
• alf:parseXMLDocument : a function that can be called from the XSLT to read and parse an XML document from the repository
• alf:parseXMLDocuments : a function that can be called from the XSLT to read and parse a collection of XML documents from the repository

Model entries that are provided by the rendition definition via the PARAM_MODEL parameter are provided to the template with no namespace qualification.

Functions made available to the template

As listed above, there are three functions that are made available to the XSLT when rendering through the XSLT Rendering Engine. These are described a little more fully here, along with guidance as to how to add your own functions.

alf:parseXMLDocument

This function parses one XML content node and returns its root element as an object of type org.w3c.dom.Element. It expects one String argument to be passed to it that is the path to the XML content node relative to the folder that contains the source node. That is to say that if the source node is "/Company Home/My XML files/source.xml" then calling alf:parseXMLDocument('other.xml') will attempt to load the node at "/Company Home/My XML files/other.xml".

Here's an example of a small XSLT that uses alf:parseXMLDocument:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
  <xsl:output method="text" />
  <xsl:preserve-space elements="*" />
  <xsl:variable name="other" select="alf:parseXMLDocument('other.xml')" />
  <xsl:template match="/">
    <xsl:for-each select="$other/food">
      <xsl:value-of select="name"/>
    </xsl:for-each>
  </xsl:template>
</xsl:stylesheet>

alf:parseXMLDocuments

This function parses a collection of XML content nodes and returns them in all combined into a single XML document with a root element of alf:file_list and with the root element of each parsed node forming a sub-element of alf:file_list. Each of these sub-elements has an attribute named alf:file_name added to it that contains the name of the corresponding node.

The function defines two String arguments. The first argument (mandatory) is a type name (such as "cm:content" or "myapp:NewsArticle") that restricts the type of node that the function parses. The second argument (optional) is a path relative to the folder that contains the source node. This path determines the folder that the function will look in to find the XML nodes and defaults to the folder holding the source node.

Here's a quick example:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
  <xsl:output method="text" />
  <xsl:preserve-space elements="*" />
  <xsl:variable name="all_docs" select="alf:parseXMLDocuments('cm:content')" />
  <xsl:template match="/">
    <xsl:for-each select="$all_docs//food">
      <xsl:value-of select="name"/>
    </xsl:for-each>
  </xsl:template>
</xsl:stylesheet>

alf:encodeQuotes

A function that converts invalid HTML characters into the appropriate entities. For example:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
  <xsl:output method="html" encoding="UTF-8" indent="yes" doc-type-public="-//W3C//DTD XHTML 1.0 Transitional//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" />
  <xsl:preserve-space elements="*" />
  <xsl:template match="/">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <body>
    <xsl:for-each select="food/name"
      <xsl:variable name="food_name"><xsl:value-of select="normalize-space(.)" disable-output-escaping="yes" /></xsl:variable>
      <xsl:value-of select="alf:encodeQuotes($food_name)" disable-output-escaping="yes" /><br/>
    </xsl:for-each>
  </body>
</html>

  </xsl:template>
</xsl:stylesheet>

Making your own functions available

Functions that are made available to the XSLT are presented in the template model as objects implementing the interface org.alfresco.repo.template.TemplateProcessorMethod. This interface describes just one operation:

Object exec(Object[] arguments) throws Exception;

You can see examples of this being used in the class org.alfresco.repo.rendition.executer.XSLTRenderingEngine. In that class, the TemplateProcessorMethod objects passed into the model are wrapping methods in the class org.alfresco.repo.rendition.executer.XSLTFunctions.

If you want to pass your own function into the model then add it (inside a TemplateProcessorMethod wrapper) into a Map<String,Serializable> object and store this map on the rendition definition as PARAM_MODEL.