Display Documents Differences

Nuxeo Diff](https://doc.nuxeo.com/x/iYCo) is an amazing plug-in! It displays an interface that compares two documents or two versions of a document and shows the differences between them. For instance, we compare the current, “live” document to its latest saved version (1.1) in the following screenshot:

The plug-in displays the differences:

In the metadata: So we can easily spot if the “Subjects”, “Language” and “Expiration” fields were modified
In the binaries, if any: In the above example, we can see that the Word document was modified and clicking on one of the buttons on the right will display the differences in a pretty cool interface.

This useful plug-in is part of the installation wizard and available to you right away when you install a new version of the Nuxeo Platform. Of course, you can also always install it later from the Admin Center or with the command line.

Nuxeo Diff displays the differences by default:

In the dublincore schema
In the note schema
In the file and files schemas for the binaries, and in current version, it displays the differences only for text-like/text-based binaries (Word, Excel, etc.)

This is already quite cool but you may wonder: “What if I want to display the differences in _my_ custom schemas as well?”. For example, say you have this ApplicationCommon schema defined in Nuxeo Studio:

You added this schema to File, Picture and Video and want to display the differences for this schema. Just adding the schema to the default document types is not enough. In the previous example with the “Nuxeo Webinar Intro” document, if you modified a field from ApplicationCommon and displayed the differences, you still only see the differences in dublincore.

So, how can you add your schema to the Diff? Very easily actually! It is mainly all about adding an XML extension. The plug-in is built in a way that makes it smooth and fast. You don’t have to define custom XHTML widgets or layouts. Just contribute some XML and the plug-in will handle the complex engine behind the scene, detect the type of the fields, and use the correct widget to display the differences (single text value, date multivalued, complex field, etc.).

Everything is explained well in the GitHub page of the plug-in, but here I will summarize how to do it so you have a quick “How-to” guide.

Installation of the Document Differences Plug-In

First, you want to make sure Nuxeo Diff is installed on your server, or you will have hard time making it work (1).

Next, you have two small things to do which wouldn’t take more than 5 mins in Nuxeo Studio:

Add an XML extension to contribute this Diff plug-in
Add (or update) a “messages_en_US.properties”. This is a requirement of the Diff plug-in.

Contribute the Document Differences Plug-in

Here’s what you have to do:

Contribute a diffDisplay for each document type
In this diffDisplay, reference a diffBlock
Contribute this diffBlock

You must override the existing diffDisplay already contributed (typically, File).

Here is the first contribution. We added our ApplicationCommon diffBlock to the diffDisplay for File, Picture and Video:

<extension target="org.nuxeo.ecm.diff.service.DiffDisplayService" point="diffDisplay">
  <!-- Redefine the diffDisplay for File and other types, adding our display block -->
  <diffDisplay type="File">
    <diffBlocks>
      <diffBlock name="dublincore" />
      **<diffBlock name="ApplicationCommon" />**
      <diffBlock name="files" />
    </diffBlocks>
  </diffDisplay>

  <diffDisplay type="Picture">
    <diffBlocks>
      <diffBlock name="dublincore" />
      **<diffBlock name="ApplicationCommon" />**
    </diffBlocks>
  </diffDisplay>

  <diffDisplay type="Video">
    <diffBlocks>
      <diffBlock name="dublincore" />
      **<diffBlock name="ApplicationCommon" />**
    </diffBlocks>
  </diffDisplay>

</extension>

Now let’s move on to the diffBlock. A diffBlock is in charge of displaying the thing in the UI. A diffBlock has:

A name, which is its ID as referenced in previous contribution
A title
A list a fields to display (in the order you put them in the contribution)
A template layout, which, thankfully, already exists, so no need to write a new one

Here’s our ApplicationCommon diffBlock:

<extension target="org.nuxeo.ecm.diff.service.DiffDisplayService" point="diffBlock">
  <diffBlock name="ApplicationCommon">
    <properties mode="any">
      <property name="label">label.diffBlock.ApplicationCommon</property>
    </properties>
    <fields>
      <field schema="ApplicationCommon" name="country" />
      <field schema="ApplicationCommon" name="us_state" />
      <field schema="ApplicationCommon" name="topics" />
      <field schema="ApplicationCommon" name="width" />
      <field schema="ApplicationCommon" name="height" />
      <field schema="ApplicationCommon" name="count_elements" />
    </fields>
    <templates>
      <template mode="any">/layouts/layout_diff_template.xhtml</template>
    </templates>
  </diffBlock>
</extension>

That’s it! There’s no need to write a widget definition. Internally, the Diff plug-in already has all the widgets to display the differences for scalar fields (strings, int, double, etc.) including the list of values. Complex properties are also handled.

Add or update a messages_en_US.properties file

The Diff plug-in requires you to add the labels in a .properties file. You must follow its recommendations, or the plugin will display non user-friendly labels such as “label.diffBlock.ApplicationCommon” or “label.ApplicationCommon.country”, etc.(2)

Create or update a .properties file (see How to Upload Labels Translations in Nuxeo Studio (i18n)), and remember that the name of this file is important. In our case, in English, it must be “messages_en_US.properties”. In this file, add:

An entry for the tilte (here, label.diffBlock.ApplicationCommon)
One entry per field
One entry for the item of a multi-valued field

Here you go:

label.diffBlock.ApplicationCommon=Common Asset Data
label.ApplicationCommon.country=Country
label.ApplicationCommon.us_state=US State
label.ApplicationCommon.topics=Topics
label.ApplicationCommon.topics.item=Topic
label.ApplicationCommon.width=Width
label.ApplicationCommon.height=Height
label.ApplicationCommon.count_elements=Count Elements

Now save, deploy, and enjoy!

If you are interested in having a Diff for Pictures, you don’t have to wait long! It’s coming very soon in the Nuxeo Platform 7.4 release!

(1) Yes: This is a joke. The last one of this whole blog, because it is time to grow up and be serious, you know (2) Check future versions: We may change that to make it easier. At the time this blog is written, nuxeo-diff is in version 7.3