TIP FieldHistoryPlugin is not installed on Foswiki.org.


Record the history of a formfield inside the topic text

FieldHistoryPlugin is a plugin that enables recording the history of changes of a formfield within the same topic.

Each time a page is saved, the plugin will compare the old and new value of the specified formfield. If the value has changed and it is not empty, the FIELDHISTORY macro will replace itself with the text specified in the format parameter.

Normally you will include the value of the changed field ($value) and you will include the macro itself ($macro).

By placing the $macro at the beginning of the format string, the history will be added on top of the existing history. If you place the $macro at the end of the format string, the history will be appended below the existing history.

The macro also accepts $wikiname, $date, and $time in the format string as well as the normal FormatTokens like $n.

Example which records the history of changes to a field called "Status".

%FIELDHISTORY{field="Status" format="$n()---+++ Status update by $wikiname $date - $time$n()$value$n()$n()$macro"}%

The idea of the plugin is to enable an easy way to enter regular status updates in a formfield, and recording the history of these status changes inside the topic itself.

Syntax Rules

FIELDHISTORY -- record the history of a formfield inside the topic text

The %FIELDHISTORY% variable is handled by the FieldHistoryPlugin


Parameter Description Default
"..." Unnamed parameter is not used in this macro  
field Name of a formfield used in the topic ''
format Format of status update added when the formfield named defined by field changes. Use the parameter tokens listed below ''

Parameter Tokens in format="..." parameter

Name: Expands To:
$value The new value of the changed formfield. New lines in the formfield value are replace by an html break to preserve the viewed format of the formfield
$macro The FIELDHISTORY macro including all the parameters.
$date The current date in the format defined for the server
$time The current time in the format defined for the server
$wikiname The wikiname of the current user

  • In addition you can use all the standard format tokens with the format parameter. See below.

Standard Tokens for format parameter

Name: Expands To:
$n or $n() New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar

TIP Most macros accept parameter strings which are split over multiple lines. This is usually more readable than using $n tokens. If you are familiar with sectional includes, you might also consider nested sectional includes to hold the newline content outside of the parameter string entirely.

TIP Note that newline is not a line break. The browser will wrap the lines together. If you require a line break, displaying the results on two lines, use %BR%. Or use two consecutive newlines to create a TML "Paragraph".

$nop or $nop() Is a "no operation". This token gets removed; useful for nested search
$quot Double quote (") (\" also works)
$percent Percent sign (%) ($percnt also works)
$dollar Dollar sign ($)
$lt Less than sign (<)
$gt Greater than sign (>)
$amp Ampersand (&)
$comma Comma (,)


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. Use "Find More Extensions" to get a list of available extensions. Select "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 http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Change History:  
1.0 (07 Dec 2015) Initial release
Dependencies: None
Topic revision: r1 - 08 Dec 2015, KennethLavrsen - This page was cached on 12 Jan 2018 - 17:56.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License