Comments

Note: The recipes here are for PmWiki versions 0.6 and 1.0 only. For PmWiki 2.0 recipes, see Cookbook.


Description

This module enables comment functionality on all pages in the wiki. It doesn't mess page content, because comments are stored in separate files. Users have ability to alter their comments right after posting. Wiki markup is supported.

Installation

Simply copy file comments-041029.php as comments.php into your local/ subdirectory and add the following line:

    include_once('local/comments.php');

into your local configuration file. Then, to display comments you should call PmWiki with action=comments. For example you may add the following line in your pmwiki.tmpl template file, if you're using standard template:

    <a href='$PageUrl?action=comments#comments'>
        $[Comment] (<!--function:DisplayCommentsCount -->)
    </a>

If you want comments always to be displayed in pages, place a call to PatchCommentBrowseFmt() in your config file after including comments.php.

To be able to remove comments you also need to set the default password for this action:

    $DefaultPasswords['removecomment'] = crypt('yourpassword');

See also Passwords and PasswordsAdmin for information on using passwords in PmWiki.

Usage

To display comments call pmwiki.php script with action=comments. Or simply open any page, if the comments are shown by default. Under the page text there will be a bunch of already written comments (if any) and the form to enter new comment. It looks like:

    Enter your comment:
    [                                             ]
    [                                             ]
    [                                             ]
    [                                             ]
    [                                             ]
    [                                             ]
    Author: [          ]  [Submit]

After entering comment text and author name (if not entered, it's substituted by author's ip address) and submitting the form buttons are replaced by those:

    Author: [          ]  [Update] [Delete] [Reset]

User can now edit his recently posted comment and submit changes by pressing Update button. If the text is completely deleted and posted, the recent comment is deleted. The same effect can be reached by pressing Delete. To add a completely new comment, Reset button should be pressed to clear all the hidden fields.

The behaviour seems a bit hard to understand, but it's useful and easy when one's got used to it. As for beginners, they could probably need some advice, and it should be written in the PmWiki.CommentsFooter page. For example, it may contain the following text:

The meaning of buttons:

  • Submit — submits a new comment;
  • Update — updates recently submitted comment's text;
  • Delete — removes last comment;
  • Reset — clears text and hidden fields allowing to enter a new comment.

The one useful feature is that wiki markup is supported in the comment text.

Configuration

In the script there are two functions that set default values for the styling variables. The first one, InitComments(), uses plain wiki markup to style comments. If you are not afraid of using CSS markup, you may leave a call to InitCommentsStyled() uncommented.

Variables

$CommentStartFmt
Defines comment list header.
$NoCommentsFmt
Defines text that is displayed when there's no comments for the page. By default it looks like $CommentStartFmt, but saying 'No comments'.
$CommentFmt
Defines how the comment is displayed. Has following variables that are substituted: $Author — author's name or ip; $Time — date and time of the comment (formatted with $TimeFmt); $Text — the comment itself.
$CommentEditFmt
Contains the comment edit form excepting buttons. Before changing this variable you must learn how it works by examining the default value.
$NewCommentButtonsFmt
Contains Submit button, which sends the new comment data.
$EditCommentButtonsFmt
Contains Update, Delete and Reset buttons used to alter posted comment.
$CommentsFooterFmt
By default displays PmWiki.CommentsFooter page under the edit form. Is referred in the $CommentEditFmt.
$RecentComments
List pages where notifications about recently added comments are stored, just as $RecentChanges array. By default contains Main.AllRecentComments and $Group.RecentComments.
$CommentsFileName
The name of the function which takes page name as parameter and return the file name where page comments are stored. Default function returns "$WikiDir/$pagename.Comments".

Internationalization

Several strings in default values are made i18nable, and some of those strings interfer with the standard ones. I think this is not critical because the meaning is the same. The strings are:

  • Comments (in $CommentStartFmt)
  • No comments (in $NoCommentsFmt)
  • Enter your comment
  • Author
  • Submit
  • Update
  • Delete
  • Reset
  • Set new comment removing password:

Storage

Comments are stored in $WikiDir along with wiki pages. The name of comments file for the page in constructed by adding .Comments extension to the page file name. For example, for Main.HomePage comments file will be named Main.HomePage.Comments. If you want to override this behaviour (for example, store comments in a separate directory), write your own comment-file-name-constructing function and specify its name in the $CommentsFileName variable.

Each comment occupies exactly one line in the file. The line has the following format:

    UID|IP|Author|Time|Text

The meaning of fields is:

  • UID — the unique id of the comment allowing its author to alter it right after posting. Probably it will allow changing all comments by the author in the future;
  • IP — the ip address of the comment author;
  • Author — the author's name;
  • Time — the unix-timestamp of the comment, is converted to normal time using $TimeFmt when the comment is displayed;
  • Text — the comment text itself. All newlines are replaced with the $Newline symbol. Note that $Newline is not stored along with comments, so it will be a disaster when you change it.

History

Oct 29, 2004

  • Handling \r chars in input.
  • CommentsCount() function caused warnings.
  • Now allows authorized users to delete comments.
  • Added forgotten fclose() in HandlePostComment{}.

Sep 29, 2004

  • original version.

Comments & Bugs

Leave your comments and bug reports here.

Give us a link to a working example

Sorry, I don't have any internet site for now. Probably, in a few weeks... But the script works well on my intranet wiki. Zverik

Author

I'm Ilya Zverev, you can mail to zverik at int.spb.ru if you are experiencing problems with this script. I'm also subscribed to Pmwiki-users list: use it if you think that the question (and the answer) may be interesting to others. pmwiki-2.3.32 -- Last modified by {{gb}}

from IP: 85.171.160.186 ip should be disabled by default for security reasons