CommentIt Plug-in

The latest version of CommentIt is no longer released as a 'stand-alone' plugin - it is now part of the Bayly.root. If you are updating from a very early version of CommentIt - i.e. one where the link to the documentation doesn't point to this page - I recommend the following:

Disabled the CommentIt plugin (from Editors only menu choose Prefs and then PlugIns).
Delete the table at config.manila.plugins.registered.commentIt
Run the CommentIt install script (commentIt.install)
Re-enable the commentIt PlugIn.

What is CommentIt?

CommentIt lets visitors to your site append comments to the bottom of your web pages. It's simple stuff, visitors don't need to register to leave a comment; they read your page, click the comment button and tell you what is on their mind (but you can alter the default behaviour to suit yourself - read on to find out more).

Useful for sites where a full-blown discussion forum seems like overkill - or if you just want to keep comments on the page they relate to. Also good for bandwidth conservation - no need to click through ten pages to see ten comments because they are all on the one page.

It is based on the CommentIt cgi/macro I wrote a long time ago and which can be seen in action on many Web sites including: http://www.glasgowwestend.co.uk. Get the old cgi version to use on classic Frontier static sites from: http://www.ispn.gcal.ac.uk/Frontier/CommentIt/index.html. David Bayly is responsible for re-writing it as a Manila Plug-in (with a few modest tweaks from myself).

If you want to see how it works scroll down to the bottom of this page and tell me why you need/don't need this plug-in.

Features

Works on both dynamic and statically rendered Manila sites.
You can choose to be e-mailed when a new comment is added.
Comments can be restricted to editors only.
Comments can be restricted to logged in members only.
Comments can be appear to logged in members only.
You can decide what pages can receive comments and what pages can't.
Comments can appear on both stories and discussion group messages.
Templates for the input forms so you can change the text and what fields are collected, even adding additional fields.
An output template so you can design your response format.
Includes a powerful workgroups feature: only workgroup members can view messages posted by other workgroup members. Particularly useful in the educational setting.
Easy to modify the text that appears on the comment button
Administrators can now add fields to the comment form and have the results of those fields both displayed as part of the comment and sent to the administrator by email.

How to install

Follow the documentation on the Bayly.root page for installation instructions. (You can find out more about what happens when you register a Plug-in at: http://plugins.userland.com/ Though registered this does not mean that CommentIt is enabled for each site that will use it.)

To enable the CommentIt plug-in, open your Manila site in your Web browser. Make sure you are logged in as the editor. From the Editors only menu choose Prefs and then choose Plug-ins from the menu on the left hand side of the page. On the resulting page you should see a box that you can check to enable the CommentIt plug-in.Check the appropriate box and click submit. The CommentIt option will be added to your editors only menu. You will use this menu to configure CommentIt.

Macros

Add the following macros to your template just under {bodytext} macro

{commentIt.formMacro()} {commentIt.commentsMacro()}

The first puts an 'Add a Comment' button on your page and the second lists the eligible comments that have been made to this page.

If you prefer you can just add the commentIt macros to the bottom of individual pages.

The form macro has the following parameters:

buttonID which defaults to 'Add a Comment'. You can set this parameter yourself - changing the button text to anything you like, e.g.
{commentIt.formMacro(" button text ")}
membersOnlyMsg this allows you to add a heading that separates comments from the rest of the page if you set the preference for displaying comments but only members can post ( so there is no 'Add a Comment' button). So typically you might set this as follows:
{commentIt.formMacro(membersOnlyMsg: "<h3>Comments</h3>")}

the commentsMcro has the following parameters

preamble - optional string, default empty. Is placed before the first comment.
startTag - optional string, default "
". Is placed before each comment. Best left empty as the template offers more control.
endTag - optional string. Is placed after each comment. Best left empty as the template offers more control.
selectMethod - optional string literal random or default, default empty. Determines how comemnts are chsoen for display. Default means display all; random means randomly select selector within those eligible.
selector - optional string, default empty. Maximum number of comments to display in random selection.

The default display shows all comments in reverse chronological order, subject to their membership status, workgroup definitions and privacy flag. Random selects from within that set.

Preferences

Choose CommentIt from your Editors Only menu.Choose Preferences from the menu on the left hand side. The following preferences are available.

Notify webmaster of comments by Email
Notify page author of comments by Email
Use commentIt pathAtt in Site structure:
Restrict commentIt to editors:
Accept comments from logged in members only:
Show comments to logged in members only
Default value of private comment for members
Allow definition of workgroups
Protect email addresses against spam harvesters:
Static page render after comment added
Response when static rendering involved.
Static response hold time (seconds)
Input form layout for anonymous posters
Input form layout for logged in members
comment template:

I assume that most of the above preferences self-explantory - however my instinct tells me that the following preferences are not so obvious.

Static page render after comment added

CommentIt can be used on sites that are rendered to static servers. This preference is set if you would like the page to be re-rendered when a new comment is added.

Response when static rendering involved

This preference allows you to type in a message for the feedback page users will get after they add a comment to a static site. This get round the problem that the comment will not appear immediately; because the page is getting rendered to the static server in the background. Before the user is returned to the static page they are sent to a page that reassures then that their comments have been added succesfully and that they will appear shortly. The 'Response when static rendering involved' preference allows you to type in the text that visitors will see while they wait to be returned to the page they added their comment to.

Static response hold time (seconds)

Contrary to W3c guidelines CommentIt uses a client side refresh on the page that provides feedback to users who add comments to pages that are rendered to a static server. This preference allows you to set the number of seconds users have to read your message (that their comments will appear shortly) before the page refreshes back to the original URL.

Use CommentIt PathAtt in Site Structure

You are probably thinking - what the hell is that all about? Well put simply it is a way of giving you control over which pages can accept comments and which pages cannot.

It uses the fact that you can add attributes to story entries in your site structure - and have a script make use of the value of those attributes. This is a technique developed by David Bayly - co-author of this plug-in. It is a bit like setting directives when using the conventional Web site work. Sounds complicated but in practice it is very simple.

To use it you need a site structure with story entries for the pages you would like comments on. e.g.
A new Manila web site structure looks like this:


<hierarchy>

  <story name="About" pathname="about" msgNum="2" />

  </hierarchy>

If you would like to take advantage of the PathAttributes features first set 'Use commentIt pathAtt in Site structure:' to Yes in the preferences and in the site structure add commentIt="true".
Thus:


<hierarchy>

  <story name="About" pathname="about" msgNum="2" commentIt="true" />

  </hierarchy>

The default behaviour

To get the default behaviour - once you have added a page to your Site Structure you don't have to do anything; leave 'Use commentIt pathAtt in Site structure:' set to 'No' and all pages in your site structure will be able to accept comments.

Find out how to use the site structure by reading the following pages:

Thanks to David Davies who asked if comments could be added to pages that would only be visible to the person who added them. David the answer is yes. There is now an option in the comments form which you can check to make your comment visible only to yourself.

Inspect/Delete

The Inspect Delete option does just what you would expect. You are presented with a list of pages and their respective message numbers. Choose the page you are interested in and click the 'Choose' button. There is a check box next to each comment. Check those you would like to delete and click the delete button. Well that's your lot. Get in touch if you spot a bug.

Conditions of Use

If you use CommentIt don't send money - even though this would certainly increase our happiness - but do send messages of gratitude and over the top expressions of enthusiasm for commentIt - they will be graciously accepted.

Updates

28th March 2002

CommentIt.utility.applyTemplate: make test for string.multipleReplaceAll version dependent.

23rd March 2002

Optimisation : non regex version of template renderer.

Administrators can now add fields to the comment form and have the results of those fields both displayed as part of the comment and sent to the administrator by email.

Comment macros return null on /commentIt/postcomment.

28th March 2002

22 February 2002

Option for Managing Editors to see all comments even if private or in workgroup

19th February 2002

default values for members form were incorrect
posted values from comment form are converted to display form
ensure that pseudo-macro entries left in the comment form are noted as errors

16th February 2002

sort messages with comments on inspect page by descending date of most recent comment
show changes in plugin updated message on default page

1st February 2002

Implement random Number of comments from comments to a page

27th November 2001

Fix subtle interaction bug with turbocache

23 November 2001

Regex is too slow; replace wherever possible

18 October 2001

Submit buttons can be images

20 September 2001

More localisation of text on the form entry page.

August 2001

Added pref to send notification email to page author, if defined.

Users can inspect their their own comments.

Fix for bug in commentIt.inspector; don't assume country is a field anymore.

Fix for multiple delete bug in commentIt.inspector (Jim Byrne).

Add /commentit/versionhistory url - not in menu bar. interface to manilafixer text replace.

25 July 2001

Reply to in email messages.

Added posters email to body of email to site owner.

Version check on default page.

Make subjects in list from inspect, a link to the page.

Add header with link to page in comments for 1 story.

CommentIt.utility.MEditorsOnly - script to police access to maintenance pages.

CommentIt.data.websiteFragment.default - call MEditorsOnly.

CommentIt.data.websiteFragment.inspector - call MEditorsOnly.

CommentIt.prefsEdit now uses prefsSuite.browser not commentIt.presfBrowser.

Fixed bug setting pta and msgNum.

Added protect emails preference.

Stomped the "cant find message 0000" bug for once and for all.

8th April 2001

Default values from manilaextras.pathatt set to false in comment.formmacro.
In commentIt.CommentsMacro - what to display if no comment in form macro
Added #security to website fragment, editors only.

3rd April 2001

Interface to manilfixer.turbocache
Commentit.utility.nocache
Register callback in commentit.enable
(don't) de-register in commentit.disable.

28th March 2001

Erin Clerico and the missing untaint call.

13th March 2001

Allow comments on messages rather than just stories.

10th March 2001

Add preference staticrendermessage to override static is rendereing yadad ...
Make text area wrap = virtual in comments field.
Try and log to catageory of manila website name , if possible.

2nd March 2001

Added static rendering in post a comment.Provide feedback page if came from static page then return to original static page.

5th February 2001

Fixed originalurl in dynamic case now. Added staticrender preference if set, simulate render this page call from commentIt.postcomment.

4th February 2001

Fixed original url in commentit.formmacro.

16th November 2000

A change to the script CommentIt.prefs - so that new prefs will apply to the correct site.

31st October 2000

New preferences added: editors only, accept/show comments only to members, comments only visible to author.

26th October 2000

Sorted problem related to sending notification of new comments by e-mail.

23rd October 2000

Sorted problem with broken paragraphs and made e-mail address a link.

--Scott Granneman(scott at granneman dot com) from USA on 2002.06.4; 18:42:41 Uhr [permalink]
I cannot download the plugin ... if I do manage to get it, it's 0 bytes.

--sly(pat9 at hot dot ee) from Estonia on 2002.05.31; 13:17:32 Uhr [permalink]
Jo.
Sly
MySly
Mysly.KoLhOos.ee
....................

--craf(craff at hot dot ee) from estonia on 2002.03.22; 11:23:18 Uhr [permalink]
heh ...nice thing :P

--Don Saklad(don at saklad dot org) from USA on 2001.11.14; 14:42:19 Uhr [permalink]
How would you put the comment button on the Guide to Problematical Library Use?...

http://GuideToProblematicalLibraryUse.WebLogs.com

--David Bayly(webmaster at udena dot ch) from UK on 2001.09.20; 12:52:58 Uhr [permalink]
The latest version has templates for the input forms. You can change the text and what fields are collected, even adding additional fields.

There's an output template too, so you can design your response format

Latest version is in bayly root, downloadable on the page .

--Pichat(ypichat at kojito dot fr) from France on 2001.09.20; 12:02:32 Uhr [permalink]
How can i change : -Add a Comment

Hit the return key twice to create a new paragraph.- to a french version ?

Thanks

--Shaggy(scooby at doo dot com) from MysteryMachine on 2001.08.30; 18:48:51 Uhr [permalink]
Zoiks!

--David Davies(d dot a dot davies at bham dot ac dot uk) from VA on 2001.08.13; 15:46:21 Uhr [permalink]
Nice feature!

--Matt(goober at weehours dot com) from USA on 2001.07.30; 13:47:23 Uhr [permalink]
Looks pretty good

--Ian Koss(ikoss at ink19 dot com) from USA on 2001.07.25; 22:07:03 Uhr [permalink]
Hey, Matthew, do you think we could use this for Columns?

--David Bayly(dbayly at udena dot ch) from UK on 2001.05.17; 14:24:13 Uhr [permalink]
Peter yes it does render static pages. I've sent email with soem questions.

--Peter(peter dot baumgartner at uibk dot ac dot at) from Austria on 2001.05.17; 14:05:28 Uhr [permalink]
Can I use CommentIt with Frontier rednering a static site too? I tried it, but I got the messages "can't find a subtable "commentit".

--Bob(bob at bob dot com) from UK on 2001.05.5; 16:47:52 Uhr [permalink]
This is a cool plugin

--Test Spam(spam at spam dot net) from USA on 2001.04.12; 19:40:07 Uhr [permalink]
test comment. Nice plug in!