Preview

The nuxeo-platform-preview module provides services, converters and adapters to generate HTML previews of a Nuxeo DocumentModel. You may want to understand in details how this module works so as to change the behavior for a given MIME type or add the support of a new format.

Overview

When previewing a document, the logic executed goes through several layers (from end result to the most core part):

Preview tab in the JSF UI: Adds a Preview tab that displays the preview inside an iframe, querying the Restlet preview URL for the current document.
A preview Restlet, that is in charge of handling caching logic when delivering the HTML preview for a given document. The Restlet URL follows the pattern below:
```
http://NUXEO_SERVER/nuxeo/restAPI/preview/{server_name}/{document_uuid}/{previewfield}/
```
An example could be http://NUXEO_SERVER/nuxeo/restAPI/preview/default/cf5d81c5-e880-4f8a-9520-bf63e670260e/file:content/.

It gets the HTLM preview by getting the HtmlPreviewAdapter from the documentModel.
The HtmlPreviewAdapter is a standard Nuxeo Platform adapter, that is fetched using doc.getAdapter(HtmlPreviewAdapter.class). This adapter is a way to get access to the service below.
The PreviewAdapterManagerComponent and its getAdapter(DocumentModel doc) method, that returns, depending on the document type of "doc" and the contributions that have been made to extension "AdapterFactory" of this component, an object whose type implements the interface.

HtmlPreviewAdapter Details

The HtmlPreviewAdapter is an interface that is in charge of returning the preview blob (or list of blobs).

...
 preview = targetDocument.getAdapter(HtmlPreviewAdapter.class);
 List<Blob> previewBlobs= preview.getFilePreviewBlobs();

When no custom factory has been contributed for the given document type, the above mentioned service returns a ConverterBasedHtmlPreviewAdapter instance. This instance leverages the BlobHolder of the document to get the preview blob. If the document has no BlobHolder, it takes takes file:content or files:files. It uses the MimeTypePreviewer (see below) if the MIME type matches. If there is no MIME type match, the converter service is used to get a any2html conversion chain. (You can override/extend the MIME types that can benefit from this chain).

Some other adapters are contributed by default in the Platform, for pictures and notes. Contributing another adapter is of course possible. For instance, if you want to "merge" all the PDFs there are in the file:content and files:files properties of a custom "Report" type (or any other property) and preview all the content in one block. This custom logic could be written in such an adapter. Or, if you want to generate the preview of a CAD (AutoCAD) document and need to get some linked files before doing your generation, this is where you would do it.

MimeTypePreviewer Details

The MimeTypePreviewer, as said above, may be used by the converter-based HtmlPreviewAdapter as a helper to build the HTML document. It was introduced to handle cases where the binary to preview is already in plain/text, XML or HTML, and we just need to either wrap it by <PRE> chunks and encode existing tags inside the content, or do other small string manipulations. Pragmatically, you may want to contribute a MimeTypePreviewer if you want to build your preview by doing a bit of HTML assembly with some custom logic, and that you want to use this logic on a per MIME type basis. MimeTypePreviewer can be contributed via the extension system. You need to provide a mapping between a class that implements MimeTypePreviewer and a regular expression that can be validated by the MIME type of the targeted blob to preview.

Note that it is by default called only from the converter-based HtmlPreviewAdapter. If you contribute your own adapter and also want to benefit from this logic, you need to call inside your HtmlPreviewAdapter implementation. The following extract of Nuxeo code illustrates how to use it:

...
String srcMT = blob.getMimeType();
MimeTypePreviewer mtPreviewer = Framework.getService(PreviewAdapterManager.class).getPreviewer(srcMT);
        if (mtPreviewer != null) {
            blobResults = mtPreviewer.getPreview(blob2Preview, adaptedDoc);
            return blobResults;
        }

....