Chapter 62. Nuxeo Preview Addon

Table of Contents

62.1. Overview
62.2. Installing the Preview Addon
62.2.1. Deploy the Addon
62.2.2. Configure Transformers
62.3. Extensions and Pluggability
62.3.1. Pluggable Adapters
62.3.2. Pluggable HTML Transformers
62.4. Previews and URLs

The nuxeo-platform-preview addon provides services, transformers and adapters to generate HTML previews from of a Nuxeo DocumentModel.

62.1. Overview

The preview addon is composed of several layers:

  • UI part

    Adds a Preview tab that displays the preview inside an IFRAME.

  • Transformer part

    The Preview addon contributes transformers that are dedicated to generating HTML out of most file formats.

  • Service and Adapters

    The Preview addon includes services that allow you to define PreviewAdapters for each type of Document. These adapters are responsible for defining how the preview will be generated:

    • define the field(s) used for preview

      Because a Nuxeo document contains a lot of differents fields, the adapter must determine what are the default fields used to generate the preview.

    • define how preview is generated

      Basically preview can be generated using some transformers or using some fields that already contains pre-generated HTML preview

    The services provided by the Preview addon let you configure the PreviewAdapter depending on your document types and manage some cache for transformer based previews.

62.2. Installing the Preview Addon

Installing the Preview addon is fairly simple.

62.2.1. Deploy the Addon

Just drop the nuxeo-platform-preview-5.X.jar in the nuxeo.ear/plugins/ directory and restart your server.

62.2.2. Configure Transformers

The preview service relies on HTML transformers that uses external tools to achieve the transformation. You need to have them installed and configured before the preview addon will work.

The preview service comes with two HTML transformers:

  • PDF2Html

    This transformer generates HTML from PDF files.

    This transformer relies on the command line tool pdftohtml This tool can be found as package for most linux distrib (for instance, included in poppler-utils in Ubuntu). This tool can also be installed on MS Windows platform, see http://sourceforge.net/projects/pdftohtml/

    Once you have installed pdftohtml on your server, you must configure Nuxeo to let him know where is the command line tool. For this, you can use a extension point to define what is the temporary directory to use and where is pdftohtml command.

    Default settings should be ok for most Linuxes, but you will have to do the configuration if you use a MS Windows box.

    To do this configuration, create a file named pdftohtml-config.xml in the nuxeo.ear/config directory

                <?xml version="1.0"?>
    <component name="myproject.pdftohtml.config.contrib">
      <extension target="org.nuxeo.ecm.platform.preview.transformers.CLTransformerPluginParameterManagerComponent"
        point="cltpParameters">
    
      <CLTranformerPluginParameters name="Pdf2HtmlParams" targetTransformerPlugin="Pdf2Html">
        <parameters>
          <!-- default Linux parameters 
          <parameter name="commandString">/usr/bin/pdftohtml</parameter>
          <parameter name="tmpDir">/tmp/</parameter> -->
          <!-- MS Windows parameters -->
          <parameter name="commandString">C:\\Program files\\pdftohtml\\pdftohtml.exe</parameter>
          <parameter name="tmpDir">C:\\Temp\\</parameter>
        </parameters>
      </CLTranformerPluginParameters>
      </extension>
    </component>
    
    
              
  • Any2Html

    This Transformer is in fact a chain using Any2pdf and PDF2html. This means you need to have PDF2html working but also OpenOffice.org in listen mode (this is documented earlier in this book).

62.3. Extensions and Pluggability

The Preview addon provides several extension solutions.

62.3.1. Pluggable Adapters

Preview AddOn uses the standard DocumentModelAdpater system. For that it defines a HtmlPreviewAdapter interface that must be implemented by each adapters. In order to let you choose the Adapter implementation according to the Document type, the DocumentAdapterFactory used for the HtmlPreviewAdapter is pluggable. This factory uses the PreviewAdapterManager service to determine what implementation of the HtmlPreviewAdapter should be returned when you use

doc.getAdapter(HtmlPreviewAdapter.class)

.

Defining custom preview adapter is done via a dedicated extension point: you register a Factory for a given DocumentType. This factory will be used to create the implementation of the HtmlPreviewAdapter from the DocumentModel. Here is example of such a contribution:

          <?xml version="1.0"?>
<component name="org.nuxeo.ecm.platform.preview.adapter.contrib">
  <extension target="org.nuxeo.ecm.platform.preview.adapter.PreviewAdapterManagerComponent"
    point="AdapterFactory">

    <previewAdapter name="notePreviewAdapter" enabled="true">
      <typeName>Note</typeName>
      <class>org.nuxeo.ecm.platform.preview.adapter.factories.NotePreviewAdapter</class>
    </previewAdapter>

  </extension>
</component>

        

This contribution defines the Adapter factory for the Note Document type. Contributed factories must implement the PreviewAdapterFactory interface (that contains only one method!).

The implementation returned by the factory can be based on one of the 2 base classes provided inside the addon.

  • TransformerBasedHtmlPreviewAdapter

    This base class provides all the build in features to create a preview adapter that uses the Transformation Services to generate the html preview.

    Default usage in Nuxeo is the generic adapter for the all the documents that contains the file schema.

  • PreprocessedHtmlPreviewAdapter

    This base class provides all the build in features to create a preview adapter that uses pre-processed HTML preview that is stored inside the document.

    Default usage in Nuxeo is the adapter for the Note Document type.

    For most usages, you just be able to contribute a factory that create a new PreprocessedHtmlPreviewAdapter with the good arguments.

62.3.2. Pluggable HTML Transformers

The Preview addon contributes some command line based transformers.

It also provides you with a base class AbstractCommandLineBasedTransformer that can be used to easily make another CommandLine based Transformer.

We also provide a CLTransformerPluginParameterManager service that is used by the base class to extact the configurable parameters.

62.4. Previews and URLs

The preview addon includes a restlet.

This restlet provides a RESTful access to the preview service. This means that you can retrieve the preview of a document by just using a simple GET URL.

Preview URLs have this form :

http://{server}:{port}/nuxeo/restAPI/preview/{document_uuid}/{previewfield}/

where:

  • document_uuid

    is the the document uuid that is already present in all Nuxeo urls

  • previewfield

    is the xpath of the field that should be used as main file for the preview

    Depending on the underlying adapter implementation, this field may or may not be relevant. Use 'default' to let the adapter implementation choose the right field for you.

Please note that the last / is important. As HTML preview can contain nested images, the base URL must end with a /. The Restlet system handles a cache to avoid refetching the preview data at each call.