Posts tagged ‘comments’

Added a new feature that people have been asking me for since I created SFC to begin with: Comments Integration.

Facebook Comments

Facebook comments

When you make a post with SFC, the publisher plugin has the ability to push that post to either your Facebook Page or Profile. Up until now, the auto-publish feature has been doing this and storing meta-data with the post about the resulting “story” id that Facebook sends back. This data was stored, but not really used.

No longer. Now, if you auto-publish to Facebook, you have the option to pull comments back from that automatically published Facebook post and show them in the blog as if they were normal WordPress comments.

You can see this in action here on my own site. On the SFC 1.0 Photo Support post, you’ll find a comment at the bottom made by a user named “Kartsios Vasilis”. That comment wasn’t left here on this site, it was left on the Facebook story corresponding to that post. As you can see, the avatar for the user shows up on the comment, it’s styled differently (I felt the blue background sort of distinguished it), and it doesn’t have a reply link.

Since these aren’t “real” WP comments, and don’t live in the WP database, you can’t reply to them properly. So the reply link is automatically removed for them. I used a styling rule in the CSS to add the “This comment was originally made on Facebook, so replying to it here is not allowed.” message where the Reply link would normally be. Because this is just using a simple CSS style rule, you can make that message anything you like, or not have it at all. That’s up to you and your theme.

The new feature is relatively painless too. No configuration is needed. Every 6 hours (minimum), the plugin will retrieve the relevant comments from the Facebook posts, then store them as a transient. This reduces the amount of work since it doesn’t have to talk to Facebook every time. The comments are then integrated in with the normal comments for the post, and the comment count is updated to reflect the right number.

There’s still some minor detail work to be done. Right now, for example, the comments are just added onto the end of the list of comments, and so they’re out of order. The final version will have the comments integrated in correctly by the date and time they were made. Edit: This is now working, comments are added in the proper order.

If you want to use the beta version of SFC (currently marked as version 0.999) you can find it in the WordPress Plugins SVN repository.

Edit: The CSS to add this text, since people asked, is this:

li.comment.facebook .reply:before {
content:"This comment was originally made on Facebook."
}

Simple, really.

Shortlink:

WordPress 3.0 has something very handy that I want theme authors to start implementing as soon as possible.

To show exactly why it’s so useful, I modified my own theme to start using it.

Demonstration

So, here’s a big hunk of code I pulled out of my current theme’s comments.php. This hunk of code has only one purpose: To display the form area where people can leave a comment:

<?php if ('open' == $post->comment_status) : ?>

<div id="respond">

<h3><?php comment_form_title( 'Leave a Reply', 'Leave a Reply to %s' ); ?></h3>

<div class="cancel-comment-reply">
	<small><?php cancel_comment_reply_link(); ?></small>
</div>

<?php if ( get_option('comment_registration') && !$user_ID ) : ?>
<p>You must be <a href="<?php echo get_option('siteurl'); ?>/wp-login.php?redirect_to=<?php echo urlencode(get_permalink()); ?>">logged in</a> to post a comment.</p>
<?php else : ?>

<form action="<?php echo get_option('siteurl'); ?>/wp-comments-post.php" method="post" id="commentform">

<?php if ( $user_ID ) : ?>

<p>Logged in as <a href="<?php echo get_option('siteurl'); ?>/wp-admin/profile.php"><?php echo $user_identity; ?></a>. <a href="<?php echo wp_logout_url(get_permalink()); ?>" title="Log out of this account">Log out &raquo;</a></p>

<?php else : ?>

<p><input type="text" name="author" id="author" value="<?php echo $comment_author; ?>" size="22" tabindex="1" />
<label for="author"><small>Name <?php if ($req) echo "(required)"; ?></small></label></p>

<p><input type="text" name="email" id="email" value="<?php echo $comment_author_email; ?>" size="22" tabindex="2" />
<label for="email"><small>Mail (will not be published) <?php if ($req) echo "(required)"; ?></small></label></p>

<p><input type="text" name="url" id="url" value="<?php echo $comment_author_url; ?>" size="22" tabindex="3" />
<label for="url"><small>Website</small></label></p>

<?php endif; ?>

<!--<p><small><strong>XHTML:</strong> You can use these tags: <code><?php echo allowed_tags(); ?></code></small></p>-->

<p><textarea name="comment" id="comment" cols="100%" rows="10" tabindex="4"></textarea></p>

<p><input name="submit" type="submit" id="submit" tabindex="5" value="Submit Comment" />
<?php comment_id_fields(); ?>
</p>
<?php do_action('comment_form', $post->ID); ?>

</form>

<?php endif; // If registration required and not logged in ?>
</div>
<?php endif; // if you delete this the sky will fall on your head ?>

Nasty, eh? It’s a mess of if/else statements. It handles cases where the user is logged in or not, where the comments are open or closed, whether registration is required, etc. It’s confusing, difficult to modify, poor for CSS referencing…

Here’s what I replaced all that code with:

<?php comment_form(); ?>

Now then, that’s much better, isn’t it?

The comment_form function is new to 3.0. Basically, it standardizes the comments form. It makes it wonderful for us plugin authors, since now we can easily modify the comments form with various hooks and things. I’ve already modified Simple Facebook Connect and Simple Twitter Connect to support this new approach; if you’re using a theme with this, then the user won’t have to modify it to have their buttons appear on the comments form.

Customizing

Since theme authors love to customize things, the comments form is also extremely customizable. Doing it, however, can be slightly confusing.

Inside the comments_form function, we find some useful hooks to let us change things around.

The first hook is comment_form_default_fields. This lets us modify the three main fields: author, email, and website. It’s a filter, so we can change things as they pass through it. The fields are stored in an array which contains the html that is output. So it looks sorta like this:

array(
	'author' => '<p class="comment-form-author">...',
	'email'  => '<p class="comment-form-email">...',
	'url'    => '<p class="comment-form-url">...'
);

I truncated it for simplicity. But what this means is that code like this can modify the fields:

function my_fields($fields) {
$fields['new'] = '<p>Some new input field here</p>';
return $fields;
}
add_filter('comment_form_default_fields','my_fields');

That sort of thing lets us add a new input field, or modify the existing ones, etc…

But fields aren’t the only thing we can change. There’s a comment_form_defaults filter too. It gets a lot of the surrounding text of the comments form. The defaults look sorta like this:

$defaults = array(
	'fields'               => apply_filters( 'comment_form_default_fields', $fields ),
	'comment_field'        => '<p class="comment-form-comment">...',
	'must_log_in'          => '<p class="must-log-in">...',
	'logged_in_as'         => '<p class="logged-in-as">...',
	'comment_notes_before' => '<p class="comment-notes">...',
	'comment_notes_after'  => '<dl class="form-allowed-tags">...',
	'id_form'              => 'commentform',
	'id_submit'            => 'submit',
	'title_reply'          => __( 'Leave a Reply' ),
	'title_reply_to'       => __( 'Leave a Reply to %s' ),
	'cancel_reply_link'    => __( 'Cancel reply' ),
	'label_submit'         => __( 'Post Comment' ),
);

All the various pieces of html that are displayed as part of the comment form section are defined here. So those can be modified as you see fit. However, unlike the fields, adding new bits here won’t help us at all. The fields get looped through for displaying them, these are just settings that get used at various times.

But filters are not the only way to modify these. The comment_form function actually can take an array of arguments as the first parameter, and those arguments will modify the form. So if we wanted a simple change, like to change the wording of “Leave a Reply”, then we could do this:

<?php comment_form(array('title_reply'=>'Leave a Reply, Stupid')); ?>

This gives us a simple and easy way to make changes without all the trouble of filters. Nevertheless, those filters can be very useful for more complex operations.

But wait, there’s more!

As the comments form is being created, there’s a ton of action hooks being called, at every stage. So if you want to insert something into the form itself, there’s easy ways to do it.

A quick list of the action hooks. Most of them are self-explanatory.

  • comment_form_before
  • comment_form_must_log_in_after
  • comment_form_top
  • comment_form_logged_in_after
  • comment_notes_before
  • comment_form_before_fields
  • comment_form_field_{$name} (a filter on each and every field, where {$name} is the key name of the field in the array)
  • comment_form_after_fields
  • comment_form_field_comment (a filter on the “comment_field” default setting, which contains the textarea for the comment)
  • comment_form (action hook after the textarea, for backward compatibility mainly)
  • comment_form_after
  • comment_form_comments_closed

CSS and other extras

Let’s not forget styling. All parts of the comments form have nice classes and id’s and such. Take a look at the resulting HTML source and you’ll find all the styling capabilities you like. Also, everything is properly semantic, using label tags and aria-required and so forth. All the text is run through the translation system for core translations.

So theme authors should start modifying their themes to use this instead of the existing big-ugly-comment-form code. Your users will thank you for it. Plugin authors will thank you for it. And really, it’s about time we made WordPress themes more about design and less about the nuts and bolts of the programming, no?

Shortlink:

Originally posted here: http://ottodestruct.com/blog/2008/wordpress-27-comments-enhancements/

WordPress 2.7 includes a lot of new enhancements, but one of the big ones is the new comment functionality. Comments can be threaded, paged, etc. This is all built in, but unfortunately, your theme must support it. So, for theme authors, I’d suggest getting to work on making your themes compatible right away.

Read on if you’re a theme author…

Note: A lot of people seem to miss this key bit: Enhanced Comments are optional and default to off, even after you make these changes. You have to go to the Settings->Discussion panel to turn the features on.

Actually “compatible” is not quite the right term. Old themes will continue to work fine in WordPress 2.7. It’s just the threading and paging and javascript enhancements need the theme to support it. This is much the same as the sidebar widgets, the theme has to support it for the functionality to work. So this article is really not about 2.7 compatibility, it’s about 2.7 capability.

Note that this article will explain some of the changes needed to make themes capable of supporting the new comments functions, however there’s no substitute for the real thing. Install a local copy of WordPress trunk on your home machine (possibly using XAMPP) and test it there.

Also note that this is all based on the current state of WordPress trunk, and is subject to change before WordPress 2.7 is released. However, it’s probably not going to change all that much at this point.

How to create a 2.7 compatible comments.php

2.7 Detection

If you want your theme to be backward compatible as well, then there’s a simple way to do it. Just check for the wp_list_comments function, like so:

if (function_exists('wp_list_comments')) :
// new comments.php stuff
else :
// old comments.php stuff
endif;

While you could check for the version number of WordPress, this method is better because it simply looks for the actual function you’re going to use anyway. Never make assumptions based on version number.

One of the more interesting ways I’ve seen to use this is to have the “old comments” php in a separate file entirely, which is then included. This preserves backwards compatibility for your theme in a simple way. Here’s a quick example code for that approach:

<?php
add_filter('comments_template', 'legacy_comments');
function legacy_comments($file) {
	if ( !function_exists('wp_list_comments') )
		$file = TEMPLATEPATH . '/legacy.comments.php';
	return $file;
}
?>

Adding this code to a theme’s functions.php file will make the theme use the “legacy.comments.php” for older non-2.7 installations. That way, you can simply rename your old comments.php and then make a new one based on the new functionality. Clever.

Password Protection Check

Put this code at the top of your comments.php file. This is what lets it support the post password functionality. Note that this code is quite similar to the previous way that it was done (by checking the cookie directly), but now WordPress has a specific function to do it. You should use this function in case the functionality changes in the future, your code will be forward compatible:

if (!empty($_SERVER['SCRIPT_FILENAME']) && 'comments.php' == basename($_SERVER['SCRIPT_FILENAME']))
	die ('Please do not load this page directly. Thanks!');
if ( post_password_required() ) {
	echo 'This post is password protected. Enter the password to view comments.';
	return;
}

The Comments Loop

The Comments Loop used to look similar to this (much simplified from a real one):

if ($comments) :
<?php $comment_count = get_comment_count($post->ID); echo $comment_count['approved']; ?> Comments
<ul class="commentlist">
<?php foreach( $comments as $comment ) :
// stuff to display the comment in an LI here
endforeach;
?></ul>
<?php else :
if ('open' == $post-comment_status) :
	// If comments are open, but there are no comments.
else :
	// comments are closed
endif;
endif;

Basically, it went through the comments manually and output all the necessary pieces. Easy, but very manual. This also had the problem of being very inconsistent and hard to manage for your theme’s users, especially if you heavily customized it.

The new comments loop is much simpler:

<?php if ( have_comments() ) : ?>
<h4 id="comments"><?php comments_number('No Comments', 'One Comment', '% Comments' );?></h4>

<ul class="commentlist">
<?php wp_list_comments(); ?>
</ul>

<div class="navigation">
<div class="alignleft">< ?php previous_comments_link() ?></div>
<div class="alignright">< ?php next_comments_link() ?></div>
</div>
<?php else : // this is displayed if there are no comments so far ?>
	<?php if ('open' == $post->comment_status) :
		// If comments are open, but there are no comments.
	else : // comments are closed
	endif;
endif;
?>

That new one is, in fact, a complete comments loop. No simplification at all. Unless you want something displayed for “no comments” or “comments closed”, of course. I don’t have anything showing there.

There are three important pieces to note here:

  • The have_comments() function replaces the check on the global $comments variable.
  • The wp_list_comments() function now outputs all the comments. It does threading, the classes, everything new.
  • There’s a new navigation section to do comment paging.

The Power of Javascript

To support the new Javascript functionality with comment threading, some minor bits of code are needed:

First, in the header.php, add this line immediately before the call to wp_head():

if ( is_singular() ) wp_enqueue_script( 'comment-reply' );

That code adds the comment-reply javascript to the single post pages, letting the comment reply links work correctly. WordPress specifically does NOT do this itself, for the reason that use of this script requires certain naming conventions and parameters in the comment form, which you’ll have to add.

So, your comment form has a new parameter that you have to add:

<?php comment_id_fields(); ?>

This adds a bit of code to your form which makes it display two hidden inputs: comment_post_ID and comment_parent. Your form probably had the comment_post_ID before, so you need to remove it. The comment_parent is there for the javascript, so that replies to comments get threaded properly.

Also, your comment textarea MUST have an id=”comment”. The javascript expects it for focus purposes. If you used anything else, change it. Note that because of this, no other element on your page can have the “comment” ID.

Finally, the entire comment form MUST be surrounded by a DIV with an id=”respond”. In some previous themes (including the default ones), there would be an anchor tag like this:

<a id="respond"></a>

This was there to allow the link from the front page to go directly to the respond section when there were no comments already. That still happens, but now there’s a double purpose. The javascript moves the comment form to where the reply link is, so instead of it being an anchor, it needs to be a DIV that surrounds the comment form.

So, remove that anchor, and add a DIV with an id=”respond” around the entire comment form. The link from the front page still works this way with all modern browsers, and the javascript can now move the form around on the page as needed.

Next, you can replace the call to your normal “Leave a Comment” text with something like this:

<h3><?php comment_form_title(); ?></h3>

This makes a comment form title of “Leave a Reply” which will change to “Leave a Reply to Whoever” when somebody is replying directly to another person. You can customize this, if you like, with two parameters, like so:

<?php comment_form_title( 'Leave a Reply', 'Leave a Reply to %s' ); ?>

The %s will be replaced with the person’s name. This will only happen when the javascript isn’t working and the reply links have to cause a page refresh. So it’s usually not worth customizing much. Still, not everybody runs javascript and so this is nice to let them know who they are replying to.

Finally, you’ll notice that when somebody clicks “reply” and the comment form appears there, maybe they decide to cancel instead. So, that cancel link needs to be in your respond section. Here’s the code to do that, just put it right below your “leave a message” header in the comment form area:

<div id="cancel-comment-reply">
	<small><?php cancel_comment_reply_link() ?></small></div>

That’s pretty much it for making the AJAX work. With this, the new features on the Settings->Discussion panel will work. Obviously, you can modify this somewhat as needed for your theme, these are just general principles that you’ll need to use.

Styling

Now that you have it working, there’s plenty of new styling you can add to comments. The new comments loop automatically puts every comment into an LI tag, and threads them as well, with embedded UL/LI tags. It also adds a ton of classes on all these LIs which surround every comment in this fashion:

  • comment, trackback, pingback classes get added depending on the type of the comment.
  • byuser gets added if the comment is by a registered user of the site.
  • comment-author-authorname gets added for specific registered users.
  • bypostauthor gets added if the comment is by the author of the post the comment is attached to.
  • odd and even classes are added to odd and even numbered comments
  • alt is added to every other comment
  • thread-odd, thread-even, and thread-alt classes are the same as the odd/even/alt classes, but these only apply to the top level of each set of comments and replies
  • depth-1 is added to the top level comments, depth-2 to the next level, and so on.

What’s more, a comment_class filter is provided to allow you to add your own classes. Here’s an example of that. This example function adds a microid to every comment with the microid for the comment authors given URL and email address. This sort of thing could be done in a plugin or a theme’s functions.php file, whatever.

// add a microid to all the comments
function comment_add_microid($classes) {
	$c_email=get_comment_author_email();
	$c_url=get_comment_author_url();
	if (!empty($c_email) && !empty($c_url)) {
		$microid = 'microid-mailto+http:sha1:' . sha1(sha1('mailto:'.$c_email).sha1($c_url));
		$classes[] = $microid;
	}
	return $classes;
}
add_filter('comment_class','comment_add_microid');

Simple and effective. It just adds the class to the given array of classes and lets the comment display functions take care of the rest.

And there you have it. It’s not hard to support the new functions. And if you need to customize your theme’s comments section even more, wp_list_comments() supports a number of parameters. Most of this is not documented yet, because WordPress 2.7 is not out until November. However, the code is relatively straightforward, and anybody with a good understanding of WordPress should be able to work it out.

Additional: A lot of people keep asking me for a full-fledged example. Really, I recommend that you examine the comments.php file in the default theme in the 2.7 beta versions. However, the actual comments.php file I’m using on this site can be found here: http://ottodestruct.com/comments.phps, if it helps you any. It has the code I’ve described in this article, pretty much verbatim. The only additions to it are a couple of extra options on the wp_list_comments() call, such as avatar_size and reply_text.

Shortlink: