Rendition templates simplifies and accelerates the web publishing process by transforming the web form-managed XML content into web content. Rendition templates can be written in the FreeMarker template language (with an extension .ftl), Extensible Stylesheet Language Transformations (with an extension .xslt), and Extensible Stylesheet Language Formatting Objects (with an extension .xsl-fo). You can leverage the built-in renditioning engine for FreeMarker, XSL, and XSL-FO template languages. After a content item (XML file) is created with a web form, each rendition template is configured for that content type to produce an output in a desirable format. It mainly includes plain text, JSP, PDF, and HTML.
The second step of the Create Web Form wizard suggests configuring a template for rendition output. In this section, you will learn in detail about how to create and configure a template while creating web forms. We will use the FreeMarker template for rendition in this chapter and will see an overview about XSLT and XSL-FO.
FreeMarker is an open source template engine. It is a generic tool for generating text output (which can be anything from HTML to auto-generated source code) based on templates. FreeMarker is designed to be practical for the generation of HTML web pages, by following the MVC (Model View Controller) pattern. The idea behind using the MVC pattern for dynamic web pages is that you separate the content authors from the programmers. This separation is useful, even for projects where the programmer and the HMTL page author are the same person, as it helps to keep the application clear and easier to maintain. If you want that page to be more dynamic, then you begin to put special parts into the HTML, which will be understood by FreeMarker. For instance,"${...}" will produce output with the actual value of the thing inside the curly brackets. Presentation templates are written in FreeMarker template language and will have a .ftl extension.
In the following figure, the content authors create document content in Alfresco. The programmers create the presentation template file with stylesheets and HTML code, taking care of look and feel requirements. The final content will be generated by the FreeMarker engine (which is embedded in Alfresco) by applying the presentation template on the document content as shown in the following figure:
The FreeMarker template engine is embedded within Alfresco. FreeMarker takes schema as input and generates text (HTML or XML) as output. FreeMarker also supports XSLT to translate XML content.
The default model provides a set of named objects that wrap Alfresco Node objects to provide a rich, object-oriented layer, suitable for scripting usage. If you are accessing the templates through the web-client UI, then the following named objects are provided by default:
|
Named object |
Description |
|---|---|
|
|
This provides the URL to the root of the current sandbox. |
|
|
This provides the name of the file containing the form instance data being used. |
|
|
This provides the filename of the rendition being produced. |
|
|
This provides the |
For example, consider the following FreeMarker template. In FreeMarker, all variables and functions are in a hash called alf:
<html>
<head>
<title>Whats New</title>
</head>
<body>
<h1>${alf.parent_path}</h1>
</body>
</html>
At runtime, the value of variable alf.parent_path will be the path of XML file, which is generated while creating content.
Note
The Alfresco Wiki website (http://wiki.alfresco.com) contains a complete reference to the FreeMarker template engine.
These objects, and any child node objects, are called template-node objects, and they provide the following API:
Like any programming language, the FreeMarker templating language also supports fundamental directives such as the following:
${ }
#if, #else, #elseif
#switch, #case
#list
#assign
FreeMarkerFreeMarker template engine#function
#include
<#-- comment -->
<!--comment -->
Continuing with our example of the Cignex.com website, we have already created web forms for blogs and a news section. Now we will associate these web forms with the rendition templates. We will first learn to create FreeMarker templates. Let's learn how to create .ftl files.
To create .ftl files, we have to start with the standard declaration of the default name space for the associated web form (consider the blog web form) using the<#ftl > tag (check the target namespace of the blogs.xsd file that has been used in creating the blog web form), as follows:
<#ftl ns_prefixes={"D", "http://www.alfrescobook.com/webforms"}>
Now we need to display the elements we have used for the blog web form. In the blogs.xsd file, we have defined the root element as "blogs". Assume we want to use the mainTitle, contentSubHeader, and publishedDate elements of the blog.xsd in the .ftl file. The following table shows various uses of FreeMarker directives:
|
Description |
XSD syntax |
FTL syntax |
|---|---|---|
|
Display single element |
|
|
|
Display recurring elements |
|
|
|
Sort the recurring elements |
|
|
|
Conditional checks |
|
|
Let's develop a FreeMarker template for rendition:
- Navigate to the
<installed-alfresco>/extras/wcm/formsfolder. - Create a file named
news.ftlin the above-specified path and populate it with the downloaded code from Packt's website. - Create a file named
blogs.ftlin the above-specified path and populate it with the downloaded code from Packt's website.
Note
For your reference, a complete guide to FreeMarker directives is available at: http://FreeMarker.sourceforge.net/docs/. Download the complete code samples from the Packt website.
The Extensible Stylesheet Language is divided into two sub-languages: Extensible Stylesheet Language Transformations (XSLT) and Extensible Stylesheet Language-Formatting Objects (XSL-FO).
XSLT is a stylesheet language for XML documents. It is designed to transform XML documents into other formats such as XHTML (Extensible HTML). With XSLT you can add/remove elements and attributes to or from the output file. You can also rearrange and sort elements, perform tests, and make decisions about which elements to hide and display. XSLT uses XPath to find information in an XML document. XPath is used to navigate through elements and attributes in XML documents. XSLT uses XPath to define parts of the source document that should match one or more predefined templates. When a match is found, XSLT will transform the matching part of the source document into the result document. XSLT is written in stylesheet language and will have .xsl extension.
Some of the fundamentals used for XSLT are:
|
Declare namespaces |
|
|
Define output format |
|
|
Define Template |
|
|
Iterate from a set of repeating elements |
|
|
Select the values of single occurring element |
|
|
Provide conditions |
|
Let's develop an XSL template for rendition:
- Navigate to the
<installed-alfresco>/extras/wcm/formsfolder. - Create a file named
training.xslin the above-specified path and populate it with the downloaded code from the Packt website.
Note
Download the complete code samples from Packt Publishing's website. For your reference, a complete guide to XSL template is available at: http://www.w3schools.com/xsl/.
It is designed to provide a mechanism for formatting XML data for print, screen, and other output media. Transforming XML for print is accomplished by transforming an XML document to a Formatting Objects (FO) document, which itself is XML based, via XSLT. The Formatting Objects processor is able to read the FO document and transform it for different types of print output. The most common and best-supported print output is currently Adobe PDF. XSL-FO has the advantage of being able to produce PDFs.
The template files are now ready to use. The next task is to associate rendition templates with the web forms created earlier, for this web form should be created in Alfresco. In our case, we have already created a web form in the earlier section.
Templates cannot be associated through the web project after the web form is created. Since the web form is already created, the association of template must be done through Company Home | Data Dictionary | Web Forms | <web-form space name>. We will configure our template to the blog's web form. The process is as follows:
- Ensure that the Alfresco Server is up and running.
- Go to Company Home | Data Dictionary | Web Forms | <web-form space name> | Blog:
- Clicking on Edit Web Form action image under the web form space name (as shown in the previous screenshot) opens the Edit Web Form Wizard window. You may notice that the Edit Web Form Wizard window has four steps, as shown in the following screenshot. The first step is to delete the previously uploaded XSD (if you want to upload another XSD) file and then upload the XSD, the second step is to configure templates for rendition output, the third step is to define the workflow for form data, and the fourth step is to confirm the web form.
- In the Step One window, you will notice the information provided about the web project if this corresponding web form is associated. You will also see that the rest of the values are prepopulated on the basis of the attached web form. You are given the facility to upload or delete the existing XSD file, if required. You can also change the Output path pattern. For now we will not make any change, so click on Next.
- In the Step Two window, the Configure Templates page is shown. This step allows you to upload a template file in order to generate forms in various outputs. Click on Browse to locate and upload the
blog.ftlfile created in the<installed-alfresco>/extras/wcm/formsfolder. After uploading, it will automatically fill up values, such as Rendering Engine, Name, Title, Rendition mimetype, and Output path pattern. By default, the Rendition mimetype will be selected as HTML. You can change the output path pattern and also the extension. This means the file will be created with the specified extension in the specified path. Take a look at the following screenshot and change the output path as specified. We have also changed the extension in order to generate the JSP file. By default, an HTML file will be generated. Click on the Add to List button to add the uploaded templates. You can click on the Add to List button as many times as you want to upload templates. A list of associated templates will be visible at the bottom. The Remove icon is also provided to delete the template in case it's not required. Click on Next:
- In the Step Three window, the Configure Workflow page is shown. Select the No not now option (this step allows the creation of default workflows for form data; you will learn more about this in the next chapter WCM Workflow).
- Clicking on the Next button will take you to the Step Four window, which displays a summary of the web form. Clicking on the Finish button will create the template. You will notice blog.ftl inside the blog space:
- Continue the previous steps to upload the
news.ftlandtraining.xslfile. Provide the Output path pattern, as shown in the following screenshot, for creating the news template when the Configure Templates pane is open.
- Provide the Output path pattern as shown in the following screenshot for creating the training template when the Configure Templates pane is open.
Note
Do not proceed to the subsequent sections without first configuring the templates. The remaining sample solution is based on these web forms and templates. Remember to specify the output path pattern as shown in the previous screenshots for news and blogs. The Alfresco Wiki website (http://wiki.alfresco.com/wiki/WCM_Forms_Rendering) contains information about forms and widgets.