doc/plugins/contrib/postcomment.mdwn

   1 [[!template id=plugin name=postcomment 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 Comments are saved as internal pages, so they can never be edited through the CGI,
   9 only by direct committers. Currently, comments are always in [[ikiwiki/markdown]].
  10 Directives and raw HTML are filtered out by default, and comment authorship should
  11 hopefully be unforgeable by CGI users.
  12
  13 When comments have been enabled generally, you still need to mark which pages
  14 can have comments, by including the `\[[!postcomment]]` directive in them. By default,
  15 this directive expands to a "post a comment" link plus an `\[[!inline]]` with
  16 the comments.
  17
  18 The plugin adds a new [[ikiwiki/PageSpec]] match type, `postcomment`, for use
  19 with `anonok_pagespec` from the [[plugins/anonok]] plugin or `locked_pages` from
  20 the [[plugins/lockedit]] plugin. Typical usage would be something like:
  21
  22     locked_pages => "!postcomment(*)"
  23
  24 to allow non-admin users to comment on pages, but not edit anything. You can also do
  25
  26     anonok_pages => "postcomment(*)"
  27
  28 to allow anonymous comments (the IP address will be used as the "author").
  29
  30 Optional parameters to the postcomment directive:
  31
  32 * `commit=no`: by default, comments are committed to version control. Use this to
  33   disable commits.
  34 * `allowhtml=yes`: by default, raw HTML is filtered out. Use this to allow HTML
  35   (you should enable [[plugins/htmlscrubber]] and either [[plugins/htmltidy]] or
  36   [[plugins/contrib/htmlbalance]] if you do this).
  37 * `allowdirectives=yes`: by default, IkiWiki directives are filtered out. Use this
  38   to allow directives (avoid enabling any [[plugins/type/slow]] directives if you
  39   do this).
  40 * `closed=yes`: use this to prevent new comments while still displaying existing ones.
  41 * `atom`, `rss`, `feeds`, `feedshow`, `timeformat`, `feedonly`: the same as for [[plugins/inline]]
  42
  43 This plugin aims to close the [[todo]] item "[[todo/supporting_comments_via_disussion_pages]]",
  44 and is currently available from [[smcv]]'s git repository on git.pseudorandom.co.uk.
  45
  46 Known issues:
  47
  48 * Needs code review
  49 * The access control via postcomment() is rather strange
  50 * There is some common code cargo-culted from other plugins (notably inline and editpage) which
  51   should probably be shared
  52 * If the postcomment directive is removed from a page, comments can still be made on that page,
  53   and will be committed but not displayed; to disable comments properly you have to set the
  54   closed="yes" directive parameter (and refresh the wiki), *then* remove the directive if
  55   desired