Hikari Titled Comments

Installation

Hikari Titled Comments requires theme modifications to be used, unfortunately there is no way to insert titles to comments without editing the theme. But first let’s install it.

You can use the built in installer and upgrader, or you can install the plugin manually.

1. Download the zip file, upload it to your server and extract all its content to your /wp-content/plugins folder. Make sure the plugin has its own folder (for exemple /wp-content/plugins/hikari-titled-comments/).
2. Activate the plugin through the ‘Plugins’ menu in WordPress admin page.

There’s no options page at the moment. You can go to Edit Comment Admin Page and try to edit any comment, and the title box will be there so you can add title to existing ones. But now it’s time to edit your theme to have them shown and let your visitors set titles to their new comments.

Preparing your theme

There are 2 steps you do to add titled comments support to your theme. First you include the title to your comment building code, second you include an input text to your comment form so that users can submit the title.

First thing you must do is find your comment building code, your search starts in your theme’s file comments.php. If you don’t have experience editing themes, you may need help. The person who developed your theme is the obvious first suggestion.

Since WordPress 2.7, themes use the function wp_list_comments() to print comments, with support to threads, pagination, etc. This function has a parameter called callback, that points to a theme function that has the comment code.

For exemple, in wp_list_comments('style=ol&type=comment&callback=prefix_comment'), the comment function is prefix_comment. Now you must find this function in your theme, I like to have it in comments.php itself, but many tutorials say to move the function to functions.php, just look around.

If your wp_list_comments doesn’t have a callback parameter, you reached a dead end, your theme uses WordPress’s default code and it can’t be edited. You’ll have to design a comment layout for your theme to be able to give a title to your comments. It’s not hard or complex, but if you are reading this and don’t know what to do you’ll need to read a lot and learn a bit before proceeding.

Ok, you’ve found your comment building code. There is no specific place to add a title to your comments, use your imagination. I like to see comments as mini-articles, or extensions of the post. Generally titles come on the top of the article, followed by the author and the article’s date, and then the content.

Once you choose where the title will go in each comment, I tell you that not all comments have titles. Your old comments don’t have, and commentators are not required to use a title (at least for now). So you must have in mind that a title may or may not be present, both layouts must look good and be XHTML valid.

The function you use to add the title is function hkTC_comment_title( $comment_id=null, $before=null, $after=null). If $comment_id is empty, it will try to find global $comment. You can also pass any text to be used before and after the title, probably some HTML tag to surround the title text, these string are not escaped so pass them in the final format they’ll be sent to browsers.

If current comment has a title, the function will print echo $before.$comment_title.$after;. If it hasn’t, the function will just return without doing anything. Here’s the final code I use in my theme:

<?php if(function_exists('hkTC_comment_title'))
    hkTC_comment_title($comment->comment_ID,'<h2 class="comment-title">','</h2>');
?>

Nice! Your theme is ready to print titles to your comments, now you must let your visitors submit them! Your next stop is in your theme’s comment form, also inside comments.php. Again, your creativity will tell you where to include the text field, I’ve chosen just above the comment textarea, with a header to say it’s meant for the title.

There’s nothing much to say here, it’s a simple input text that’s added if the hkTC_comment_title function exists. The function isn’t used here, but we test it to assure the input text is only included if the plugin is activated to receive its parameter. Just make sure you don’t change its ‘name’ and ‘id’ attributes.

<?php if(function_exists('hkTC_comment_title')) { ?>
    <h3>Comment Title</h3>
    <input type="text" name="hikari-titled-comments" id="hikari-titled-comments" tabindex="4" value="" />
<?php } ?>

And that’s it! Now you are ready to aggregate value to your site’s comments!

Upgrading and uninstalling

If you have to upgrade manually, simply delete hikari-titled-comments folder and follow installation steps again.

If you wanna deactivate the plugin, just use the option in plugins page. Your theme will keep the new code for titles, but it will remain asleep while the plugin is not available.

In future version I’m gonna include an option to delete titles metadata from database.