Comment Plugin

Features

• in different formats (as defined by a template),
• in both forward and reverse chronological order,
• signed or unsigned, dated or undated (as defined by a template),
• in other topics, or other positions within the current topic.

Syntax

Parameters

• The following standard attributes are recognized

  Name	Description	Default
  type	This is the name of the template to use for this comment. Comment templates are defined in a Foswiki template - see Customisation, below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE preference setting.	below
  default	Default text to put into the prompt.
  target	Name of the topic to add the comment to	the current topic
  mode	For compatibility with older versions only, synonymous with type
  nonotify	Set to "on" to disable change notification for target topics	off
  noform	Set to "on" to disable the automatic form that is generated around your comment prompt if you don't provide a FORM template. See CommentPluginExamples:noform for an example.	off
  nopost	Set to "on" to disable insertion of the posted text into the topic.	off
  remove	Set to "on" to remove the comment prompt after the first time it is clicked.	off
  button	Button label text	Add comment

Positioning the comment

Location relative to %COMMENT tag

%COMMENT{type="below"}%

Location relative to an anchor

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

Default templates

Customization

• familiarity with HTML forms
• some familiarity with the Skin Templates.

Defining custom templates

1. To override all default templates, everywhere, change comments.tmpl to include a different topic (this customization will be lost next time you upgrade, though).
2. To add site-wide local template customizations, 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 System.UserCommentsTemplate)
4. To override templates for a specific skin, add them to System.UserComments<Skin>Template (where <Skin> is the name of the skin with the first letter capitalized, e.g. Pattern)

%COMMENT{
   type="blogpost"
   templatetopic="BlogPostCommentTemplate"
   target="%TOPIC%"
   button="Add comment"
}%

Templates are picked up by following the standard rules for locating template files. Note that you can use %TMPL:INCLUDE to include other files of templates.

Customization example

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

%COMMENT{type="myComment"}%

The PROMPT template

The FORM template

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 macros

<form method="post" action="%SCRIPTURL{restauth}%/CommentPlugin/comment" >
<input type="submit" value="I Approve" />
<input type="hidden" name="topic" value="%WEB%/%TOPIC%" />
<input type="hidden" name="redirectto" value="%WEB%/%TOPIC%" />
<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>

Customisation example with custom form template

This method has critical differences from the version shipped with Foswiki 1.1.4! (Identified by )

• In the form, the action must be %SCRIPTURL{"rest"}%/CommentPlugin/comment. The save script used in previous versions will not work.
• In the form, the topic must be set to a valid, existing Web.Topic. topic is validated by the rest script which will reject the request if invalid.
• In the form, if the target topic will be provided by user input, use the comment_target input field to identify the target, otherwise it defaults to topic setting. comment_target is more flexible and can omit the Web part.
• In the form set the location of the prompt with %COMMENTPROMPT%; the prompt will be positioned here.
• In %COMMENT use parameter noform="on"
• In %COMMENT use parameter templatetopic to point to the topic with the form template

%TMPL:DEF{FORM:example}%
<form method="post" action="%SCRIPTURL{rest}%/CommentPlugin/comment" enctype="application/x-www-form-urlencoded" name="examplecomment" id="examplecomment">
<input type="hidden" name="topic"  value="%BASEWEB%/%BASETOPIC%" /> 
<input type="hidden" name="redirectto" value="%BASEWEB%.%BASETOPIC%" />
%COMMENTPROMPT%
</form>
%TMPL:END%

%COMMENT{
   type="example"
   templatetopic="%SANDBOXWEB%.CommentPluginTemplateExample"
   target="%TOPIC%"
   button="Add comment"
}%

The OUTPUT template

• %DATE% Signature-format date VarDATE
• %SERVERTIME% See VarSERVERTIME
• %GMTIME% See VarGMTIME
• %USERNAME% Base login name - VarUSERNAME
• %WIKINAME% Wiki name - VarWIKINAME
• %WIKIUSERNAME% Wiki name with prepended web - VarWIKIUSERNAME
• %URLPARAM{...}% - Parameters to the current CGI query - VarURLPARAM
• %NOP% No-op - VarNOP

%TMPL:DEF{outputoneliner}%   * %URLPARAM{"comment" encode="$encodeguest"}% -- %WIKIUSERNAME% - %GMTIME{"$day $month $year"}%%TMPL:END%

Custom access controls

Caution If you configure this plugin to use COMMENT permission instead of CHANGE, you should ensure that every web has the desired default permission by configuring ALLOWWEBCOMMENT or DENYWEBCOMMENT in every WebPreferences topic. You should also configure appropriate defaults in the _default Template web. If default permissions are not configured, then commenting will be permitted.

Settings

Installation Instructions

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

1. Install the Foswiki:Extensions/ActionTrackerPlugin;
2. Put the CommentPlugin before the ActionTrackerPlugin in the {PluginsOrder} configuration option (in configure)

Upgrade Instructions

• The plugin uses a rest handler to update topics. By default this script does not require authentication, and can now permit anonymous commenting. Examine the http://biostat1478.dhcp.mc.vanderbilt.edu/foswiki/bin/configure ( Security and Authentication tab, Login sub-tab ) configuration {AuthScripts} setting, and the scripts requiring authentication in the Apache configuration.
• The plugin no longer processes %COMMENT macros during save. If you have developed any forms using the noform and templatetopic examples they must be revised.

Info