Table of Contents
The nuxeo-platform-preview addon provides services,
transformers and adapters to generate HTML previews from of a Nuxeo
DocumentModel.
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.
Installing the Preview addon is fairly simple.
Just drop the nuxeo-platform-preview-5.X.jar in
the nuxeo.ear/plugins/ directory and restart your
server.
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).
The Preview addon provides several extension solutions.
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.
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.
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.