%META:TOPICINFO{author="ProjectContributor" comment="" date="1738771920" format="1.1" version="1"}%
%META:TOPICPARENT{name="Plugins"}%
---+ History Plugin

%FORMFIELD{"Description"}%.

The output can arbitrarily be formatted. An example for a Wikipedia-like history is included.

When using PatternSkin enabling the !HistoryPlugin changes the "History" link in the bottom action bar so it opens a page with a nice user interface where you can select the versions to compare.

With other skins for Foswiki you will need to tweak the templates.

If [[Foswiki:Extensions.CompareRevisionsAddOn][CompareRevisionsAddOn]] is installed and activated the "History" user interface will allow you to choose how the changes are rendered (interweaved vs side-by-side, and context).

If [[Foswiki:Extensions.RevCommentPlugin][RevCommentPlugin]] is installed and activated the "History" page will show the comments entered for each revision.

This plugins is designed to work together with !CompareRevisionsAddOn and !RevCommentPlugin but works well on its own or with just one of the two other plugins.

---++ Syntax Rules
Syntax: =%<nop>HISTORY{ _attributes_ }%=

%INCLUDE{"VarHISTORY" section="history_attributes"}%

---++ Custom settings:

If the preference variable =HISTORYPLUGIN_NREV= is set,  it overrides the default number of revisions shown in history when the topic =History= link is
selected.  For example, the following setting changes the revisions shown to 5.   Copy this setting into a topic to enable it for a pariticular topic,
user, Web, or site wide.   See [[%SYSTEMWEB%.PreferenceSettings]].

<verbatim>
   * Set HISTORYPLUGIN_NREV = 5
</verbatim>

---++ Examples

The call %<nop>HISTORY% shows a simple list of available revisions like%BR%
<pre>
r3 - 17 Feb 2005 - 09:56 - AnUser
r2 - 31 Dec 2004 - 10:22 - AnotherUser
r1 - 15 Nov 2003 - 01:23 - YetAnotherUser
</pre>

For a more complex example see the attached =oopshistory.tmpl= which also allows the comparison of two selected revisions.

Example screenshot of the topic history with !HistoryPlugin enabled and working with !CompareRevisionsAddOn and !RevCommentPlugin.

<div class="foswikiImage"><img src="%ATTACHURLPATH%/screenshot.png" alt="screenshot" width='785' height='592' /></div>

---++ 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 -&gt; "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!)
<verbatim>
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
</verbatim>

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.


Test if the installation was successful:
   * Here should appear the history of this document inline:
     %HISTORY{"r1.$rev - $date - $wikiusername"}% <!-- -->
   * [[%SCRIPTURLPATH{oops}%/%USERSWEB%/%WIKIUSERSTOPIC%?template=oopshistory][Show the history of %USERSWEB%.%WIKIUSERSTOPIC%]]

---++ Dependencies
<table border="1" class="foswikiTable"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Foswiki::Plugins::ZonePlugin</td><td align="left">&gt;=1.0</td><td align="left">Required. required for Foswiki < 1.1</td></tr></table>

---++ Change History
%TABLE{columnwidths="7em" tablewidth="100%"}%
|  05 Feb 2025: | 1.21 Foswikitask:Item15453: properly implement HISTORYPLUGIN_NREV |
|  16 Nov 2020: | 1.20 Foswikitask:Item14992: always display date _and_ times of revisions; clean up templates |
|  22 Jan 2018: | 1.14 Foswikitask:Item14471: HistoryPlugin not properly rendering date tokens.<br/>\
                       Foswikitask:Item14605: Unescaped brace in Regular Expression,   Perl 5.27.8. |
|  08 Sep 2015: | 1.13 Remove RevCommentPlugin hooks from the templates. |
|  15 Mar 2015: | 1.12 Version released with Foswiki 2.0 Foswikitask:Item12881: Add HISTORYPLUGIN_NREV setting. |
|  28 Nov 2012: | 1.11 Version released with Foswiki 1.1.6. Change to perl version strings |
|  11 Apr 2011: | 1.10 Version released with Foswiki 1.1.3. Only a minor change related to how the plugin is being upgraded |
|  13 Mar 2011: | 1.9 Arthur Clemens: added parameter =versions= as a more versatile alternative to =rev1=, =rev2=, =nrev= and =reverse=. |
|  13 Mar 2011: | 1.8 Arthur Clemens: fix rendering of =REVINFO= date and time parameters; add unit tests. |
|  27 Dec 2010: | 1.7 Arthur Clemens: update of screen layout. |
|  31 Jul 2010: | 1.6 Paul Harvey: Foswikitask:Item9415 - Documentation updates |
|  09 Feb 2009: | 1.5 Kenneth Lavrsen: Small cosmetic updates. Changed the author name to non liked to avoid bogus links to Main.loginname. Changed some CSS names to Foswiki that I missed in 1.4 |
|  08 Dec 2008: | 1.4 Kenneth Lavrsen: Changed the author to myself. !JChristophFuchs is the original author but announced in 2006 that he no longer maintains this plugin. So now I officially take the task as maintainer. Plugin is changed to Foswiki namespace and tested and works under Foswiki 1.0.0 |
|  09 Dec 2007: | 1.3 Kenneth Lavrsen: Restored the features that were lost in revision 1.1 including: Showing comments made by !RevCommentPlugin, selection of render styles "interweave" and "side by side" provided by !CompareRevisionsAddOn, and link to rdiff history. Restored compatibility with older releases, which means removing the dependency of 4.2 only CSS feature. Updated the default rev format to 4.X format. |
|  13 Nov 2007: | 1.2 Michael Daum: removed cruft from plugin, \
                  updates to use modern APIs, \
                  added some more flexibility to create a diff interface, \
                  removed plugin topic options |
|  07 Nov 2007: | 1.1 Arthur Clemens: improved user interface.  |
|  19 Jan 2007: | 1.002 Corrected coding error that causes the plugin to fail with HISTORY tag in topic |
|  9 Apr 2006: | 1.001 Updated for new <nop>PatternSkin |
|  17 Feb 2005: | Initial version |

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Foswiki:Main.KennethLavrsen"}%
%META:FIELD{name="Version" title="Version" value="1.21"}%
%META:FIELD{name="Release" title="Release" value="15 Mar 2026"}%
%META:FIELD{name="Description" title="Description" value="Shows a complete history of a topic"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/distro"}%
%META:FIELD{name="Copyright" title="Copyright" value="2006, !JChristophFuchs; 2008-2025 Kenneth Lavrsen and Foswiki Contributors"}%
%META:FIELD{name="License" title="License" value="GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]])"}%
%META:FIELD{name="Home" title="Home" value="https://foswiki.org/Extensions/HistoryPlugin"}%
%META:FIELD{name="Support" title="Support" value="https://foswiki.org/Support/HistoryPlugin"}%
%META:FILEATTACHMENT{name="screenshot.png" attr="h" comment="" date="1738771920" size="72043" user="ProjectContributor" version="1"}%
