WCM Forms Rendering

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

{{AVMWarning}}
AVM

Table of Contents

• 1 Introduction


• 2 Example
  
  
  
  • 2.1 Rendering Template 1 - Freemarker
  
  
  • 2.2 Rendering Template 2 - XSL
  
  


• 3 Variables and Functions exposed to Rendering Engine


• 4 Template Inclusion


• 5 More Freemarker Rendering Template Examples
  
  
  
  • 5.1 Example - Using qualified elements namespaces
  
  
  • 5.2 Example - Using NameSpace Prefixes
  
  
  • 5.3 Example - Using Variable Assignment
  
  

Introduction

Once the content data is captured (via XForms) as XML instance documents, it needs to be rendered to site visitors in a human-readable format (typically HTML).  This transformation can be done at request time (by converting the XML to HTML on the fly) or at authoring time, via the use of 'renditioning templates'.

Alfresco provides two renditioning engine implementations, one which uses XSL templates, and the other freemarker.  In both cases, the form instance data (XML) is passed to the template to be rendered.  The following are simple examples of how a simple XML document can be processed by both FreeMarker and XSL.

Example

Given the XML schema:

<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
           elementFormDefault='qualified'>
  <xs:element name='simple'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='string' type='xs:normalizedString'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

The user will open an XForm, and fill in one string.  The resultant XML is as follows:

 <simple>
   <string>hello!</string>
 </simple>

Rendering Template 1 - Freemarker

You can now use the following FreeMarker rendering engine template:

 
 
   
   ${simple.string}
   
 

Rendering Template 2 - XSL

Alternatively, you could use an XSL rendering engine template:

 <xsl:stylesheet version='1'
                 xmlns:xhtml='http://www.w3.org/1999/xhtml'
                 xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
                 exclude-result-prefixes='xhtml'>
   <xsl:output method='html' indent='yes' encoding='UTF-8' version='4.01'
               doctype-public='-//W3C//DTD HTML 4.01 Transitional//EN'
               doctype-system='http://www.w3.org/TR/html4/loose.dtd'/>
   <xsl:template match='/'>
     <xhtml:html>
       <xhtml:body>
         <xsl:value-of select='/simple/string'/>
       </xhtml:body>
     </xhtml:html>
   </xsl:template>
 </xsl:stylesheet>

Resulting HTML output rendition (using either FreeMarker or XSL):

  
  hello!
  

Variables and Functions exposed to Rendering Engine

Alfresco makes a set of helper variables and functions available within both FreeMarker and XSL rendering engine templates.  These allow the author of a rendering engine template to perform conditional logic, extract content from the repository.

Here's a list of the variables and functions provided:

avm_sandbox_url: A variable that provides the URL to the root of the current sandbox.  For example:  http://www-alfresco2--admin.avm.alfresco.org:8180

form_instance_data_file_name: A variable that provides the name of the file containing the form instance data being used.

rendition_file_name: A variable provides the file name of the rendition being produced.

parent_path: A variable that provides the parent_path of the rendition being produced.  This is an AVM path  of the form:  alfresco2-admin-main:/appBase/avm_webapps.

request_context_path: ??? http://forums.alfresco.com/viewtopic.php?p=25552&sid=3f598085a96299c4e29653f8fda3408f

parseXMLDocument(String virtualPath): A function returning the root element of the XML file at the given virtualPath.  A 'virtual path' is virtualized path within the AVM repository.  The most recent version within the repository is assumed (i.e.: version -1).

parseXMLDocuments(String formName, String virtualPath):  A function returning an iterator over the root elements of the XML documents at directory given by virtualPath; this interator only contains those form instance data files generated by formName.  In FreeMarker, the return value of this function is a list.  In XSL, the return value is a node-set.  In either case, the attribute alf:file_name  is set on each element;  this contains the name of the file that was parsed.

In Freemarker, all variables and functions are in a hash called alf.  For example, to access the value of the parent_path variable, use the FreeMarker expression:

${alf.parent_path}

In XSL, all variables are in the namespace alf.  Thus, to access the value of the parent_path, use the XSL expression:

<xsl:value-of select='$alf:parent_path'/>

Examples can be found in the source tree in FTL and in XSL:

HEAD\root\projects\web-client\source\test-resources\xforms\unit-tests\rendering-engine-test\form-data-functions-test.*

Template Inclusion

Both Freemarker and XSL support including one template (or stylesheet) from another using the #include directive and xsl:include tag respectively.  The template to include can be either a path within the virtualized webapp the form is configured for, or secondarily the name of the file to include in the form's folder within the Web Forms space in the Data Dictionary.

More Freemarker Rendering Template Examples

NOTE Refer to Freemarker docs for more details.

Example - Using qualified elements namespaces

Schema:

<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
           xmlns:si='http://www.alfresco.org/alfresco/simple'
           targetNamespace='http://www.alfresco.org/alfresco/simple'
           elementFormDefault='qualified'>
  <xs:element name='simple'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='string' type='xs:normalizedString'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Form instance data:

 <si:simple>
   <si:string>hello!</si:string>
 </si:simple>

FreeMarker template:

HTML output rendition:

  
  hello!
  

Example - Using NameSpace Prefixes

Example - Using Variable Assignment

---

Return to WCM Forms Developer Guide