Renditions

This page explains what renditions are, how to get them and how to contribute new ones.

Functional Overview

In the Nuxeo Platform, renditions are used for exports. For more information, discover how it works on:

What Are Renditions?

Renditions are alternative representations of a document, or its content such as:

A PDF representation of office files
A watermarked image
A resized video
An XML export of the document
...

Rendition Contributions

Renditions are declared on a document through rendition definition contributions. They are done on the org.nuxeo.ecm.platform.rendition.service.RenditionService .

Rendition Definitions

A rendition definition can be contributed through the renditionDefinitions extension point.

Sample contribution for a PDF rendition

<extension target="org.nuxeo.ecm.platform.rendition.service.RenditionService"
  point="renditionDefinitions">
  <renditionDefinition name="pdf">
    <label>label.rendition.pdf</label>
    <icon>/icons/pdf.png</icon>
    <contentType>application/pdf</contentType>
    <operationChain>blobToPDF</operationChain>
    <storeByDefault>true</storeByDefault>
    <filters>
      <filter-id>allowPDFRendition</filter-id>
    </filters>
  </renditionDefinition>
</extension>

By default, the rendition is computed through an automation chain, specified in the operationChain element. The rendition isn't stored permanently unless the code requesting it explicitly asks for it to be stored, but since Nuxeo 7.10 the default can be changed by using the storeByDefault element.

When using an automation chain to compute the rendition, note that the document and the main Blob are pushed on the operation context. For instance, the blobToPDF chain uses the Context.PopBlob operation as the first operation to retrieve the Blob to convert, see its contribution:

<extension target="org.nuxeo.ecm.core.operation.OperationServiceComponent"
  point="chains">
  <chain id="blobToPDF">
    <operation id="Context.PopBlob" />
    <operation id="Blob.ToPDF" />
  </chain>
</extension>

A rendition definition can also use a specific class (instead of the default DefaultAutomationRenditionProvider) to compute the rendition, through the class attribute on the renditionDefinition contribution. The class must implement the RenditionProvider interface.

Rendition Definition Providers

Rendition definitions can also be contributed through a RenditionDefinitionProvider on the renditionDefinitionProviders extension point. Using a RenditionDefinitionProvider allows to dynamically generate RenditionDefinition, especially useful when the renditions depends on the content of a document.

We have some examples in the Nuxeo Platform, such as:

PictureRenditionDefinitionProvider for picture conversions
VideoRenditionDefinitionProvider for transcoded videos

Here is the contribution for the PictureRenditionDefinitionProvider:

<extension target="org.nuxeo.ecm.platform.rendition.service.RenditionService"
  point="renditionDefinitionProviders">
  <renditionDefinitionProvider name="pictureRenditionDefinitionProvider"
    class="org.nuxeo.ecm.platform.picture.rendition.PictureRenditionDefinitionProvider">
    <filters>
      <filter-id>hasPictureFacet</filter-id>
    </filters>
  </renditionDefinitionProvider>
</extension>

Filtering Rendition Definitions and Rendition Definition Providers

Since 7.2, both contributions can be filtered through standard filters we already use in the Nuxeo Platform. The currentDocument referenced in the filter is the document on which the rendition definition is checked.