Reader comment may be solicited and displayed using the $$COMMENT$$ substitution directive.
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).
As a general rule a comment directive would be placed at the end of a content section (bottom of the page).
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.
Each of the buttons can have an icon associated with it. If one is graphical they all must be. See Icons for additional information.
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.
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.
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.
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.
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
and the associated comment file is
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.