Comment Plugin

<--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail thge author.
-->

Comment Plugin lets users quickly post comments to a page without an edit/preview/save cycle.

Features

Inserts an edit box into the page that allows users to type in and save comments. Comments can be made

Positioning the comment

Location relative to %COMMENT tag

%COMMENT{type="below"}%

Location relative to a TWiki anchor

%COMMENT{type="above" target="%MAINWEB%.PersonalRemarks#InsertHere"}%

Location relative to an arbitrary text string

%COMMENT{type="above" location="Flights of Fancy"}%

If you specify an anchor and a location, the anchor will be ignored.

Default templates

Customisation

• familiarity with HTML forms
• some familiarity with the TWiki templating language.

To define a comment type, you have to provide two simple template definitions in the template file; one for the prompt box, and one for the generated output. If we have a template type "mytype", these are named PROMPT:mytype and OUTPUT:mytype respectively. See comments.tmpl in the templates directory for examples.

The plugin picks up these template definitions from a standard TWiki template file, templates/comments.tmpl. This allows different templates to be defined for different TWiki skins.

Defining custom templates

This allows for several levels of customisation:

1. To override all default templates, everywhere, change comments.tmpl to include a different topic (this customisation will be lost next time you upgrade, though).
2. To add site-wide local template customisations, add them to UserCommentsTemplate (create if it does not exist yet). You can redefine the standard templates here if you want, and your definitions will override the standard definitions.
3. To override templates on a web-by-web basis, add a topic UserCommentsTemplate to the web (this will replace TWiki.UserCommentsTemplate)
4. To override templates for a specific skin, add them to TWiki.UserComments<Skin>Template (where <Skin> is the name of the skin with the first letter capitalised, e.g. Pattern)

Customisation example

%TMPL:DEF{PROMPT:myComment}%%TMPL:P{promptbox}%%TMPL:END%
%TMPL:DEF{OUTPUT:myComment}%%TMPL:P{outputoneliner}%%POS:TOP%
%TMPL:END%

Call your custom comment with:

%COMMENT{type="myComment"}%

The PROMPT template

Only the input fields of the form need be defined. The plugin automatically generates the <form> and </form> tags, unless you specify noform="on", in which case you have to provide them yourself. Note that you must define a "submit" button if you want the form to work!

Providing attribute values

<textarea rows=%rows|3% cols="%cols|50%" value="%tval|Rubbish%">

%COMMENT{type="example" cols="75"}%

<textarea rows="3" cols="75" value="Rubbish">

Special variables

EXPERT Note that when a comment is saved, the TWiki save script is invoked on the target topic, with a number of parameters provided by the comment form. Normally the CommentPlugin will provide these fields in the form, but experts can also provide the fields themselves in order to get finer control over what is submitted, or you might want to define your own HTML forms that do comment submission. The parameters that the CommentPlugin recognises are as follows:

<form method="post" action="%SCRIPTURL{save}%/%WEB%/%TOPIC%">
<input type="submit" value="I Approve" />
<input type="hidden" name="comment_action" value="save" />
<input type="hidden" name="comment_type" value="bottom" />
<input type="hidden" name="comment" value="I Approve" />
</form>

The OUTPUT template

There are also four position tags that are used to indicate where the comment should be placed, relative to the location defined in the %COMMENT tag:

Settings

<-- required for compatibility 

 

 

 Set SHORTDESCRIPTION = Allows users to quickly post comments to a page without an edit/preview/save cycle.
 
 
 Name of file in the 'templates' directory that contains the comment templates. The default 'comments.tmpl' automatically includes user templates from CommentPluginTemplate 

 Set TEMPLATES = comments
 
 
 Default template type (if not present, defaults to "below") 

 Set DEFAULT_TYPE = above
 
 
-->

Plugin Installation Instructions

• This plugin is pre-installed in most TWiki releases. However if you need to upgrade the plugin for any reason:
• Download the archive file from the Plugin web (see below)
• Unpack the archive in your twiki installation directory.
  • You may need to correct file permissions
• Run CommentPlugin_installer to automatically check and install other modules that this module depends on, and enable the plugin.
• Alternatively,
  • Manually resolve the dependencies listed below. None
• Use configure to enable the plugin

Plugin Info

Plugin Home:	TWiki:Plugins/CommentPlugin
Feedback:	TWiki:Plugins/CommentPluginDev

Related Topics: TWikiPreferences, TWikiPlugins