ContributorsPlugin < TWiki

---+ Contributors Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/ContributorsPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/ContributorsPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Overview

This plugin gives a variable (%<nop>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 %<nop>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  [[http://www.creativecommons.org][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 %<nop>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:

%CONTRIBUTORS%

The following parameters to %<nop>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 <b>topic</b>, you must use <b>page</b>.  If you use =topic=, then bin/view will display that topic instead of displaying WebContributors for that topic.
   * Instead of using <b>rev</b>, you must use <b>revision</b>.  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 ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>CONTRIBUTORSPLUGIN_SHORTDESCRIPTION%==

   * One line description which is shown in the %SYSTEMWEB%.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 %<nop>CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7"}% to get:

%CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7"}%

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

%CONTRIBUTORS{web="TWiki" topic="TWikiPreferences" last="7" rev="1.20"}%

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

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

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

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

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

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

---++ 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 [[%SCRIPTURL{configure}%][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 ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/WebContributors.txt== | Page to allow getting revision history from a URL |
        | ==lib/TWiki/Plugins/%TOPIC%.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 [[%SCRIPTURL{configure}%][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: | &copy; 2004 TWiki:Main.DuckySherwood <br /> &copy; 2008-2011 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2011-04-06 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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: | %SYSTEMWEB%.GoodStyle 100%, %SYSTEMWEB%.FormattedSearch 100%, %TOPIC% 100% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ WebContributors, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.AdminDocumentationCategory
This topic: TWiki > ContributorsPlugin
Topic revision: r1 - 2011-06-05 - TWikiContributor
Copyright © 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.