Reader comment may be solicited and displayed using the $$COMMENT$$ substitution directive.

JavaScript is required to view and make comments.

When included on a page two buttons are displayed. The first allows any existing comments to be viewed. It can be disabled (greyed-out) if none currently exist. The second allows any reader to compose and submit a new comment. This button may also be disabled if further comment has been closed.

The following displays some example comment and the comment submission dialog (and are moderated).

Mark Daniel Sunday, 22 Feb 2009 06:43 This is just an example comment for documentation purposes.

Mark Daniel Sunday, 22 Feb 2009 06:45 This is a second comment. Note that hard line-breaks format the text. Lines beginning with two spaces are not wrapped or pushed against the left margin allowing block-quotes and code examples. Longer lines should be wrapped at the column limit of the text area. It has been moderator approved (though this is not obvious to the reader).

~~~ waiting for moderator approval ~~~ Mark Daniel Sunday, 22 Feb 2009 06:47 ******************************** ********************************************

(completely optional and not for publication)

As a general rule a comment directive would be placed at the end of a content section (bottom of the page).

Parameters

The comment directive is moderately complex and can take several parameters. All of the button label and dialog strings have reasonable defaults. If any of the parameters are supplied empty they use the associated default.

Parameter	Description
!	An exclamation point closes further comment.  This disables the button and further submissions are ignored.
^	A caret displays the comments when the page is first accessed.  By default the button needs to be used.
_	An underscore leading parameter renders the comment text in monospace (fixed) font.
:	A full-colon makes comment strings that look like URLs into anchors (and therefore clickable).
@	The at sign results in the reader's host name being displayed both when soliciting and displaying the comment.
%	A percentage symbol indicates a format string (see Time) used to format the comment time.
+	A plus sign indicates the comment must be moderated before being available for unobfuscated general viewing (provides optional email notification).
16x80	If the parameter begins with a digit it is used to specify the number of rows and the number of columns in the comment text area.  Rows and columns are separated by a non-digit (non-dollar) character.
email=	Notification of comment submission for following email address(es).
fremail=	Local string for default commentator email address.
from=	Local string for default commentator identification.
hide=	Label for the button.
make=	Label for the button.
name=	Comment (file) name. When unspecified this is the full section name (including any parent).  Names are modified (see below).
nfp=	Local string for "not for publication" notice.
origin=	Sets the origin address ("From:") for the VWcms email message.
show=	Label for the button.
submit=	Label for the button.

Each of the buttons can have an icon associated with it.  If one is graphical they all must be.  See Icons for additional information.

Moderation

Reader comments may be moderated before general viewing.  This is accomplished by obfuscating text until moderator approval. The example above includes one such comment.  Comment moderators should be notified by email so that approval (or otherwise) is implemented within a reasonable period.

The following example shows the directive for moderated comments with email notification, intially open for reading, and default button labels.

$$COMMENT$^$+$email=mark.daniel@wasd.vsm.com.au$$

A moderator must be a site manager.  Moderation is accomplished by logging-in and viewing the comment  section.  When logged-in checkboxes associated with each comment item variously allowing cutting the comment (removing it from view but not actually deleting it), approving the comment (for unobfuscated viewing), or un-cutting the comment (if previously cut).  An additional button actions any checked items.

Email Notification

As suggested above, comment moderators should be notified by email so that moderation may occur expeditiously.  It is also possible to notify via email when a non-moderated comment is submitted.  Any email address acceptable to site VMS (callable) Mail may be specified.

$$COMMENT$email=mark.daniel@wasd.vsm.com.au$$

Comment Abuse

Though a notoriously difficult issue to address other than through moderation there are some configurable mechanisms available that attempt to minimise the possibility of comment abuse and DOS.

Comment Files

Comments are stored separately to content. By default a file name is generated from the full section name and all comments against the directive in that section (i.e. on that page) are stored in that file.  For whatever reason (name length, site preference, etc.) the comment file name can be specified in the comment directive. Different sections have individual comment files but by specifying the same name across multiple sections the comment files can be shared.

In the default case, the example comment directory above is in section

/Building_The_Site/Reader_Comment

and the associated comment file is

[.vdub]_Building_The_Site$Reader_Comment.CMT

Dollar symbols represent section forward-slashes.  It is stored in the site directory.  It is rendered ODS-2 compliant if necessary.  Renaming of a section requires renaming any associated comment file.

Individual comment files can be edited using the facilities of Managing Content and Plain Edit. Do not use an HTML editor.  Beware of "lost updates" (i.e. overwriting comments submitted during an edit).

The maximum size of an individual comment file is determined by configuration directive [comment-max-size] kbytes.