%META:TOPICINFO{author="frank" date="1030312260" format="1.0" version="1.2"}%
%TOC%
---
---+ development

Please use FeedbackPluginDev for development related discussion

---+ Feedback TWiki Plugin

This is a Plugin for creating and collecting comments to a page without changing the page itself. This makes sense if you want others to contribute, but still preserve clear ownership of the topic in question. I use it for my weblog, which is in fact only editable by myself.

The plugin provides a joint view of the topic and the collected comments. 

---++ user interface

The owner of the page enables the plugin. The plugin splits the text in paragraph like units and adds a button after each paragraph.

After clicking on the button a comment entry form appears and allows the reader to enter some text. Alternatively the user can double click on any paragraph if javascript is enabled.

---++ theorie of operation
Internally the comment data is stored on a separate page - which is optionally specified in the %<nop>FEEDBACK% construct see FeedbackPlugin#ExampleAnchor - inside a table:

This table has to have three columns on a single line:

|*Searchtext*|*Author*|*Comment*|

The Plugin will search for *Searchtext* and then add *Comment* and *Author* . Searchtext can be Perl Regular expressions or simple strings. 

The %<nop>FEEDBACK% construct is replaced by a form which enables you to see the page which shall be commented with or without links and directly add the comments in text fields without manually changing the table. The layout is currently a _proof of concept_ one and not designed for usablity.

I think it is somehow related to CommentPlugin and similar work. 
It was created for my private fun and now released to get feedback :) and get outstanding issues solved.

---++ Syntax Rules

(none)

---++ %TOPIC% Settings

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

	* One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
		* Set SHORTDESCRIPTION = This is a Plugin for creating and collecting comments to a page without changing the page.
 
	* Debug plugin: (See output in =data/debug.txt=)
		* Set DEBUG = 

---++ Plugin Installation Instructions

	* copy the Files at the correct locations!
		* V1.16 Stored this text inside the TWiki Web. V1.19 now uses the Plugins Web.

---++ Plugin Info

|  Plugin Author: | %TWIKIWEB%.FrankHartmann, |
|  Plugin Version: | 1.16 |
|  Change History: | 1.16 initial public release |
|						| 1.19 now using forms and http POST method |							  
|						| 1.25 paragraph mode implemented,									 javascript still missing|
|						| 1.29 Javascript implemented as suggested by Main.WoutMertens |
|  CPAN Dependencies: | none | 
|  Other Dependencies: | none |
|  Perl Version: | 5.0 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

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


---+ Example
#ExampleAnchor

A TAG %<nop>FEEDBACK% will automatically add the Comment Data to a Page named %<nop>TOPIC%Feedback or if you would like an other name:
%<nop>FEEDBACK{<nop>CommentPage="<nop>SeparatePage"}% 

---+ Known Issues
	* the %<nop>FEEDBACK% is partly expanded even within verbatim tags.
	* I am somehow unhappy having the user enter a Perl regular expression. 
	* If you enter an invalid expression this will be listed in the error.log of your web server. No user feedback currently.
	* the way the table rows are added to the page holding the comment data seems to be unclean. Currently it is file IO, without locking or TWiki routines involved.


---+ Roadmap 

A sorted list of features, which will be implemented if things go well. 

	1. paragraph mode.  The Plugin (triggered by an access of the rendering page) reads in the (external) webpage, splits it into paragraphs, wraps some javascript/html around it and display it with comments on or off. The javascript/html shall enable the entry of new comments for the current paragraph. *done*
	1. Make it look good. *NEXT*
	1. allow the web page to be commented to be an external one. 
	1. data handling
		1. show orphaned comments
		2. allow form based editing/deleting of old comments
