%META:TOPICINFO{author="PeterMasiar" date="1064941479" format="1.0" version="1.21"}%
	* post development notes in TWiki:Plugins/%TOPIC% - TWiki:Plugins/%TOPIC%Dev - TWiki:Plugins/%TOPIC%Ideas
	* Sandbox.TestComments - your playground
	* define differrent comment formats in CommentTemplates

%TOC%

---++ About

The CommentPlugin allows to quickly post comments to the page without edit/preview/save cycle. 
	* in different formats (like comments, bookmarks etc, defined on special page). 
	* in both forward and reverse chronological order (before or after the form).  
	* comment may or may not include your name and date - depending on template.
	* page is not locked during page update (very slight risk of racing condition). 

---++ Handling Page Lock

Plugin checks if page is locked for edit - in view mode, disables data input.

However, if page was read long time ago, it's possible that page was locked by another user *after* read by current browser. In this case, comments cannot be saved immediately. Instead, browser is redirected to ==oopslockedcomments.tmpl== template to report an error. Entered data are passed to error page.

To prevent edit conflict, reminder to refresh the page before typing comments is printed in place of comments. Reminder can be ignored if you loaded page recently.

On error page, user has several options:
	* *Cancel*
	* *Back* Some browsers might requery the page and comments are lost - so test how your browser behave,	copy/paste comments, or save page (with entered comments) locally.
	* Continue browsing in new window and return later. New window has name =%<nop>WEB%%<nop>TOPIC%= , and is opened using  &lt;a target="..." (no javascript), make sure that you won't try to open it twice (old window will be reused instead).

When passing entered data to ==oopslockedcomments.tmpl== to copy/pasted, Twiki uses GET, which has a limit (per browser and per web server) on lenght of URL-encoded params - so tail might be lost. Oh wow. Nothing can be done about it. :-( 

If your comments are more than couple hundred chars, and you want for sure to keep it, use edit (and better editor).

---++ Syntax Rules

	* id: This gives a unique name for a COMMENT, in case you have more than one COMMENT tag in a page. Id is mandatory with > 1 COMMENT, so you cannot give "id" only to one of COMMENTs - all need ids.
	* mode: template name. 

---++ Templates
You can have multiple templates (modes) defined on single wiki page, and even name of this template page is a parameter ( ==TEMPLATE== ): see Plugins/CommentTemplates for example.

Within template page, modes are set as header1 level. Each header has 3 header2 subheaders (which are supressed from TOC): INPUT, OUTPUT, and END. Don't worry: just copy-paste some existing mode. :-)

In INPUT section, you can use {COMMENT}{URL}{LINK} for data transfers, and 

	* common input/output parameters: {COMMENT}{URL}{LINK}
	* INPUT can use also 
		* {DISABLED} set to ='DISABLED'= when cannot comment
		* {LOCKMSG} message
		* {ID} id of comment (blank, if default)
	* OUTPUT can use also:  
		* sign with {USERNAME}{DATE} 
		* direction of growth:{GROWHEAD} or {GROWTAIL}
	* all {} will be converted to &lt;> 


---++ Settings

	* Description:
		* Set SHORTDESCRIPTION = Allows edit page without edit/preview/save cycle
	* "please refresh" message prevent edit conflict
		* Set REFRESH = works OK (refresh)
	* templates
		* Set TEMPLATE = Plugins/CommentTemplates
	* default mode (if none given)
		* Set MODE = after

---+++ Plugin Installation Instructions

*TWO WARNINGS*

	* *WARNING 1*: Anybody can refactor text added via Comments, just like any other page.  CommentPlugin knows nothing about what you've done once you have posted your comments.
	* *WARNING 2 (Installation warning)*: Because Plugin API have no capability to handle form processing (saving the data), I was left with no recourse but to create a =savecomment= script in the bin directory.  Formatting part is handled via saveComment subroutine in plugin, and checking simmilar to page edit are performed. 

	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
| *File:* | *Description:* | 
| ==data/Plugin/%TOPIC%.txt== | Plugin doc page (this page) | 
| ==data/Plugin/CommentTemplates.txt== | Plugin templates | 
| ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module | 
| ==templates/oopslockedcomments.tmpl== | error message when page is locked by another user | 
| ==bin/savecomment== | Plugin save script (*HACK*) - should be included into another - preferably =savemulti= | 

	* Check this page here to make sure the installation was successful
	* Test if the plugin is correctly installed:

If installed correctly, you should see a 4 "Comment" form fields below here, not
 the meta tag.  Feel free to use this sequence of comments as a way to test the
"behaviour" of multiple comments with multiple modes.  But please test it in ano
ther topic, preferably in the [[%TESTWEB%.%HOMETOPIC%][%TESTWEB%]] Web :) :

%COMMENT{mode="before" id="first"}%

%COMMENT{mode="after" id="second"}%

%COMMENT{mode="before" id="third"}%

%COMMENT{mode="after" id="fourth"}%
----

---+++ Plugin Info

|  Plugin Author: | v1.0 David Weller v2.0 Peter Masiar|
|  Plugin Version: | 30 Nov 2001 |
|  Change History: | 30 Nov 2001: Initial version<br> 4 Dec 2001: 1.01 release, changed name to CommentPlugin, added $button var, changed textarea WRAP setting to "soft"<br> 24 Feb 2002 added a few more user requests, made "English" text configurable <br> 5 March 2002  Bug fixes<br>Jon Lambert created oopslockedcomments.tmpl template<br>15 July 2003: Peter Masiar added "reminder" parameter and feature to pass comments to oopslockedcomments.tmpl template to copy-paste later |
| | 23 Sep 2003 Peter Masiar: 80% rewrite/refactor, adding templates |
|  CPAN Dependencies: | None |
|  Other Dependencies: | None |
|  Perl Version: | 5.0 |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

-- David Weller - 05 Mar 2002 <br>
-- User.PeterMasiar - 15 Jul 2003,  23 Sep 2003
