=== Customizable Comment Listings ===
Contributors: coffee2code
Donate link: http://coffee2code.com
Tags: comments, commenters, listings, query, recent comments, top commenters, recent commenters
Requires at least: 2.3
Tested up to: 2.5
Stable tag: trunk
Version: 2.0

Easily find comments (including pingbacks and/or trackbacks) or commenters and list and display anything about them or their related post in the manner you want.

== Description ==

Easily find comments (including pingbacks and/or trackbacks) or commenters and list and display anything about them or their related post in the manner you want.

You can search for and display Recent Comments, Pingbacks, and/or Trackbacks, Top Commenters, or Recent Commenters, and use the comment, commenter, and/or post information of your choosing to customize the how they are listed.  You can narrow comment searches by specifying post IDs, comment types, and/or comment status, among other things.

== Installation ==

1. Unzip `customizable-comment-listings.zip` inside the `/wp-content/plugins/` directory, or copy `customizable-comment-listings.php` into `/wp-content/plugins/`
1. Activate the plugin through the 'Plugins' admin menu in WordPress
1. Go to the new `Options` -> `CCL` (or in WP 2.5: `Settings` -> `CCL`) admin options page.  Optionally customize the settings.  You can read documentation on the template tags, arguments, and percent-substitution tags there as well.
1. In your sidebar.php (or other template file), insert calls to comment and/or commenter listings function(s) provided by the plugin.

== Template Tags ==

The plugin provides three optional template tags for use in your theme templates.

= Functions =

* Highly customizable way to retrieve and display comments.

`<?php function c2c_get_recent_comments( $limit = 5,
  $format = "<li>%comment_author%: %comment_excerpt_URL%?</li>",
  $types = 'comment pingback trackback',
  $status = '1',
  $ids = '',
  $order = 'DESC',
  $offset = 0,
  $date_format = 'm/d/Y' ) ?>`

* Get top commenters
`<?php function c2c_get_top_commenters( \$limit = 5,
  $format = "<li>%comment_author_URL% (%total_comments%)</li>",
  $types = 'comment pingback trackback',
  $status = '1',
  $ids = '',
  $order = 'DESC',
  $offset = 0,
  $date_format = 'm/d/Y' ) ?>`

* Get recent commenters
`<?php function c2c_get_recent_commenters( \$limit = 5,
  $format = "<li>%comment_author%: %comment_excerpt_URL%</li>",
  $types = 'comment pingback trackback',
  $status = '1',
  $ids = '',
  $order = 'DESC',
  $offset = 0,
  $date_format = 'm/d/Y' ) ?>`

= Arguments =

* `$limit`
The number of comments/commenters to list.
Default: `5`

* `$format`
String containing percent-substitution tags and text to be displayed for each comment/commenter retrieved.

* `$type`
(optional) Space-separated list of comment types to include -- leave empty to search for all types of comments, otherwise specify one or more of: 'comment', 'pingback', or 'trackback'.
Default value: `'comment pingback trackback'`

* `$order`
(optional) Indicates whether the comments/commenters should be listed in ascending or descending order.
Possible values: `'ASC'` or `'DESC'`
Default value: `'DESC'`

* `$offset`
(optional) Number of comments/commenters to skip from the beginning of the list of posts found.
Default value: `0`

* `$date_format`
(optional) Date format, PHP-style, to use to format any dates.  If set to `''`, then the blog default date format of
`'$default_date'` will be used.  Keep in mind that the template functions provide their own date format.
Possible values: see http://us2.php.net/date for more info on date format strings.
Default value: `'m/d/Y'`

== Examples ==

* `<ul>
   Recent Comments
  <?php c2c_get_recent_comments(3); ?>
</ul>`

* `<ul>Recently Commented
   <?php c2c_get_top_commenters(3); ?>
</ul>`

* `<ul>Recently Updated
   <?php c2c_get_recent_commenters(3); ?>
</ul>`

== Screenshots ==

1. A screenshot of the admin options page for the plugin showing the options input fields.
2. A screenshot of the admin options page for the plugin showing the percent-substitution tag documentation.
3. A screenshot of the admin options page for the plugin showing the template function and argument documentation.