doc/plugins/contrib/comments.mdwn

   1 [[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]]
   2 [[!tag type/useful]]
   3
   4 This plugin adds "blog-style" comments. The intention is that on a non-wiki site
   5 (like a blog) you can lock all pages for admin-only access, then allow otherwise
   6 unprivileged (or perhaps even anonymous) users to comment on posts.
   7
   8 When using this plugin, you should also enable [[htmlscrubber]] and either [[htmltidy]]
   9 or [[htmlbalance]]. Directives are filtered out by default, to avoid commenters slowing
  10 down the wiki by causing time-consuming processing. As long as the recommended plugins
  11 are enabled, comment authorship should hopefully be unforgeable by CGI users.
  12
  13 The plugin adds a new [[ikiwiki/PageSpec]] match type, `postcomment`, for use
  14 with `anonok_pagespec` from the [[plugins/anonok]] plugin or `locked_pages` from
  15 the [[plugins/lockedit]] plugin. Typical usage would be something like:
  16
  17     locked_pages => "!postcomment(*)"
  18
  19 to allow non-admin users to comment on pages, but not edit anything. You can also do
  20
  21     anonok_pages => "postcomment(*)"
  22
  23 to allow anonymous comments (the IP address will be used as the "author").
  24
  25 There are some global options for the setup file:
  26
  27 * `comments_shown_pagespec`: pages where comments will be displayed inline, e.g. `blog/*`
  28   or `*/discussion`.
  29 * `comments_open_pagespec`: pages where new comments can be posted, e.g.
  30   `blog/* and created_after(close_old_comments)` or `*/discussion`
  31 * `comments_pagename`: if this is e.g. `comment_` (the default), then comments on the
  32   [[sandbox]] will be called something like `sandbox/comment_12`
  33 * `comments_allowdirectives`: if true (default false), comments may contain IkiWiki
  34   directives
  35 * `comments_commit`: if true (default true), comments will be committed to the version
  36   control system
  37 * `comments_allowauthor`: if true (default false), anonymous commenters may specify a
  38   name for themselves, and the \[[!meta author]] and \[[!meta authorurl]] directives
  39   will not be overridden by the comments plugin
  40
  41 Templates that will display comments (by default that means `comments_display.tmpl`)
  42 can use the following additional `<TMPL_VAR>`s:
  43
  44 * `COMMENTUSER`: the authenticated/verified user name, or undefined if the user was not signed in
  45 * `COMMENTIP`: the remote IP address, or undefined if not known (this is not currently recorded
  46   for users who are signed in, who are assumed to be vaguely accountable)
  47 * `COMMENTAUTHOR`: a "prettier" version of the authenticated/verified user name (e.g. OpenIDs are
  48   formatted the same way as in [[RecentChanges]]), or the result of localizing "Anonymous" if the
  49   user was not signed in
  50 * `COMMENTAUTHORURL`: if the user was signed in with an OpenID, that URL; if the user was signed
  51   in with some other username, a CGI URL that redirects to their user page (if any)
  52
  53 This plugin also adds a `\[[!_comment]]` directive which is used when storing comments. This
  54 directive is for internal use only and shouldn't be used on pages that are edited in the usual way.
  55
  56 This plugin aims to close the [[todo]] item "[[todo/supporting_comments_via_disussion_pages]]",
  57 and is currently available from [[smcv]]'s git repository on git.pseudorandom.co.uk (it's the
  58 `comments-rebase2` branch). A demo wiki with the plugin enabled is running at
  59 <http://www.pseudorandom.co.uk/2008/ikiwiki/demo/>; the
  60 [sandbox page](http://www.pseudorandom.co.uk/2008/ikiwiki/demo/sandbox/#comments) has some
  61 examples of comments.
  62
  63 Known issues:
  64
  65 * Needs code review
  66 * The access control via postcomment() is rather strange (see [[discussion]] for more details)
  67 * There is some common code cargo-culted from other plugins (notably inline and editpage) which
  68   should probably be shared
  69 * Joey doesn't think it should necessarily use internal pages (see [[discussion]])
  70 * Previews always say "unknown IP address"
  71 * Add `COMMENTOPENID`: the authenticated/verified user name, if and only if it was an OpenID
  72 * The default template should have a (?) icon next to unauthenticated users (with the IP address
  73   as title) and an OpenID icon next to OpenIDs
  74
  75 > I haven't done a detailed code review, but I will say I'm pleased you
  76 > avoided re-implementing inline! --[[Joey]]
  77
  78 Fixed issues:
  79
  80 * Joey didn't think the `\[[!comments]]` directive was appropriate; comments now appear
  81   on pages selected with a [[ikiwiki/pagespec]]
  82 * Joey thought that raw HTML should always be allowed; it now is
  83 * tbm wanted anonymous people to be able to enter their name and possibly email
  84   address; a name and website can now be supplied
  85 * There is now an indication of who you're signed in as
  86 * Each comment is now one big \[[!_comment]] directive invocation, avoiding previous
  87   issues with unambiguous and un-spoofable metadata
  88 * `\[[!comment]]` should be `\[[!_comment]]`, or a special filter/htmlize hook rather
  89   than being a directive at all
  90 * [[todo/inline_plugin:_ability_to_override_the_feed_name]]
  91 * [[todo/inline_plugin:_hide_feed_buttons_if_empty]]