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

Contents

→ Purpose

→ Why XSL-FO

→ Supported scenario’s

→ Important notices

→ Default model

→ Installation

→ User guide

→ References

→ Contact

2

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, simplebooks, 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

Why XSL-FO

→ XSL-FO (XSL Formatting Objects) provides a set of formatting semanticsto 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 itborrows a lot of semantics from CSS (Cascading Stylesheets).

→ XSL-FO might not help you to produce high-end publications, but youcan use it for catalogues, simple books, documentation, letters, newsletters , advertisements, menu cards or business reports.

4

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.

5

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 addingresources from the Alfresco repository to the output using a Web Script request.

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

Default model

→ The following objects are available in the Freemarkerdefault 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

7

With the Freemarker engine you can combine metadata from Documents and Spaceobjects and content in your PDF output.

Installation

→ The Alfresco Formatting Module is distributed as an AMP file calledalfresco-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 spaceFormatting 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.

8

Tip: if you have not invested in developing XSL-FO templates using XSLT, we recommendthat you use Freemarker to create XSL-FO output. Freemarker provides powerful Alfresco specific features.

User guide

→ Using the Run Action Wizard

→ Using the Create Rule Wizard

→ Using the Apply Formatting Template dialog

→ Using the JavaScript API

9

USING THE RUN ACTION WIZARD

11

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

12

Select the Formatting Template and click OK to apply the template

13

Click Finish to end the wizard.

14

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

15

The output file is added to the space.

16

<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-beforeregion-name="xsl-region-before" extent="0.7in" />

<fo:region-afterregion-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>

A simple hello world formatting template...

17

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

USING THE CREATE RULE WIZARD

Content Rules

→ Selecting Manage Content Rules and then CreateRule enables you to add the Apply FormattingTemplate action to a Content Rule.

→ Visit the following Wiki page for more informationabout content rules in Alfresco: http://wiki.alfresco.com/wiki/Client_Manage_Content_Rules

19

USING THE APPLY FORMATTINGTEMPLATE DIALOG

21

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

22

Once the object has the aspect Formattable applied, Alfresco shows the ApplyFormatting Template action.

23

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

24

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

25

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

26

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

USING THE JAVASCRIPT API

27

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);

}

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);}

}

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