How to use the Alfresco Formatting Module to apply formatting templates to create PDF documents.

1. Alfresco Formatting Module
Apply a formatting template to either
a space or a document to create PDF
output.
Version 1.0, June 15, 2009
1

2. Contents
→ Purpose
→ Why XSL-FO
→ Supported scenario’s
→ Important notices
→ Default model
→ Installation
→ User guide
→ References
→ Contact
2

3. Purpose
→ The Alfresco Formatting Module provides a custom action to apply XSL-
FO templates to Documents and Space objects to create PDF output.
→ In just a few clicks (or no clicks at all when using a content rule) you
can produce high quality PDF documents.
→ It can be used to create on demand publications, catalogues, simple
books, documentation, letters, newsletters, advertisements, menu
cards or business reports.
→ Both XSLT and Freemarker can be used as a template rendering engine.
→ As a side-effect the module can be used to apply XSLT stylesheets to
XML documents to create XML, HTML or plain-text output.
3

4. Why XSL-FO
→ XSL-FO (XSL Formatting Objects) provides a set of formatting semantics
to describe the presentation of a document on screen or paper.
→ Although XSL-FO never received much attention, support for the
standard adds a simple to use PDF formatting engine to Alfresco.
→ Writing templates to produce XSL-FO output is not that difficult since it
borrows a lot of semantics from CSS (Cascading Stylesheets).
→ XSL-FO might not help you to produce high-end publications, but you
can use it for catalogues, simple books, documentation, letters,
newsletters , advertisements, menu cards or business reports.
4

5. Supported scenario’s
→ A Freemarker template that produces XSL Formatting Objects applied
to an object or objects will be formatted to PDF.
→ An XSLT stylesheet that produces XSL Formatting Objects applied to an
XML document will be formatted to PDF.
→ An XSLT stylesheet with output method html applied to an XML
document will be transformed to HTML.
→ An XSLT stylesheet with output method text applied to an XML
document will be transformed to plain text.
→ An XSLT stylesheet with output method xml applied to an XML
document throws a DuplicateChildNodeNameException when
executed from either the custom dialog or run action wizard.
Tip: when using XSLT you can add an alf_ticket parameter. This parameter is added by the
formatter to enable you to authenticate against Alfresco for example when adding
resources from the Alfresco repository to the output using a Web Script request.
5

6. Important notices
→ If the output file already exists and the object has the aspect
Versionable, it will create a new version, otherwise the output file will
be overwritten.
→ When you apply a formatting template from the Run Action Wizard or
a Content Rule, the name of the document is used as output file name
with the extension of the output format.
→ Therefore an XSLT stylesheet with output method xml will throw a
DuplicateChildNodeNameException, since the object created will have
the same name as the source document.
→ Use the JavaScript Root Object formatter in these cases to specify a
different output file name and execute the script using either the Run
Action Wizard or a Content Rule.
→ See the example later in this presentation.
6

7. Default model
→ The following objects are available in the Freemarker
default model:
companyhome: the Company Home template node.
userhome: current users Home Space template node.
person: node representing the current users Person object.
space: the current space template node.
→ If you apply the template to a document object:
document: the current document template node.
→ See also: http://wiki.alfresco.com/wiki/Template_Guide
With the Freemarker engine you can combine metadata from Documents and Space
objects and content in your PDF output.
7

8. Installation
→ The Alfresco Formatting Module is distributed as an AMP file called
alfresco-formatting.amp.
→ Available at: http://forge.alfresco.com/projects/formatter.
→ Please refer to the Alfresco documentation on how to install a module.
→ Please note that installing a module requires a restart.
→ Once the module is installed and Alfresco is restarted, a space
Formatting Templates is added to the Data dictionary, an aspect
Formattable is added and an Apply Formatting Template action is
available through the Run Action and Create Rule wizards.
→ Put your formatting templates in the space Formatting Templates.
→ You can add both XSLT and Freemarker templates.
Tip: if you have not invested in developing XSL-FO templates using XSLT, we recommend
that you use Freemarker to create XSL-FO output. Freemarker provides powerful Alfresco
specific features.
8

9. User guide
→ Using the Run Action Wizard
→ Using the Create Rule Wizard
→ Using the Apply Formatting Template dialog
→ Using the JavaScript API
9

10. USING THE RUN ACTION WIZARD

11. Navigate to the details view of the document or space object and select Run
Action from the menu. Alfresco will start the Run Action Wizard.
11

12. Select the Formatting Template and click OK to apply the template
12

13. Click Finish to end the wizard.
13

14. Once finished, the Formatting Action will provide you with a confirmation.
14

15. The output file is added to the space.
15

16. A simple hello world formatting template...
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="only">
<fo:region-body
region-name="xsl-region-body"
margin="0.7in" />
<fo:region-before
region-name="xsl-region-before"
extent="0.7in" />
<fo:region-after
region-name="xsl-region-after"
extent="0.7in" />
</fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence
master-reference="only">
<fo:flow flow-name="xsl-region-body">
<fo:block>${space.name}</fo:block>
</fo:flow>
</fo:page-sequence>
</fo:root>
16

17. The formatted object for the simple hello world example...
17

18. USING THE CREATE RULE WIZARD

19. Content Rules
→ Selecting Manage Content Rules and then Create
Rule enables you to add the Apply Formatting
Template action to a Content Rule.
→ Visit the following Wiki page for more information
about content rules in Alfresco:
http://wiki.alfresco.com/wiki/Client_Manage_Con
tent_Rules
19

20. USING THE APPLY FORMATTING
TEMPLATE DIALOG

21. First add the aspect Formattable through the Run Action Wizard with
the Add aspect to item action.
21

22. Once the object has the aspect Formattable applied, Alfresco shows the Apply
Formatting Template action.
22

23. Click the Apply Formatting Template action, select a template from the
Formatting Templates space and click OK to render the template.
23

24. Once finished, the formatting action will provide you with a confirmation.
24

25. By default the result is added to the space of the source document.
25

26. The output below uses an example from http://www.w3schools.com/.
26

27. USING THE JAVASCRIPT API
27

28. Basic example
→ You can call the formatter with a document
and template node as parameters:
var template = companyhome.childByNamePath("/Data Dictionary/Formatting Templates/cdcatalog.xsl");
if (template != null)
{
formatter.format(document, template);
}

29. Specify output location
→ You can add an output file node to specify a
different output file and location:
var template = companyhome.childByNamePath("/Data Dictionary/Formatting Templates/cdcatalog.xsl");
if (template != null)
{
var outFile = space.childByNamePath("cdcatalog.html");
if (outFile == null)
{
outFile = space.createFile("cdcatalog.html");
}
if (outFile != null)
{
formatter.format(document, template, outFile);
}
}

30. References
→ Project site:
http://forge.alfresco.com/projects/formatter.
→ The following Alfresco Wiki pages might be helpful:
http://wiki.alfresco.com/wiki/Template_Guide
http://wiki.alfresco.com/wiki/JavaScript_API
→ The following tutorials might be helpful to get you started with XSL-FO:
http://www.xml.com/pub/a/2002/10/09/xslfo.html
http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html
http://www.cafeconleche.org/books/bible2/chapters/ch18.html
http://www.renderx.com/tutorial.html
http://www.antennahouse.com/XSLsample/XSLsample.htm
http://www.dpawson.co.uk/xsl/
http://www.w3schools.com/xslfo/default.asp
30