Alfresco provides the ability to add custom transformers to transform a given source document to a different document format. There are several transformers available out of the box, but there is no transformer that let’s you transform an XML document to PDF based on XSL-FO.
You can check the available transformers in Alfresco. Since version 3.4 there is an Administration Web Script (http://localhost:8080/alfresco/service/mimetypes) that lists all mimetypes and the transformers between these mimetypes.
Custom Transformer
You can write the transformer using Java, but you can also add a custom transformer by adding a couple of configuration files. It might not provide you with all the bells and whistles you can think of, but at least it shows how you easily add XSL-FO support without writing any code.
The transformer allows you to transform an XSL-FO document to PDF using a Run Action, a Content Rule or using the following line in a JavaScript:
document.transformDocument("application/pdf");
An XSL-FO document is an XML file containing the content that should be published in the resulting document combined with lay-out instructions. The lay-out instructions are somewhat similar to applying a CSS stylesheet to an HTML document. In Alfresco you can use a Freemarker template or an XSLT stylesheet to transform a source node into an XSF-FO document.
Download and install FOP
The first step is to download and install FOP, the apache XSL-FO processor. You can find it at http://xmlgraphics.apache.org/fop/. The next thing you need to do is to add it to the path to allow Alfresco to locate the executable files. Using Windows you can do this by adding the path to FOP to the PATH environment variable.
Configure the Transformer
The next step is to configure the transformer. Create a file custom-content transformer-context.xml in the folder tomcat/shared/classes/alfresco/extension and add the following lines:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN'
'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<bean id="transformer.worker.FOP.PDF"
class="org.alfresco.repo.content.transform.RuntimeExecutableContentTransformerWorker">
<property name="mimetypeService">
<ref bean="mimetypeService" />
</property>
<property name="checkCommand">
<bean class="org.alfresco.util.exec.RuntimeExec">
<property name="commandsAndArguments">
<map>
<entry key=".*">
<list>
<value>fop.bat</value>
<value>-version</value>
</list>
</entry>
</map>
</property>
</bean>
</property>
<property name="transformCommand">
<bean class="org.alfresco.util.exec.RuntimeExec">
<property name="commandsAndArguments">
<map>
<entry key=".*">
<list>
<value>fop.bat</value>
<value>${source}</value>
<value>${target}</value>
</list>
</entry>
</map>
</property>
<property name="errorCodes">
<value>1,2</value>
</property>
</bean>
</property>
<property name="explicitTransformations">
<list>
<bean class="org.alfresco.repo.content.transform.ExplictTransformationDetails">
<property name="sourceMimetype">
<value>text/xsl</value>
</property>
<property name="targetMimetype">
<value>application/pdf</value>
</property>
</bean>
</list>
</property>
</bean>
<bean id="transformer.FOP.PDF"
class="org.alfresco.repo.content.transform.ProxyContentTransformer"
parent="baseContentTransformer">
<property name="worker">
<ref bean="transformer.worker.FOP.PDF" />
</property>
</bean>
</beans>
I the configuration above I only added the Windows command-line. If you run on Linux, you should remove the .bat extension.
Add the Mimetype
In order to allow Alfresco to recognize the XSL-FO source document, you need to add a new mimetype to Alfresco. There is no official mimetype for XSL-FO, but FOP lists an unregistered one called text/xsl. First add a file mimetypes-extension.xml in the Alfresco extension folder and add the following lines to the file:
<alfresco-config area="mimetype-map">
<config evaluator="string-compare" condition="Mimetype Map">
<mimetypes>
<mimetype mimetype="text/xsl" display="XSL-FO">
<extension>fo</extension>
</mimetype>
</mimetypes>
</config>
</alfresco-config>
Next add a file custom-mimetype-map-context.xml to the extension folder in order to load the new mimetype during the system bootstrap.
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN'
'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<bean id="mimetypeConfigService"
class="org.springframework.extensions.config.xml.XMLConfigService"
init-method="init">
<constructor-arg>
<bean class="org.springframework.extensions.config.source.UrlConfigSource">
<constructor-arg>
<list>
<value>classpath:alfresco/mimetype/mimetype-map.xml</value>
<value>classpath:alfresco/mimetype/mimetype-map-openoffice.xml</value>
<value>classpath:alfresco/extension/mimetypes-extension.xml</value>
</list>
</constructor-arg>
</bean>
</constructor-arg>
</bean>
</beans>
The last step is to add the transformer to the web-client-config-custom.xml:
<config evaluator="string-compare" condition="Action Wizards">
<subtypes>
</subtypes>
<specialise-types>
</specialise-types>
<aspects>
</aspects>
<transformers>
<transformer name="text/xsl" />
</transformers>
</config>
Restart Alfresco
When you restart Alfresco you should now be able to find the mimetype text/xsl listed in the Administration Web Script mentioned earlier. When you go to the details you should see that it is transformable to application/pdf.
Test the transformer
Now add a file called hello-world.fo to Alfresco with the following content:
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="A4-portrait"
page-height="29.7cm" page-width="21.0cm" margin="2cm">
<fo:region-body/>
</fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence master-reference="A4-portrait">
<fo:flow flow-name="xsl-region-body">
<fo:block>Hello World!>/fo:block>
</fo:flow>
</fo:page-sequence>
</fo:root>
Go to the document’s detail view and click Run Action and select Transform and Copy Content. The required format shall be Adobe PDF Document. Once you click OK you should be able to find a document called hello-world.pdf in the selected destination space.
JavaScript example
You can use the content transformer action in JavaScript to transform an XSL-FO document to PDF:
var action = actions.create("transform");
action.parameters["destination-folder"] = document.parent;
action.parameters["assoc-type"] = "{http://www.alfresco.org/model/content/1.0}contains";
action.parameters["assoc-name"] = document.name + "transformed";
action.parameters["mime-type"] = "application/pdf";
action.execute(document);
Creating XSL-FO output
There are a couple of options to create XSL-FO output in Alfresco. If you have XML documents that need to be transformed to PDF you can either use a Freemarker template or an XSLT stylesheet. You can use Alfresco’s XSLT Rendition Service to transform XML documents using XSLT.
Freemarker example
Create a file hello_world_fo.ftl in the space Data Dictionary/Presentation Templates and add the folowing lines to the file:
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="A4-portrait"
page-height="29.7cm" page-width="21.0cm" margin="2cm">
<fo:region-body/>
</fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence master-reference="A4-portrait">
<fo:flow flow-name="xsl-region-body">
<fo:block>${document.name}</fo:block>
</fo:flow>
</fo:page-sequence>
</fo:root>
Next create a file hello-world.js in Data Dictionary/Scripts and add the following content:
var template = companyhome.childByNamePath("/Data Dictionary/Presentation Templates/hello_world_fo.ftl");
if (template != null) {
var result = document.processTemplate(template);
var parent = document.parent;
var name = document.name.replace(".txt",".fo");
var output = parent.childByNamePath(name);
if (output ==null) {
output = parent.createFile(name);
}
output.content = result;
output.transformDocument("application/pdf");
}
When you execute the script using a Run Action on a document it creates a PDF file with the document name in the same space as the source document.
Reformat Rendering Engine
As with all transformations you can also use the XSL-FO transformer to create a rendition using the Reformat Rendering Engine. The following JavaScript code snippet provides an example:
var renditionDef = renditionService.createRenditionDefinition('cm:pdfRenditionDef', 'reformat');
renditionDef.parameters['mime-type'] = 'application/pdf';
var pdfRendition= renditionService.render(document, renditionDef);
This code will create a PDF rendition for the given XSL-FO document.
Using XSLT
You can use Alfresco’s rendition service to transform documents using XSLT in Alfresco. Using JavaScript you can for example transform a document with code similar to this:
var template = companyhome.childByNamePath("/Data Dictionary/XSLT Templates/hello-world.xsl");
var renditionDef = renditionService.createRenditionDefinition("cm:xsltRenditionDef", "xsltRenderingEngine");
renditionDef.parameters["template_node"] = template;
renditionDef.parameters["mime-type"] = "text/xsl";
var doc = renditionService.render(document, renditionDef);
You can then extend the rendition with a transformation to PDF using the Reformat Rendering Engine:
var template = companyhome.childByNamePath("/Data Dictionary/XSLT Templates/foptestxsl.xsl");
var renditionDef = renditionService.createRenditionDefinition("vlc:xslRenditionDef", "xsltRenderingEngine");
renditionDef.parameters["template_node"] = template;
renditionDef.parameters["mime-type"] = "text/xsl";
var doc = renditionService.render(document, renditionDef);
// add a destination to make the rendition visible
var destination = document.displayPath + "/" + document.name + "-rendered.pdf";
renditionDef = renditionService.createRenditionDefinition("cm:foRenditionDef", "reformat");
renditionDef.parameters['mime-type'] = "application/pdf";
renditionDef.parameters["destination-path-template"] = destination;
var pdfRendition= renditionService.render(doc, renditionDef);
This example first creates a rendition that applies an XSLT stylesheet to an XML document to produce an XSL-FO document and then creates a reformat rendition to transform the result to PDF using our Apache FOP based custom transformer.
Composite Rendering Engine
There is also a Composite Rendering Engine that is able to just persist the PDF which is actually what you want to do in this case. For example:
var template = companyhome.childByNamePath("/Data Dictionary/XSLT Templates/foptestxsl.xsl");
// the following method is not supported in the JavaScript renditionService
var compositeDefinition = renditionService.createCompositeRenditionDefinition("cm:compositeDefinition");
var xslRenditionDef = renditionService.createRenditionDefinition("cm:xslRenditionDef", "xsltRenderingEngine");
xslRenditionDef.parameters["template-node"] = template;
xslRenditionDef.parameters["mime-type"] = "text/xsl";
pdfRenditionDef = renditionService.createRenditionDefinition("cm:pdfRenditionDef", "reformat");
pdfRenditionDef.parameters['mime-type'] = 'application/pdf';
compositeDefinition.addAction(xslRenditionDef);
compositeDefinition.addAction(pdfRenditionDef);
var pdfRendition = renditionService.render(document, compositeRenditionDef);
This will not work as the Composite Rendering Engine does not seem to be exposed in the JavaScript API. The purpose of this post was to demonstrate what you can do without having to code Java. In a follow-up post I will show how to do this in Java.
Follow-up post
Read the follow-up post Using Alfresco Composite Rendition to Render PDF for examples how to use the Composite Rendition in Java and how to add the custom transformer in Java to use the FOP library already available in Alfresco in stead of having a separate installation of Apache FOP on the server.
Last updated: October 12, 2011
View Bas Peters's Linkedin profile
