Home > Server > Platform Services > Renditions
Server

Renditions

Updated: December 17, 2024

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 Web UI.

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.

Default Rendition

A default rendition extension point allows to configure which rendition should be produced according to contextual data:

  • a reason
  • the CurrentUser
  • the Document
  <defaultRendition reason="download">
    <script language="JavaScript">
      function run() {
        if (Document.getType() == "File") {
          return 'mainBlob';
        } else if (Document.getType() == 'Picture') {
          return 'mainBlob';
        } else if (Document.getType() == 'Video') {
          return 'mainBlob';
        } else if (Document.getType() == 'Audio') {
          return 'mainBlob';
        } else if (Document.getType() == 'Note') {
          return 'pdf';
        } else if (Document.getFacets().contains("Collection")) {
          return 'containerDefaultRendition';
        } else if (Document.getFacets().contains("Folderish")) {
          return 'containerDefaultRendition';
        } else {
          return 'xmlExport';
        }
      }
    </script>
  </defaultRendition>

The language can be any JVM scripting language, the default is "JavaScript".

The <script> must define a run() function that returns the name of the rendition to be produced.

Note that the containerDefaultRendition rendition returns a ZIP containing the default renditions of the Folderish's children or the Collection's members.

Web UI leverages this capability in 2 important features:

  • Bulk Download which will pack inside a ZIP file the default renditions of a selection of documents to be downloaded.
  • Publishing where you can pick the default rendition to be used when publishing a document.
Related Documentation