DiffPlugin

Compare difference between topics and revisions

Description

This plugin implements a way to display the difference between revisions of the same topic or between two distinct topics. This adds YADT (yet another diff tool) to those previously available, i.e. Foswiki's core rdiff as well as the CompareRevisionsAddOn's compare tools. In contrast to previous work, DiffPlugin tries to display differences in a way users really can see what the difference actually is. It takes particularly care of any kind of meta data stored in a topic and diff these individually. DiffPlugin implements a %DIFF macro so that you can use it in wiki applications easily.

It integrates well with AngularSkin/AngularPlugin so that browsing among differences using the "tape-recorder" navigation feels most natural while going forward and backwards between revisions.

Examples

You type:

%DIFF{
   oldtopic="%SYSTEMWEB%.UserForm" 
   newtopic="%USERSWEB%.UserForm"
}%

You get:

Syntax

DIFF

The %DIFF macro is mostly driven by defaults in the diff.tmpl template. Each parameter has got a named definition there being used as a fallback in case the parameter wasn't specified as part of the %DIFF macro.

Parameter	Description	Default
aftertext	text to be appended to the output	diff::aftertext
beforetext	text to be displayed before any output	diff::beforetext
context	number of lines around a difference to display in addition to the difference itself	2
exclude	list of parts to exclude from being diffed, e.g. parent, form, fields, attachments, preferences, listy
footer	footer of a diff table	diff::footer
format	row of a diff table	diff::format
header	header of the diff table while iterating over all differences of a specific type	diff::header
meta_format	format to be used to display meta data	diff::meta_format
newrev, rev	revision of the newtopic to diff	latest revision of newtopic
newtopic	name of the topic on the right handside	oldtopic
no_differences	message to be displayed when no differences have been found	diff::no_differences
offset	alternative way to specify the number of revisions to diff: either use oldrev and newrev, or use rev and specify an offset into the revision history to diff	1
oldrev	revision of oldtopic to diff	latest revision of oldtopic
oldtopic	name of the topic on the left handside	current topic
separator	separator between rows of a diff table	diff::separator

The format strings can take a number of variables refering to the properties of the objects being processed:

• $oldtopic: topic name (without the web name) of oldtopic
• $oldweb: web name of oldtopic
• $oldrev: revision number of oldtopic
• $maxoldrev: maximum numbers of revision in oldtopic
• $oldauthor: author of the revision of oldtopic being processed
• $olddate: date when $oldauthor edited revision oldrev of oldtopic

• $newtopic: topic name (without the web name) of newtopic
• $newweb: web name of newtopic
• $newrev: revision number of newtopic
• $maxnewrev: maximum numbers of revision in newtopic
• $newauthor: author of the revision of newtopic being processed
• $newdate: date when $newauthor edited revision newrev of newtopic

• $offset: offset between $oldrev and $newrev
• $maxrev: alias for $maxnewrev
• $prevrev: previous revision id
• $nextrev: next revision id
• =$exclude: parts that are excluded from diffing

• $old: displays the difference of the current row being formatted in the column left column
• $new: displays the difference of the current row being formatted in the column right column
• $action: the kind of difference between $old and $new, can be "changed", "removed", "append" or "unchanged"
• $index: row being diff'ed currently
• $name: formfield filed name when diff'ing a DataForm or any other custom meta data with a "name" attribute
• $type: type of data being proccessed, can be "TEXT","TOPICINFO" or "TOPICPARENT", "FORM", "FIELD", "FILEATTACHMENT", "PREFERENCES" or the registered identifier of custom meta data

DIFFCONTROL

The %DIFFCONTROL lets you control a %DIFF happening on the same page. While you might specifiy all aspects of the diff directly in the %DIFF macro the %DIFFCONTROL lets you do so independently somewhere else on the page. I.e. it is not performing the diff operation itself. It rather displays control elements used to navigate between other diffs, like jumping to the previous or next diff following the current one. By default the appearance of diff controls are configured by the diff::control part of the diff.tmpl template file part of this extension. You might still decide to override those using the following parameters:

• temlpate: the template to read controls from, defaults to diff::control
• format: a format string to specify a diff control explicitly

Note that when format is given template is ignored. template basically is the name of a template to be used as a format. The format string then makes use of above variables.

Configuration

DiffPlugin comes with two scripts that may be used in your web-server environment - diff and diffauth - that can be used similar to rdiff and rdiffauth. No additional provisions are required when using FastCGIEngineContrib or any other persistent-perl environment where Foswiki's {SwitchBoard} mechanism is used to schedule the diff action to this plugin.

To integrate DiffPlugin into the installed skin you may replace any call to rdiff with diff, or enable the {PatchDiffScript} to automatically replace any use of the rdiff or compare scripts with a call to diff.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Algorithm::Diff	>=0	Required
Algorithm::Diff::XS	>=0	optional

Change History

27 Nov 2019	fixed js error in diff interface
12 Nov 2019	improve ui diffing revisions; added option to exclude certain parts; log diff event
25 Oct 2018	implement a separate DIFFCONTROL macro; separate diff.tmpl and diffview.tmpl
11 Jun 2018	fix changes not displayed under certain conditions
09 Jan 2018	throw an access exception instead of showing an inline error diffing revisions
01 Jun 2016	initial release