# Comment Plugin This plugin allows users to quickly post comments to a page without an edit/preview/save cycle. _( Discussion in TWiki:Plugins/CommentPluginDev )_
# Features Inserts an edit box into the page that allows users to type in and save comments. Comments can be made - 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 Rules Write the command `%COMMENT{` _attributes_ `}%` anywhere in a TWiki topic. %COMMENT% is also legal. The following attributes are [[recognised|Main/WebHome#MoreAttrs]]
Name Description
type (Required) This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see [[Main/WebHome#TemPlates]], below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your [[Main/WebPreferences]]. By default this is 'below'.
target Name of the topic to add the comment to. Defaults to the current topic.
location Regular expression specifying the comment location in the target topic. Read carefully below!
mode For compatability with older versions only, synonymous with type
nonotify Set to "on" to disable change notification for target topics
## Positioning the comment `%COMMENT` supports several ways to specify _where_ a comment should be inserted in the target topic. This is referred to as the _location_ of the comment. ### Location relative to `%COMMENT` tag The default _location_ is the `%COMMENT` tag itself. For example: %COMMENT{type="below"}% will add comments in the current topic, directly below the `%COMMENT` tag. ### Location relative to a TWiki anchor The `target` attribute may specify a web, and may also specify an anchor within the target topic; for example, %COMMENT{type="above" target="%MAINWEB%.PersonalRemarks#InsertHere"}% This uses a standard TWiki in-topic anchor as the insertion location. See [[TextFormattingRules]] for more about TWiki anchors. ### Location relative to an arbitrary text string Getting more sophisticated, you can also specify a regular expression for the target location using the `location` parameter. The target topic is searched for the regular expression, and the comment inserted relative to the string that the search matched. For example, %COMMENT{type="above" location="Flights of Fancy"}% will place comments above the first occurence of the string `Flights of Fancy` in the current topic. **Warning** of course, if a user's comment contains the string "Flights of Fancy" they may and up _changing the location_ for the next comment! Also, if you use a tag in the location, then you've just inserted another tag in the page that contains the `%COMMENT`! So be very careful how you specify the RE for `location`. Note that the RE is matched using perl "multiple line" mode, so ^ and $ match the start of a line and the end of a line respectively. If you specify an anchor _and_ a `location`, the anchor will be ignored. ## Default templates A set of default comment templates are shipped with the plugin. These are:
Template type Description
top Comments, signed and dated, added at top of the topic (the anchor is ignored)
bottom Comments, signed and dated, added at end of the target topic (the anchor is ignored)
above Comments, signed and dated, added immediately before the target anchor, or the %COMMENT if no anchor is specified
below Comments, signed and dated, added immediately below the target anchor, or the %COMMENT if no anchor is specified
tableprepend Comments, signed and dated, formatted as an HTML table row, added below the anchor (which must be in an HTML <table>)
tableappend Comments, signed and dated, formatted as an HTML table row, added above the anchor (which must be in an HTML <table>)
Your local installation may add more template types as well - see [[Customisation|Main/WebHome#TemPlates]], below. # Customisation Customisation of the comment plugin requires - familiarity with HTML forms, - some familiarity with the [[TWiki templating language|TWiki/TWikiTemplates]]. The plugin picks up its templates from a standard TWiki template file, named "comments". This allows different templates to be defined for different TWiki skins. This template file may include other template files, or may include a topic from a user web (this is an extension to the normal handling of `%TMPL:INCLUDE` described in the documentation). The shipped plugin defines default templates in `comments.tmpl` and then includes the topic [[CommentsTmpl]]. If you want to define your own templates, add them to [[UserTemplates]]. Note that you can use `%TMPL:INCLUDE` in this file to include other files of templates. Note also that if you want to override any of the default templates shipped with the plugin, you can simply do so by defining them in [[UserTemplates]], and they will replace the installed versions. To define a comment type, you have to provide two simple template definitions in the template file; one for the prompt box, and one for the generated output. If we have a template type "mytype", these are named `PROMPT:mytype` and `OUTPUT:mytype` respectively. See `comments.tmpl` in the templates directory for examples. ## The `PROMPT` template The `PROMPT` template defines the contents of an HTML form that is used to capture the comment. This form invokes the comment generator when submitted. Parameters to the comment generator are defined using standard HTML input fields, such as `input`, `textarea` and `select`. The user enters values for these parameters, and these are then available when the `OUTPUT` template is expanded, in the form of `%URLPARAM%`s. Only the input fields of the form need be defined. The plugin automatically generates the `>form<` and `>:/form<` tags. **Note** that you must define a "submit" button if you want the form to work! If an attribute is given to the `%COMMENT` tag that is not one of the [[standard attributes|Main/WebHome#StandardAttrs]], then that attribute is taken as the name of a parameter to be expanded in the `PROMPT` template. Expressions in the template of the form `%`_param_`|`_default_`%` (e.g. `%rows|3%`, `%button|Push me%`) are expanded to the values given in the `%COMMENT`. For example, if the `PROMPT` template 'example' contains: