Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
The Diff module enhances Magnolia core versioning functionality. The module uses the daisydiff Java library to compare two HTML files. Insertions are highlighted in green and deletions in red. Users can see exactly what has changed between two versions of the same content. The module is used by the Pages app to compare page versions. Line-by-line text comparison and changes in asset selection allow editors and publishers to see at a glance exactly what has changed. Diff functionality can also be enabled to compare changes to templates and resources edited in-line in the Standard Templating Kit.
groupId
and artifactId
) have changed since Magnolia 5.5.If you have custom Java code relying on this module, you need to install a compatibility module too.
To be sure - please check the module on our Bitbucket server.
Note the changes in groupId
and artifactId
since the 2.0 release.
<dependency> <groupId>info.magnolia.diff</groupId> <artifactId>magnolia-diff</artifactId> <version>2.0.1</version> </dependency>
For integration with the Pages app there is also magnolia-diff-pages-integration
.
<dependency> <groupId>info.magnolia.diff</groupId> <artifactId>magnolia-diff-pages-integration</artifactId> <version>2.0.1</version> </dependency>
With Magnolia 5.6 we've begun removing the old Content API from our modules. If you have custom code relying on classes from the old diff module then you must do one of two things:
magnolia-diff-compatibility
module together with the magnolia-core-compatibility
module.In most circumstances the Diff module requires no configuration.
However, version comparison relies on functionality provided by the Diff module and, if implemented, may require the following configuration.
VersionDiffHtmlServlet is registered in the Magnolia filter chain in the Configuration app > /server/filters/servlets/VersionDiffHtmlServlet
. The controller generates the diff view between two versions of a page by checking the toVersionNr
and fromVersionNr
request parameters.
Node name | Value |
---|---|
VersionDiffHtmlServlet | |
mappings | |
-.magnolia-versionDiff | |
pattern | /.magnolia/versionDiff |
parameters | |
class | info.magnolia.cms.filters.ServletDispatchingFilter |
comment | Shows html diff of different page versions. |
enabled | true |
servletClass | info.magnolia.module.diff.VersionDiffHtmlServlet |
servletName | VersionDiffHtmlServlet |
The default settings for headers, cookies, host and port can be set by configuration.
By default Magnolia is set to generate a JSESSIONID cookie. This is configured in the diff
module in the Configuration app > /modules/diff/config/cookies
.
Node name | Value |
---|---|
modules | |
diff | |
config | |
cookie | |
0 | JSESSIONID |
You can configure custom settings for:
cookies
: You can specify any number of custom session cookie names to forward.headers
: The default value is none
. By adding a headers
config node you can specify any number of headers to be sent to the diff servlet thereby automatically excluding any headers that are not specified.host
and port
: The default host and port is localhost
and 8080
. However, the Diff module will work even if you change the default Tomcat port. This means that you can use the diff functionality against another server. Headers and cookies are configured separately.
Node name | Value |
---|---|
diff | |
config | |
cookies | |
0 | <cookieA> |
1 | <cookieB> |
headers | |
0 | <headerA> |
1 | <headerB> |
host | <host> |
port | <port> |
VersionDiffHtmlGenerator compares two HTML files using HTMLDiffer
and returns HTML that highlights the differences between the compared pages:
Here's a snippet from diff.css
(GIT) located in the mgnl-resources
folder of the module jar.
/* * Styles for the HTML Diff */ span.diff-html-added { font-size: 100%; background-color: #ccffcc; /* light green */ cursor: pointer; } span.diff-html-removed { font-size: 100%; text-decoration: line-through; background-color: #fc6f6f; /* light red */ cursor: pointer; } span.diff-html-changed { background-color: #95c6fd; /* light blue */ cursor: pointer; } span.diff-html-selected { background-color: #FF8800; /* light orange */ cursor: pointer; }
Two utility classes are provided:
buildComparisonURL
, buildComparisonURLToCurrent
and buildComparisonURLToCurrentUnversioned
methods. gets
and sets
the versionFrom
and versionTo
methods.The CompareLocalizedVersionsAction and CompareToPreviousLocalizedVersionAction open the diff subapp (see below) configured in the Pages app. The action definitions are configured in the Configuration app > /modules/pages/apps/pages/subApps/browser/actions
.
Node name | Value |
---|---|
modules | |
pages | |
apps | |
pages | |
subApps | |
browser | |
actions | |
compareVersions | |
availability | |
class | info.magnolia.module.diff.app.action.CompareLocalizedVersionsActionDefinition |
icon | icon-compare-versions |
label | Compare versions |
compareToPreviousVersion | |
availability | |
class | info.magnolia.module.diff.app.action.CompareToPreviousLocalizedVersionActionDefinition |
icon | icon-compare-versions |
label | Compare to previous version |
The diff view that opens when comparing different page versions is configured in the Pages app. This configuration is in the Configuration app > /modules/pages/apps/pages/subApps/diff
.
class
: EmbeddedPageSubAppDescriptor embeds the page in an iframe. label
: Renders in the subapp tab.subAppClass
: EmbeddedPageSubApp is the main tab in an embedded page app.Node name | Value |
---|---|
modules | |
pages | |
apps | |
pages | |
subApps | |
browser | |
detail | |
diff | |
class | info.magnolia.ui.framework.app.embedded.EmbeddedPageSubAppDescriptor |
label | Show changes |
subAppClass | info.magnolia.ui.framework.app.embedded.EmbeddedPageSubApp |
Here's the diff
subapp for the /travel/about/what-we-believe
page. The URL is http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:pages:diff;/magnoliaAuthor/.magnolia/versionDiff?diffViewContentHandle=/travel/about/what-we-believe&fromVersionNr=1.2&toVersionNr=1.0
. Note the reference to the diffViewContentHandle
and VersionNr
parameters
1 Comment
Viet Nguyen
We are missing documentation for the 'ssl' option which is configurable under "diff > config > ..." (in parallel with "host" and "port" configuration point). Please getting more information from our development team and update it accordingly.