Platform Explorer / server 10.10

Bundle org.nuxeo.template.manager

Components

Maven artifact

filenuxeo-template-rendering-core-10.10.jar
groupId
artifactIdnuxeo-template-rendering-core
version10.10

Manifest

Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven
Built-By: jenkins
Build-Jdk: 1.8.0_191
Bundle-ManifestVersion: 1
Bundle-Version: 1.0.0
Bundle-Name: Nuxeo ECM Document template Manager
Bundle-SymbolicName: org.nuxeo.template.manager;singleton:=true
Nuxeo-Component: OSGI-INF/core-types-contrib.xml,OSGI-INF/types-contri
 b.xml,OSGI-INF/life-cycle-contrib.xml,OSGI-INF/templateprocessor-serv
 ice.xml,OSGI-INF/templateprocessor-contrib.xml,OSGI-INF/adapter-contr
 ib.xml,OSGI-INF/listener-contrib.xml,OSGI-INF/convert-service-contrib
 .xml,OSGI-INF/mimetype-contrib.xml,OSGI-INF/rendition-contrib.xml,OSG
 I-INF/operations-contrib.xml,OSGI-INF/pageprovider-contrib.xml

Documentation

  • 10.10

This modules contains the implementation of nuxexo-template-rendering module.

Main objects are

TemplateProcessorComponent

Runtime Component used to handle Extension Points and expose the TemplateProcessorService interface (interface that is used to manipulate TemplateProcessors and associated documents).

Default TemplateProcessor implementation

  • FreeMarker TemplateProcessor : FreeMarkerProcessor
  • XSLT based TemplateProcessor : XSLTProcessor

TemplateBasedDocumentAdapterImpl

Default implementation of the DocumentModel adapter for interface TemplateBasedDocument (a DocumentModel that is bound to one or more templates)

TemplateSourceDocumentAdapterImpl

Default implementation of the DocumentModel adapter for interface TemplateSourceDocument (a DocumentModel that can provide a template)

TemplateBasedRenditionProvider

Provides Rendition based on the template system.

Automation Operation

Automation Operations to wrapp TemplateProcessorService.

Additional documentation

How To  
ReadMe org.nuxeo.template.manager
  • 10.10

This modules contains the implementation of nuxexo-template-rendering module.

Main objects are

TemplateProcessorComponent

Runtime Component used to handle Extension Points and expose the TemplateProcessorService interface (interface that is used to manipulate TemplateProcessors and associated documents).

Default TemplateProcessor implementation

  • FreeMarker TemplateProcessor : FreeMarkerProcessor
  • XSLT based TemplateProcessor : XSLTProcessor

TemplateBasedDocumentAdapterImpl

Default implementation of the DocumentModel adapter for interface TemplateBasedDocument (a DocumentModel that is bound to one or more templates)

TemplateSourceDocumentAdapterImpl

Default implementation of the DocumentModel adapter for interface TemplateSourceDocument (a DocumentModel that can provide a template)

TemplateBasedRenditionProvider

Provides Rendition based on the template system.

Automation Operation

Automation Operations to wrapp TemplateProcessorService.

QuickUserGuide org.nuxeo.template.manager
  • 10.10

Quick User guide

Template Document

The first step is to create a Template Document.

This document will hold :

  • the template itself (docx or odt for now)

  • the parameters of the template

  • the options for template binding

Template Parameters

The template file itself uses Freemarker and can contain variable or Freemarker directives.

The default rendering context contains :

  • doc and document : both refering to the DocumentModel the template is rendered against

  • user : the current username

  • principal : the current user principal

  • auditEntries : the Audit entries associated to the DocumentModel the template is rendered against

But of course you can introduce new variables in your template. For example you can use ${mydescription} in the template file.

When creating a Template Document, the system will automatically try to extract all the variable names used in the template and ask you to provide a binding.

Each variable can be :

  • a String literal

  • a Date literal

  • a Boolean literal

  • a Document Property : a xpath that will be used to extract a property on the target Document

  • a Picture Document Property : same as Document property, but it must point to a Blob that will be used to replace a Picture inside the template file

Template Binding options

When creating or editing a Template Document, in addition of the template file parameters, you will be able to define options.

Here is a quick description of these options :

Applicable Document Types

Because your template can have parameters bound to xpath that are specific to a Document Type, you can define that your template is only available for some document types.

Automatic association

You can manually associate a Template Document to any Document in the Content Repository. If you want that association to be automatic, you can select the Document Types that should benefit from this association.

Typically, if I create a Template Document that is designed for Note and want it to be by default automatically associated to any Note I create, you will select Note doc type in Automatic Association.

Template Engine

The templating feature is pluggable so that we can easily add new template processors. Current implementation comes with 3 built-in processors :

  • XSLT processor (XML/XSLT)

  • Freemarker processor (bare freemarker)

  • XDocReport processor (ODT, ODS and DocX)

  • JXLS processor (for MS Excel files)

  • JODReport processor (legacy code for ODT)

  • raw XML processor for WordXML

When creating a Template Document you can select the target processor or keep the default value (automatic) to let the system choose the best processor depending on your template file mime-type. For now the default will always be XDocReport, but in the future it may change if for example we add raw freemarker or itext support for managing other template types than ODT and DocX).

Using Template Documents on an other Document

The idea is to use a Template Document to render an other Document.

TemplateBasedDocument

As example we provide a sample DocumentType that is called TemplateBasedDocument that is basically a File associated to a template.

  • you select the Template associated

  • you can render the template and have the resulting file stored in the file schema.

But this is probably not the main use case.

Dynamic binding

You dynamically bind a template to an existing Document. For that on each Document that is not already bound to a Template you will have a new Action on the top right corner: it will allow you to select a Template and associate it to the current Document. Technicall, we add a facet to the current Document.

NB : Using the automatic association in the Template Document is a way to avoid this manual operation.

Using the template bound Document

Once your Document is associated to a template (manually or automatically) you will have :

  • a new render action on the top right corner

  • a new Associated Template tab

Rendering

It will render the template against the current Document and return you the resulting file.

Associated Template tab

This tab provides :

  • a link to the associated Template Document

  • a summary of the template parameters (that you may be able to edit depending on the configuration)

  • a "render to file" action : same as rendering but stores the result as attachement of the current document

  • a "update template parameters" action : will resync the document with the Template Document parameters (useful if you edited the Template Document since the initial association)

Rendering context

From withing the template itself, you have access to a set of variable and functions. In most of the cases, the template synthax is very close to bare freemarker, but it may depends on the actual rendering engine :

  • xdocreport : FreeMarker based
  • FreeMarker : FreeMarker !
  • jod : FreeMarker based
  • jxls : JEXL based

Context variable

Anyway, there are a set of variable that will always be available :

  • doc or document : the DocumentModel being rendered
  • blobHolder : the BlobHodler adapter on the DocumentModel being rendered
  • username : interactive username (String)
  • principal : interactive User (Principal)
  • templateName : the name of the template being currently rendered (String)

In addition of this basic context, extensions can be registered to extend the content of the Context.

Default extensions include :

  • Audit : exposes audit entries associated to the DocumentModel being rendered

    • auditEntries (List<LogEntry>)
  • Helper function : misc function that may be useful

    • functions.getVocabularyTranslatedLabel(vocname, key, lang)
    • functions.getVocabularyLabel(vocname, key)
    • functions.getVocabularyLabel(vocname, key)
    • functions.formatDate(calendar)
    • functions.formatDateTime(calendar)
    • functions.formatTime(calendar)
  • Core Repository :

    • core.getParent()
    • core.getChildren()

Document Property bindings

For all Freemarker based template system, the binding is the same than WebEngine binding.

  • doc['schemaPrefix:propertyName']
  • doc.schemaName.propertyName

For JEXL based mapping only the synthax doc.schemaName.propertyName is supported.