Contributors Plugin

Show contributors of all revisions of a given topic; useful for licenses that require attribution

Overview

This plugin gives a variable (%CONTRIBUTORS%) that will show information about past edits of a topic, and allows:

  • showing only up to a give revision
  • showing only a given number of lines
  • using a custom format
  • using a custom header.

The %CONTRIBUTORS% variable can be used in templates to automatically display who has edited a page and when.

Included with the plugin is a page (WebContributors) that allows the user to access the contributor history via a regular URL.

The WebContributors page is useful when publishing information with a license that requires attribution, such as several of the Creative Commons licenses. The people who create derivative works can then put a URL that embeds the web name, topic name, and the current revision number in their attribution notices.

Syntax Rules

Using the %CONTRIBUTORS% variable alone will expand to show the author, revision, and date of each edit of the current topic. Here's what it looks like:

The following parameters to %CONTRIBUTORS% are also allowed:

Parameter Default Description
web current web which web the topic of interest is in
topic current topic which topic to give change history for
rev current revision latest revision to show information for
format " * $author -- Revision $rev on date $date \$n"; format for each contributor line
header (none) string to print before printing the contributors output
nodups (none) if set to "on", suppress duplicate lines

In the format string, the user can use the following variables:

Variable Expands to
$author the person who made that specific change (linked to their TWiki user profile page)
$date the date in GMT time
$rev the revision number (linked to that revision of the page)
$n \n

In the header string, the user can use $n but no other variables (at the moment).

To use WebContributors, you pass a URL with the information you want in the query string. Note, however, that there are some differences:

  • Instead of using topic, you must use page. If you use topic, then bin/view will display that topic instead of displaying WebContributors for that topic.
  • Instead of using rev, you must use revision. If you use rev, then bin/view will expand that revision of WebContributors instead of expanding the current version of WebContributors.

Plugins Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %CONTRIBUTORSPLUGIN_SHORTDESCRIPTION%

  • One line description which is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Show contributors of all revisions of a given topic; useful for licenses that require attribution

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Examples

Write %CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7"}% to get:

Write %CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7" rev="1.20"}% to get:

Write %CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7" rev="1.20" format=" * $author$n"}% to get:

Write %CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7" rev="1.20" format=" * $author$n" nodups="on"}% to get:

Write %CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7" rev="1.20" format="|$author|$date|$rev|$n" header="|*Author*|*Date*|*Revision*|$n"}% to get:

Author Date Revision
PeterThoeny Tue, 20 Nov 2001 07:30:55 GMT 1.20
PeterThoeny Fri, 14 Sep 2001 06:10:21 GMT 1.19
PeterThoeny Sun, 09 Sep 2001 08:05:49 GMT 1.18
MikeMannix Sat, 01 Sep 2001 07:20:30 GMT 1.17
PeterThoeny Fri, 17 Aug 2001 06:46:46 GMT 1.16
JohnTalintyre Wed, 08 Aug 2001 08:59:09 GMT 1.15
JohnTalintyre Tue, 07 Aug 2001 15:47:41 GMT 1.14

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip ContributorsPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/ContributorsPlugin.txt Plugin topic
      data/TWiki/WebContributors.txt Page to allow getting revision history from a URL
      lib/TWiki/Plugins/ContributorsPlugin.pm Plugin Perl module
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Check the above examples to see if the plugin operates as expected.

Plugin Info

Plugin Author: TWiki:Main:DuckySherwood
Copyright: © 2004 TWiki:Main.DuckySherwood
© 2008-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2011-04-06
Change History:  
2011-06-04: TWikibug:Item6701: Small doc fix; change code from "use vars" to "ours" -- TWiki:Main.PeterThoeny
2011-03-09: TWikibug:Item6638: Doc fixes; changing TWIKIWEB to SYSTEMWEB -- TWiki:Main.PeterThoeny
2004-12-04: Initial version
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.0
TWiki:Plugins/Benchmark: GoodStyle 100%, FormattedSearch 100%, ContributorsPlugin 100%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ContributorsPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ContributorsPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ContributorsPluginAppraisal

Related Topics: WebContributors, TWikiPlugins, AdminDocumentationCategory

This topic: TWiki > ContributorsPlugin
Topic revision: r1 - 2011-06-05 - TWikiContributor
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.ContributorsPlugin.