MetaCommentPlugin

An easy to use comment system

This is YACS (yet another comment system) which tries to

• (a) be easy to use,
• (b) scale up to lots of comments
• (c) provide different layouts and commenting requirements and
• (d) implement a moderation workflow for comments before they go live.

MetaCommentPlugin allows to easily add commenting to any topic. Discussiosn can either be displayed in linear or threaded mode. Different comment styles and layouts can easily be created and switched from one to the other. Comments can be edited and deleted inline easily. Commenting can be enabled independently from the normal change access rights to a topic while they are still stored as meta data to a topic. That way a keyword search matching on different comments of the same discussion will generate a hit on the discussion itself in a natural way.

Screenshot

Data Model

Each comment is stored into a META:COMMENT field of a topic with properties

• name: id of the comment, used in ref for threaded comments
• author: WikiName of the author of this comment
• date: timestamp when this comment was created
• modified: timestamp when this comment was last modified
• ref: name of another comment within the same thread this comment is a subcomment of
• text: the comment text
• title: title text of this comment

Configuring the comment system

Using MetaCommentPlugin on NatSkin

The easiest way to switch on commenting on a page is when using it together with NatSkin. When opening the topic editor, there's a "Settings" tab that allows you to switch on and off commenting, switch between different commenting styles as well as configure moderation.

Using MetaCommentPlugin on PatternSkin

On a standard PatternSkin install you will have to use preference variables to control the system. First, to enable commenting add the metacomment skin overlay to your SKIN variable in SitePreferences.

   * Set SKIN = metacomment, pattern

Display settings

To display the comment interface like shown above you need to set the preference variable:

   * Set DISPLAYCOMMENTS = on

There are a couple of formats how comments are displayed on the topic:

   * Set COMMENTFORMAT = threaded

Other values:

• linear: list comments in linear order, i.e. there are no replies to comments directly
• threaded (default): nested commenting; allows to reply on a reply
• reverse: list comments in linear order in reverse twitter-like fashion
• insidetab: list comments inside a tab at the bottom of the page; only available when used together with TopicInteractionPlugin)

A discussion can be either open or closed:

   * Set COMMENTSTATE = open

By setting this to closed comments gathered so far are still listed while the form to add more comments is hidden

These preferences can of course be set per topic or added to the WebPreferences in case you want to enable commenting on all of the web.

Below each comment there is a set of infos that can be switched on and off as desired.

This setting ...

   * Set COMMENTVOTING = on/off

enables voting per comment using the Foswiki:Extensions/LikePlugin (defaults to on when LikePlugin is installed). Users will be able to vote up or down each comment to indicate their level of agreement during a discussion.

Finally, there is a so called "permlink" that lets you share a link to a specific comment in an email or so. However this feature is not desired. Use this to switch it of then:

   * Set COMMENTPERMLINK = on/off

Permissions

MetaCommentPlugin separaters permission to comment on a topic from plain change access rights of a topic. That way you may restrict write access to a topic while still open it up for commenting to a wider audience. This is done by using a separate COMMENT access control list.

Given the current topic is write restricted only allowing the original author to make changes, the following setting will permit commenting:

   * Set ALLOWTOPICCOMMENT = <comma separated list of users and/or groups>

You may also want implement a minimal set of protection using

   * Set ALLOWYWEBCOMMENT = <comma separated list of users and/or groups>

and / or

   * Set DENYWEBCOMMENT = <comma separated list of users and/or groups>

in the WebPreferences.

See AccessControl for more information on setting up access control lists for various use cases.

Anonymous commenting

Anonymous commenting is disabled using the {MetaCommentPlugin}{AnonymousCommenting} configuration setting by default. This will protect your site from guests spamming your pages. When this flag is disabled, users will at least have to log in to be able to comment. Normal access control rules then still apply.

Contrary to the normal Foswiki access control mechanism it does not suffice to set the ALLOW rules for a guest accordingly. It is required to at least enable the {MetaCommentPlugin}{AnonymousCommenting} flag in your site configuration. Once enabled, you are still able to block anonymous commenting using the normal access control rules per web and/or topic.

Moderation

Moderating comments allows you a bit more control of which comments are approved to be okay to be displayed to the public. This is mostly used on public environments to hide comments until they are approved by a list of moderators. Only the original author and moderators will see unapproved comments. For everybody else, unapproved comments are hidden until they are approved.

To enable moderation set the COMMENTMODERATION preference setting (defaults to off):

   * Set COMMENTMODERATION = on

The list of people allowed to moderate a comment is configured by using Foswiki's permission system using the MODERATE role. So to configure moderators per topic use:

   * Set ALLOWTOPICMODERATE = <comma separated list of users and/or groups>
   * Set DENYTOPICMODERATE = <comma separated list of users and/or groups>

Or use a per web configuration in the WebPreferences using

   * Set ALLOWWEBMODERATE = <comma separated list of users and/or groups>
   * Set DENYWEBMODERATE = <comma separated list of users and/or groups>

See AccessControl for more information on setting up access control lists.

METACOMMENTS

Renders a discussion on a given topic

%METACOMMENTS{
  topic="..."
  ...
}%

Parameters:

• topic: the topic to render the discussion for, defaults to the current topic
• web: the web where to search for meta comments
• search: a search expression to find matching topics whose meta comments are extracted
• header: string prepended to the output
• footer: string appended to the output
• format: format string used to render each comment, defaults to <h3>$title</h3>$text
• template: template to be used instead of the inline format parameter
• separator: separats the list of comments
• subheader: string prepended to the list of subcommnets, defaults to <div class='cmtSubComments'>
• subfooter: string appended to the list of subcommnets, defaults to </div
• subformat: format string used for subcomments, defaults to the value of the format parameter
• ref: only list comments that are a subcomments of the given comment
• skip: number of comments to skip in the list, useful for pagination
• limit: maximum number of comments to list, useful for pagination
• singular: title used when only one comment is present, defaults to One comment
• plural: title when there are more than one comment, defaults to "$count comments
• mindate: minimum date of a comment to be displayed
• maxdate: maximum date of a comment to be displayed
• threaded: switch on/off threaded rendering, comments will be rendered recursively
• sort: specify the way comments are sorted; possible values: name (default), date, modified, author, likes (if LikePlugin is installed)
• reverse: switch on/off reverse order of sorted comments

When rendering a comment, the following variables can be used in the format strings:

• $author: the name of the user that wrote this comment
• $state: the state of this comment
• $count: the total number of comments
• $ismoderator: true/false if the current user is allowed to moderate the comments or not
• $timestamp: the date when this comment was created; format in epoch seconds
• $date: the date when this comment was created in Foswiki's default time format
• $modified: the date this comment was last modified
• $isodate: the date when this comment was last modified in iso format
• $evenodd: expands to even or odd while formatting all comments in the list; useful to implement zebra striped comments
• $id: the unique identifier of this comment (stored in the name attribute of the comment)
• $index: the running number of the current comment while rendering a list of comments
• $ref: the identifier of the comment this one is a reply to; used in threaded commenting mode
• $text: the actual comment
• $summary: a short summary of the text (the first 100 characters)
• $title: the title of the comment
• $subcomments: expands to the list of all comments that are a reply to the current one
• $web: the web this comment is in
• $topic: the topic this is a comment of
• $permlink: a link to this comment
• $isnew: boolean flag indicating whether the current user hasn't read a newly created comment yet
• $isupdated: boolean flag indicating whether the current user hasn't read an updated comment yet
• $likes: number of likes
• $dislikes: number of dislikes

Example:

Use this to render a list of all unapproved comments in a web:

%METACOMMENTS{web="Sandbox" 
  search="1" 
  header="| *Comment* | *Topic* | *Comment* | *Author* | *Date* | $n"
  format="| [[$permlink][Comment$id]] | [[$web.$topic]] |$title $summary | <nobr>[[%USERSWEB%.$author]]</nobr> | <nobr>$date</nobr> |$n"
  footer="<span class='foswikiAlert'>$count</span>"
  sort="date"
  reverse="on"
  state="unapproved"
}%

RSS feeds

By default every page has got a separate RSS feed with all comments in it. This allows to monitor individual discussions. To monitor all discussions in a web use the metacommmentrss template. Alternatively the webcomments section below renders a link to it with an RSS icon. Call it using:

%INCLUDE{"%SYSTEMWEB%.MetaCommentPlugin" section="webcomments"
  THEWEB="<webName>"
  WHERE="<query>"
  LIMIT="<limit>"
}%

The parameters THEWEB, WHERE and LIMIT are optional where

• THEWEB specifies the web to search for comments, defaults to the current web
• WHERE specifies a filter on topics while searching THEWEB, defaults to 1 (means: all topics)
• LIMIT limits the number of recent comments to be listed, defaults to 10

%STARTSECTION{"webcomments"}%<a href='%SCRIPTURLPATH{"view"}%/%THEWEB{default="%BASEWEB%"}%/%BASETOPIC%?template=metacommentsrss;contenttype=text/xml;search=%WHERE{default="1"}%;limit=%LIMIT{default="10"}%' class='cmtRssFeed foswikiGrayText foswikiSmallish foswikiHideOnPrint' title='%MAKETEXT{"RSS comments feed for the [_1] web" args="%THEWEB{default="%BASEWEB%"}%"}%'>%JQICON{"feed"}% RSS</a>%ENDSECTION{"webcomments"}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

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

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Contrib::JsonRpcContrib	>=1.1	Required.
Foswiki::Plugins::RenderPlugin	>=3.1	Required.
Foswiki::Plugins::ImagePlugin	>=3.0	Required.
Foswiki::Plugins::DBCachePlugin	>=9.0	Optional.
Foswiki::Plugins::SolrPlugin	>=4.0	Optional.
Foswiki::Plugins::LikePlugin	>=1.0	Optional.
Foswiki::Plugins::ZonePlugin	>=3.1	Required. required for Foswiki < 1.1
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required for Foswiki < 2.2

Change History

28 May 2018:	5.03 - depend on new TopicTitlePlugin
05 Mar 2018:	5.01 - cleaned up templates
16 Jan 2017:	5.00 - implemented a registerCommentHandler() api to let other plugins interact with comment changes
11 Sep 2015:	4.10 - added display settings to switch on of voting and permlink
09 Sep 2015:	4.00 - added isnew/isupdated flags; optional integration with Foswiki:Extensions/LikePlugin; using new index handler architectur in Foswiki:Extensions/DBCachePlugin now
31 Aug 2015:	3.00 - simplified comment approval; fixed ACL check (Foswiki:Main/StephanOsthold); fixed substr problem together with Foswiki-2.0
27 Feb 2015:	2.90 - removing collection field form solr index handler
16 Dec 2014:	2.80 - fixed extracting substrings from unicode strings
29 Aug 2014:	2.70 - improved finding user photo
18 Mar 2014:	2.60 - fixed dependency on ImagePlugin; some css and js fixes
15 Aug 2013:	2.50 - protect comments from being edited by others; fixed error reporting using pnotify now; reject commenting when discussion is already closed; added example how to display all unapproved comments in a web; added docu how to render an rss feed of all comments in a web
13 Aug 2013:	2.40 - disable anonymous commenting by default
02 Jun 2013:	2.32 - fixed reply-modal not closing after submit
23 May 2013:	2.31 - fixed commenting using latest jquery/jquery-ui combo
14 Mar 2013:	2.30 - fixed access rights on unapproved comments being index by solr
29 Nov 2012:	2.20 - force a new revision on every comment; fixed comments by modification date; improved templates used to rendering user photos
02 Aug 2012:	2.11 - fixed german translation (Foswiki:Main/JanKrueger)
31 Jul 2012:	2.10 - unapproved anonymous comments are only visible to the same remote address for one hour; fixed jquery-ui dialogs not popping up properly; comments by moderators don't need any further approval; fixed controls not showing up sometimes
10 Jul 2012:	2.02 - properly reset modal dialogs when reusing them
07 Jul 2012:	2.01 - use less progress messages
	2.00 - replaced all simplemodals with jquery-ui dialogs
08 May 2012:	1.12 - fixed integration with PatternSkin
28 Mar 2012:	1.11 - added ability to search for all comments in a web; improved comment rendering features; added fixes for PatternSkin
10 Jan 2012:	1.10 - added german translation; added missing dependency on RenderPlugin; backwards compatibility to older foswiki engines; adjusted index handler to latest changes in SolrPlugin; improved print css; fixed js error together with newer jquery versions
10 May 2011:	1.00 - partial rewrite to use JsonRpcContrib; renamed preference COMMENTAPPROVAL to COMMENTMODERATION
20 Apr 2011:	fixed error in regular expression
15 Apr 2011:	using CPAN:JSON to properly encode json-rpc data; fixed recoding of received data to the site's own charset; improved the way photos are gathered