Major Use cases
There a several cases where it makes sense to compare (make a diff of) 2 documents.
- Version diff: you want to list the modifications between a document and one of its archived versions, typically in the case of functional specifications.
- Publication diff: you want to list the modifications between a published document and its source, typically in the case of a web site page to measure the gap between the draft and what is online. In Nuxeo this happens to be the same case as the Version diff since the published document is a proxy to a version of the document.
- Document diff: you want to list the modifications between a document A and a document B, typically in the case of product information documents where you may want to compare the product caracteristics such as material / price / creation date.
Approach
Comparing (= making a diff of) 2 documents or 2 versions of a document can be seen in a Nuxeo way as comparing the properties shared by the 2 documents.
- This means that if a comparison is done between two documents of a different type, only the schemas in common will be "diffed".
- The result of the comparison only shows the properties that have been updated, or added / deleted in the case of multivalued properties.
- The comparison should take into account blob-type properties. This is a tricky part since:
- The diff process depends on the blob mime type, therefore we need to be able to define a list of supported types for which the diff is possible and for each type to contribute a tool in charge of the diff.
- We have to find a nice way of displaying the result of a blob diff, again depending on the blob mime type.
High level User Story
- Launching a comparison
- In the History > Archived Versions tab I can check versions. If I check 2 (and only 2) versions then the Compare button located under the version listing gets enabled.
- In the same tab, for each version a button Compare to current version is also available.
These two first cases cover the Version diff use case. - In a content view if I check 2 (and only 2) documents then the Compare button located near the Copy, Paste, ... buttons gets enabled.
This approach is nice for comparing 2 documents living in the same container or that are part of a search result, but we also need to be able to compare 2 documents lcoated in separate containers. - So if I have added 2 (and only 2) documents to my worklist, then a Compare action appears in the worklist actions.
These two cases cover the Document diff use case. - In a publication Section if I check 1 (and only 1) proxy document then the Compare to working copy button located near the Delete, Unpublish buttons gets enabled.
This case covers the Publication diff use case.
- Viewing the diff result in the UI
- The diff result is displayed in the right panel, as a table with 2 columns: document A / document B, and as many lines as different properties.
- By default, properties are grouped by schemas. It could be nice to have a layout / widget system to have a full control on the diff result display.
- Rendering of a blob-type property diff still has to be defined.
- Attached screenshot gives an example of the result of a diff between 2 documents, for most property types (simple, complex, complex list).
A color code is used to better distinguish updated / added / deleted values:- red for left document
- green for right document
- The add/delete notions make sense in the version diff case.
In the document diff case, we can consider that we are comparing the right document with the left document which is the reference.
Therefore a value existing in the right doc and not in the left one will be considered as "added" in comparison with the reference doc => green means added.
Conversely for the "deleted" case: red means "deleted".
- PDF export
- I want to make a PDF export of a diff result.
- I may also want to automatiucally store the generated PDF in Nuxeo?
