Quick guide to the comments system

[ryan]

Here is a quick guide to using the comments system. We start from the simplest usage, and get down into more configuration options further in the post.

Making use of the Comments fieldtype

---

1. Make sure that Comments fieldtype (FieldtypeComments) is installed from the Admin > Modules menu.

2. Now go to Admin > Setup > Fields and create a new field. Select "Comments" as the fieldtype and give it whatever name you wish (I usually call it just "comments", and code snippets here assume it's called that).

3. On the next screen, you'll have several options to configure the comments field. Make sure that you enter a Notification email. This is the email address that gets notified when new comments are submitted. Currently it is the only way you will know when new comments are posted (short of checking the admin page yourself), so using this is important.

4. Now edit the template where you want your comments to appear. Enter this:

<?php echo $page->comments->render(); 

5. Likewise, in your template, enter this where you want the comments entry form to appear:

<?php echo $page->comments->renderForm(); 

6. Your comments are now ready to use. Note that any templates that use comments for posting should not use Template caching unless you configure the comments to post to another template/page. You'll see an option for this in the renderForm() options shown further down on this post.

Adding the Akismet Spam Filter

---

I highly recommend that you use the Akismet spam filter with your comments. To do so, you'll need an Akismet or Wordpress API key (http://en.wordpress.com/api-keys/).

Once you have it, click to Admin > Modules > Akismet (CommentFilterAkismet). Enter your API key in the space provided and Save. Then go to Setup > Fields > and edit the comments field you added. Check the box for "Use Akismet". You'll also see a field that says how many days it will keep spam before deleting it. I usually set this at 1 or 2 days, just in case Akismet identifies something as spam that isn't (though it's yet to happen!). Hit Save, and your comments are now hooked into Akismet. 

Styling the Comments

---

See the file attached to this message (at the bottom). It is a starting point for styling the comments. It's just pulled from the comments styling at processwire.com, so it should be seen as an optional starting point rather than as a ready-to-go stylesheet. Or, you may prefer to start from scratch on styling the comments, depending on your need. 

OPTIONAL: Customizing the Comments Output

---

You may want to change some of the basics of the comments output. You can do this by passing arguments to the functions you called above to render the comments list and comments form. Included below are examples with all options. You may specify any one or more of the options -- only specify the ones you want to change:

<?php 

// comments list with all options specified (these are the defaults)
echo $page->comments->render(array(
    'headline' => '<h3>Comments</h3>',
    'commentHeader' => 'Posted by {cite} on {created}',
    'dateFormat' => 'm/d/y g:ia',
    'encoding' => 'UTF-8',
    'admin' => false, // shows unapproved comments if true
    )); 

// comments form with all options specified (these are the defaults)
echo $page->comments->renderForm(array(
    'headline' => "<h3>Post Comment</h3>",
    'successMessage' => "<p class='success'>Thank you, your submission has been saved.</p>",
    'errorMessage' => "<p class='error'>Your submission was not saved due to one or more errors. Please check that you have completed all fields before submitting again.</p>",
    'processInput' => true,
    'encoding' => 'UTF-8',
    'attrs' => array(
        'id' => 'CommentForm',
        'action' => './',
        'method' => 'post',
        'class' => '',
        'rows' => 5,
        'cols' => 50,
        ),
    'labels' => array(
        'cite' => 'Your Name',
        'email' => 'Your E-Mail',
        'text' => 'Comments',
        'submit' => 'Submit',
    ),
    // the name of a field that must be set (and have any non-blank value), typically set in Javascript to keep out spammers
    // to use it, YOU must set this with a <input hidden> field from your own javascript, somewhere in the form
    'requireSecurityField' => '', // not used by default
    )); 

Lets say that you just wanted to change the headlines for the comments list and comments form. You'd do this:

<?php

echo $page->comments->render(array(
    'headline' => '<h2>Read Comments</h2>',
    ));

echo $page->comments->renderForm(array(
    'headline' => '<h2>Join The Discussion</h2>',
    ));

OPTIONAL: Generating your own output

---

If you wanted to generate your own output (rather than use the built in render() methods), you can iterate the $page->comments field:

<?php
foreach($page->comments as $comment) {
    if($comment->status < 1) continue; // skip unapproved or spam comments
    $cite = htmlentities($comment->cite); // make sure output is entity encoded
    $text = htmlentities($comment->text);
    $date = date('m/d/y g:ia', $comment->created); // format the date
    echo "<p><strong>Posted by $cite on $date</strong><br />$text</p>";
}

You can likewise do the same for the comment form. But I don't want to get too far into this level yet since this is supposed to be a quick guide.

Whats on the Comments roadmap?

---

In my mind the biggest missing part is a central place to manage all your comments. Currently you manage them on a page-by-page basis, consistent with where the comment was posted. This is fine for simple uses, but becomes more challenging on larger sites, where you have to rely upon the notification emails to let you know where comments are posted. I would like to expand this so that comments can optionally be managed in a central place. In addition, I would like to make them as easily API accessible as pages.

The comments are also not hooked into the user system. Every time you post, you are essentially posting as a guest. While the comments fieldtype will recognize your email address if you have posted an approved comment before, I would like to make it recognize the user system, and also recognize other user systems (like Twitter, Facebook and Gravatar).

There is more needed too, like comments pagination and support for basic markup (comments can only contain text at present).

If your needs are relatively simple, the Comments fieldtype is a good way to go. If your needs are more advanced, systems like Disqus and Intense Debate are excellent options to consider. The only issue I would have with those options is that they are javascript-based by default, so comments don't become part of your site's indexable content (to search engines like Google).

comments.css.zip

[martinluff]

Thanks for the info Ryan. Agree with you points for the roadmap - good to hear where you see it going.

Also agree with your comments on using JS for pulling in Disqus or IntenseDebate... My understanding is there's a REST API for Disqus - but not had a time to explore it or see what features this includes - but I'm thinking it could possibly overcome the issues of a JS include?

I guess the other alternative is to integrate something like commentics http://www.commentics.org/ (not that I've tried it - just did a quick trawl for PHP comment scripts)...

Seems like comments could be handled more easily by a third-party SaaS or script than something like workflow or versioning for example (just thinking out loud here  )

[ryan]

I didn't realize that disqus had a REST API. That's cool if it does. I also need to look into those other solutions you mentioned. But regardless of any other solutions, I figure a good built-in comments system is a priority, so I'm going to keep at it. But keep the system so that any other comments systems can be easy to implement too.

[ryanscherler]

Hey Ryan, 

Thanks for the writeup on the comments API for processwire. Is this going to make it into the main API documentation?

Talk soon!

[ryan]

Hi Ryan,

Good to see you in the forums!

This will make it into the main API documentation. I've been posting stuff here first, and then transitioning it to the main API docs after making sure I've accounted for everyone's questions, and haven't made any typos.

Ryan

[martinluff]

Perhaps a little bit of topic here - but I thought it might be useful at this point while you're still shaping the comment system... I recently came across this plugin for WordPress which seems to take an innovative and interesting approach to commenting http://highlighter.com/

[Adam Kiss]

re" Highlighter: I've seen just a minute or so from the video, so this may be little away: I thought about this before, but, ended in the same moment this plugin does for me – engagment & discussion is becoming a little too fragmented to my taste. Now, let's say that you're okay with 4 comments on page in two blocks. But what will happen if you have 100+ comments in ten places with 4 or 5 'ideas' or 'topics' in each thread? How do you stay current and reply as much people as possible?

[Frank Vèssia]

Is there a way to access to 'email' field when pw render a comment?

'commentHeader' => 'Posted by {cite} on {created}',

i tried to add {email} in the code...

[ryan]

There isn't at present. Mainly because I couldn't think of a situation where you would be echoing someone's email on a public site.

But if that's something you need to do, I would suggest iterating the comments field directly (as in the example above), as this is very simple to do and gives you access to every bit of comment data.

[Frank Vèssia]

Situations with visible emails can be various, especially when your page is not public and only a user group can access, but there are a lot of other cases, not all the websites are similar...however i will use the custom code for this scope, thanks

[martinluff]

re" Highlighter: ... I thought about this before, but, ended in the same moment this plugin does for me – engagment & discussion is becoming a little too fragmented to my taste. Now, let's say that you're okay with 4 comments on page in two blocks. But what will happen if you have 100+ comments in ten places with 4 or 5 'ideas' or 'topics' in each thread? How do you stay current and reply as much people as possible?

You could be right there, I might test out at some stage - I just thought this was one of the better implementations I'd seen and thought it worth kicking around a few ideas at this stage...

[ryan]

I also thought that highlighter looked pretty interesting, at least in concept. But it's one of those ideas where it's kind of hard to predict whether people will actually use it.. I'm not sure I would. Though the last time I said that was in 2007 at SXSW when they introduced Twitter...

[martinluff]

I also thought that highlighter looked pretty interesting, at least in concept. But it's one of those ideas where it's kind of hard to predict whether people will actually use it.. I'm not sure I would. Though the last time I said that was in 2007 at SXSW when they introduced Twitter...

lol

I'd agree it's early days - plus of course it confounds the commenting model most folk have become used to and so there's a bit of re-education for your users then... and that's always something to think carefully about.

[apeisa]

This will be a game changer I think: http://developers.facebook.com/blog/post/472

Techcrunch already uses it: http://techcrunch.com/2011/03/01/facebook-rolls-out-overhauled-comments-system-try-them-now-on-techcrunch/

Now it only allows FB and Yahoo logins, but more is coming (google & twitter I assume). And it is integrated very nicely to Facebook. I myself don't like Facebook spreading to every single website, but I showed this today to one of our clients and he was amazed and wanted it right away. So probably it will spread, whether I like or not

[ryan]

Looks like some good ideas that Facebook is on to there. I like what they are doing with it. But it looks like it's still JS based, and any solution that is JS based has little value for building your site's content for search engines. Unless they provide an API to it where you can render the comments yourself. But I kind of doubt that Facebook is providing that here. I'm also curious who owns the comments. Something tells me Facebook has a 50-page disclaimer about this.

But these JS widgets are handy and easy to implement... I would think that sooner or later Google is going to have to start indexing pages with JS rendered content. Otherwise this is all a big black hole to search engines.

[digitex]

Hi Ryan.

3 questions regarding the comments:

In the headline <h3>Comments</h3> how would I display the number of comments?

Is there a way to incorporate captcha or some other security since akismet is probably out of reach for the people I'm doing this for (a woman's shelter in India).

Third how do I remove the email field? I don't want anyone feeling vulnerable or nervous posting comments even though no one will have access to the emails it might make some people shy away having to include it.

[ryan]

In the headline <h3>Comments</h3> how would I display the number of comments?

You can do it like this:

$num = count($comments); 
$options = array('headline' => "<h3>$num Comments</h3>"); 
echo $comments->render($options); 

Is there a way to incorporate captcha or some other security since akismet is probably out of reach for the people I'm doing this for (a woman's shelter in India).

See here:

Third how do I remove the email field? I don't want anyone feeling vulnerable or nervous posting comments even though no one will have access to the emails it might make some people shy away having to include it.

You could edit the module and remove it, but I don't recommend doing so. The email field is not displayed to anyone, it is just used as a way to recognize when a comment is made by someone that already has an approved comment (so they don't have to wait in a moderation queue). If you were certain you didn't want it, you could always pre-populated it with some fictional address and hide it with CSS.

[digitex]

You can do it like this:

$num = count($comments);
$options = array('headline' => "<h3>$num Comments</h3>");
echo $comments->render($options);

Thanks Ryan. The only downside to this is it counts all comments including the ones waiting for moderation. The number may not always agree with what's being displayed. Not an issue though.

See here:

http://processwire.c...g-alternatives/

Didn't even see that until you pointed it out. My search skills are wanting it seems. Thanks.

You could edit the module and remove it, but I don't recommend doing so. The email field is not displayed to anyone, it is just used as a way to recognize when a comment is made by someone that already has an approved comment (so they don't have to wait in a moderation queue). If you were certain you didn't want it, you could always pre-populated it with some fictional address and hide it with CSS.

I did the pre-populate and hide option.

[DaveP]

Just a quick heads-up to anyone revisiting this thread http://www.labnol.org/internet/google-indexes-facebook-comments/20295/ - Google now apparently can index embedded Facebook comments.

[alan]

Thanks Ryan. The only downside to this is it counts all comments including the ones waiting for moderation. The number may not always agree with what's being displayed. Not an issue though.

+1 for the thanks to Ryan for that snippet.

Does anyone know, for a comment, is there a field I can test to see if it is approved? If not, is there an alternative way to check, albeit might be less elegant?

[ryan]

Does anyone know, for a comment, is there a field I can test to see if it is approved? If not, is there an alternative way to check, albeit might be less elegant?

$numApproved = 0; 
$numPending = 0; 
$numSpam = 0;

foreach($page->comments as $comment) {
   if($comment->isApproved()) $numApproved++; 
    else if($comment->status == Comment::statusPending) $numPending++;
    else if($comment->status == Comment::statusSpam) $numSpam++; 
}

echo "<p>$numApproved approved comments.</p>";
echo "<p>$numPending comments awaiting moderation.</p>";
echo "<p>$numSpam spam comments.</p>";

[alan]

Me:

Does anyone know, for a comment, is there a field I can test to see if it is approved? If not, is there an alternative way to check, albeit might be less elegant?

Ryan:

→ Fantastically fast and helpful post ←

I'll take that as an emphatic "YES!" then Ryan

THANKS again for the help; it's so appreciated. Having a smile-inducing time rattling out my own blog system based only on PW API and dollops of cleverness courtesy kind people like you and others. It's a delight working in PW even tho' my speed may be lower than some due to my PHP learning curve. Thanks again for such a generous and excellent project.

[alan]

Tested, works a treat with one typo:

foreach($page->comments as $comment) {

comments needs to be comment

foreach($page->comment as $comment) {

Happy coder

[ryan]

Actually it needs to be whatever you've named your comments field, whether 'comments', 'comment' or feedback', etc.

[alan]

Actually it needs to be whatever you've named your comments field, whether 'comments', 'comment' or feedback', etc.

I read that and did a "DOH!", to quote Homer Simpson.

Sorry Ryan, I didn't spot that silliness on my part