WP-AjaxCM Manual

This document describes the installation and configuration of the WP-AjaxCM WordPress plugin.

Prerequisites and things to know before installing the plugin

WP-AjaxCM is generally easy to install and use, there is, however, one thing you should be aware of before installing it. The plugin requires a small change to your WordPress theme, specifically, you must edit exactly one template file - comments.php and add a single <div> container. Detailed instructions will follow later. If you have basic knowledge about editing theme files, you should not have difficulties with it, otherwise you may want to consult help from a person with the required knowledge or ask for help (see the end of this document for possible ways to get support).

License

 The plugin WP-AjaxCM is licensed under the terms of the GNU General Public License version 2. A copy of this license should be included with the plugin distribution file.

Installation

The plugin can be installed like any other WordPress plugin in your admin back end. Before you activate the plugin, you should prepare your theme and add the required container element to comments.php.

Theme preparation

In order to make the Ajax pager work, you must add one <div> element to your comments.php template. This element must have set its id to ajaxcm_container (check for correct spelling and don't use anything else) and the div element must enclose the following things in your comments.php:

1. The list of comments. Usually, this is a ordered list element and looks like: <ol id="thecomments" class="commentlist">.
2. The navigation area(s) at the top and the bottom of the comment list.

Here is how the the relevant part of comments.php looks in the Twenty Eleven theme.

<?php // You can start editing here -- including this comment! ?>
<?php if ( have_comments() ) : ?>
<h2 id="comments-title">
<?php
printf( _n( 'One thought on &ldquo;%2$s&rdquo;', '%1$s thoughts on &ldquo;%2$s&rdquo;', get_comments_number(), 'twentyeleven' ),
number_format_i18n( get_comments_number() ), '<span>' . get_the_title() . '</span>' );
?>
</h2>
<div id="ajaxcm_container">
<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through ?>
<nav id="comment-nav-above">
<h1 class="assistive-text"><?php _e( 'Comment navigation', 'twentyeleven' ); ?></h1>
<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentyeleven' ) ); ?></div>
<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentyeleven' ) ); ?></div>
</nav>
<?php endif; // check for comment navigation ?>
<ol class="commentlist">
<?php

/* Loop through and list the comments. Tell wp_list_comments()
 * to use twentyeleven_comment() to format the comments.
 * If you want to overload this in a child theme then you can
 * define twentyeleven_comment() and that will be used instead.
 * See twentyeleven_comment() in twentyeleven/functions.php for more.
 */

wp_list_comments( array( 'callback' => 'twentyeleven_comment' ) );
?>
</ol>
<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through ?>
<nav id="comment-nav-below">
<h1 class="assistive-text"><?php _e( 'Comment navigation', 'twentyeleven' ); ?></h1>
<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentyeleven' ) ); ?></div>
<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentyeleven' ) ); ?></div>
</nav>
<?php endif; // check for comment navigation ?>
</div>

The relevant lines are 9 and 37. As you can see, the <div id="ajaxcm_container"> element encloses the navigation links and the comment list, but nothing else. This is important to note, because the contents of this container element will be replaced whenever a new page of comments is loaded. Note that the purpose of this container is for DOM manipulation only. You do not need to create styles for it or care otherwise about this element - it must exist and that's about it.

No other editing is necessary, everything can be left as it is, but the position of the div element is crucial and don't forget the closing tag. Because of all the PhP if statements, it can be a bit confusing to place it properly, but if you know the basics about PhP, it should not be too difficult.

The above example shows the Twenty Eleven theme, but the exact same principle works for any other theme. You must open comments.php and find the section that outputs the list of comments and the corresponding navigation areas on top and bottom of this list. Once located, you simply enclose them with the div element. Make sure to spell the id ajaxcm_container properly.

Setting the comment callback function name

This is the second important configuration step, however, no theme editing is necessary for it. First, you have to find the name of the callback function your theme uses to format comments. Many, if not most, themes use such a custom comment formatting function and it is easy to find.

• In comments.php search for wp_list_comments.
• It will look like: wp_list_comments( array( 'callback' => 'twentyeleven_comment' ) ); (note: this function call can look different, passing more than a single parameter, but the important one is the callback parameter). If there is no value assigned to callback, then your theme does not use a custom callback function. In that case, the corresponding option on the WP-AjaxCM settings page must be empty.

The orange marked text is the callback function name. Write it down or copy it to your clipboard, then go to your WordPress admin area and open the Comments node in the left navigation area (note that the plugin must be active now). There you'll find a Ajax Comments menu entry. Open it and paste the name of the callback function into the first option field: Custom comment callback function name. Save the option page and you should be ready to test the plugin.

To be continued...