Nuxeo Server

Renditions

Updated: October 13, 2017 Page Information Edit on GitHub

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

Functional Overview

Users can export documents on their computer. It is possible to export:

  • One document at a time
  • A selection of documents
  • An entire workspace, folder, section

Exports Available

From a Folder

  • The XML export is a low level export that enables users to either get the XML definition of the document or get a folder for each exported document that contains:
    • A document.xml file holding the document's metadata and various information such as the applied access rights
    • A .blob file that holds the binary content of the document. This blob is referenced in the document.xml file
  • The ZIP Tree XML export enables you to export a whole workspace, section or folder in a zipped XML folder. This export is only available on folderish documents.

From a Document

  • The PDF export enables you to get a PDF version of your document. This export is only available on non-folderish documents.
  • The ZIP XML Export enables you to get a zipped folder with the documents' main attachment (.pdf, .doc files). This export is only available on non-folderish documents.
  • The XML export is a low level export that enables users to either get the XML definition of the document or get a folder for each exported document that contains:
    • A document.xml file holding the document's metadata and various information such as the applied access rights
    • A .blob file that holds the binary content of the document. This blob is referenced in the document.xml file

Export is available from:

  • The worklist
  • The Export button, available by clicking the icon in the More menu

Exporting Attachments

Users can easily export the attachments of a document or of a selection of documents, i.e. their main file and the additional attachments added from the Files tab of the documents.

Exporting the Attachments of a Document Selection

You can export the attachments of several documents at the same time, using the worklist.

To export a selection of documents, check the box that corresponds to the documents to export. Click on the Add to worklist button.

The documents are added to your worklist, in the left part of the screen.

Optionally go in other folders and add other documents to your worklist. In the worklist, click on the Export as ZIP link and Save the "Clipboard.zip" folder.

When you unzip it, you get the documents' attachments and an INDEX.txt file that summarizes the content of the export.

Exporting the List of Documents in a Folder

Just like it is possible to export search results, it is possible to export the list of documents in a workspace, section or folder. You can use the Excel export which enables you to get the list of documents inside the folder in an Excel table.

To export the list of documents of a space in an Excel file, click on the icon displayed in the top right corner of the Content tab of the workspace, folder or section. You are proposed to save a "document_content.xls" file, that displays the same information on the folder's documents as in the Content tab.

Low-Level Exports

XML export is a low level export that enables users to get a set of information on documents in an XML file. This export type is useful for debugging, and as such, is mainly intended to administrators. You can export:

  • A single document
  • A selection of documents
  • The structure of a folder

XML Export of a Single Document

The XML export of a document enables users to get a folder for the exported document that contains:

  • A document.xml file holding the document's various information (the applied access rights, the document's metadata, its path)
  • A .blob file that holds the binary content of the document. This blob is referenced in the document.xml file

To get the XML export of a document, from the document, click on the icon or, if the icon is not available on the action bar, on the Export button of the More menu in the action bar.

Click on ZIP XML Export on the pop-up window. You are proposed to save a "export.zip" file on your computer.

If you're only interested in the XML file of the document, click on XML Export. The XML file should open in a new tab or window (depending on your browser's preferences).

Save the "export.zip" file. When you unzip it, you get a folder named from the document, that contains a document.xml file and .blob for each attachment of the document.

XML Export of a Document Selection

It is possible to do an XML export of several documents in a single export, using the Worklist.

To export a selection of documents, check the box that corresponds to the documents to export to select it. Click on the Add to worklist button.

The documents are added to your worklist, in the left part of the screen.

Optionally go in other folders and add other documents to your worklist. In the worklist, click on the Export to XML link and Save the "export.zip" folder.

When you unzip it, you get a folder structure that reproduces the Nuxeo Platform tree to the document.

XML Export of a Folder

It is possible to export a whole workspace, section or folder in a zipped XML folder. This specific export enables users to import the folder back, with the same access rights definition.

To get the XML export of a folder, from the folder (or workspace or section), click on the icon or, if the icon is not available on the action bar, on the Export button of the More menu in the action bar.

Click on ZIP Tree XML Export on the pop-up window. You are proposed to save a "export.zip" file on your computer.

If you're only interested in the XML definition of the folder, click on XML Export. The XML file should open in a new tab or window (depending on your browser's preferences).

Save the "export.zip" file. When you unzip it, you get a folder named from the document, that contains a document.xml file and .blob for each attachment of the document.

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.


Related Documentation
9 days ago manonlumeau NXDOC-1346-FT review screenshot
2 years ago Manon Lumeau 8
2 years ago Manon Lumeau 7
2 years ago Florent Guillaume 6 | Add storeByDefault
3 years ago Solen Guitter 5 | Add links and related pages
3 years ago Thomas Roger 4
3 years ago Thomas Roger 3
3 years ago Thomas Roger 2
3 years ago Thomas Roger 1
History: Created by Thomas Roger