coffee2code

1. Download the file customizable-post-listings.zip and unzip it into your wp-content/plugins/ directory.
2. Activate the plugin through the ‘Plugins’ admin menu in WordPress
3. Go to the Options → CPL (or in WP 2.5+: Settings → CPL) admin options page. Optionally customize the settings. You can read documentation on the template tags, arguments, and percent-substitution tags there as well.
4. In your sidebar.php (or other template file), insert calls to post listings function(s) provided by the plugin.

These are the template functions made available by this plugins. c2c_get_recent_posts() provides the core
functionality. The other template functions are added as a convenience to provide different default argument values for their
different purposes.

• Get recent posts:
  

  function c2c_get_recent_posts( $num_posts = 5,
    $format = "<li>%post_date%: %post_URL%</li>",
    $categories = '',
    $orderby = 'date',
    $order = 'DESC',
    $offset = 0,
    $date_format = 'm/d/Y',
    $authors = '',
    $post_type = 'post',
    $post_status = 'publish',
    $nclude_passworded_posts = false,
    $extra_sql_where_clause = '' )
  

• Get Random Posts
  

  
  function c2c_get_random_posts( $num_posts = 5,
    $format = "<li>%post_date%: %post_URL%</li>",
    $categories = '',
    $order = 'DESC',
    $offset = 0,
    $date_format = 'm/d/Y',
    $authors = '',
    $post_type = 'post',
    $post_status = 'publish',
    $include_passworded_posts = false )
  

• Get Recently Commented Posts
  

  
  function c2c_get_recently_commented( $num_posts = 5, 
    $format = "<li>%comments_URL%<br />%last_comment_date%<br />%comments_fancy%</li>",
    $categories = '',
    $order = 'DESC',
    $offset = 0,
    $date_format = 'm/d/Y h:i a',
    $authors = '',
    $post_type = 'post',
    $post_status = 'publish',
    $include_passworded_posts = false )
  

• Get Recently Modified Posts
  

  
  function c2c_get_recently_modified( $num_posts = 5,
    $format = "<li>%post_URL%<br />Updated: %post_modified%</li>",
    $categories = '',
    $order = 'DESC',
    $offset = 0,
    $date_format = 'm/d/Y',
    $authors = '',
    $post_type = 'post',
    $post_status = 'publish',
    $include_passworded_posts = false )
  

Arguments:

$num_posts

The number of posts to list.

Default: 5

$format

String containing percent-substitution tags and text to be displayed for each post retrieved.

$categories

Optional. Space-separated list of category IDs — leave empty to search for posts regardless of category.

Default value: ''

$orderby

Optional. The post field to be used as the sort field. Except for a few exceptions, the value provided will assume that post_ will be prepended to it. So a value of 'title' will sort the posts by the
'post_title' field.

Possible values: any post table field that begins with post_. In practice, it’ll likely be one of the following: 'ID', 'date', 'modified', 'name', 'title'. The exceptions to this are:

• rand() : to randomize the order of posts
• max_comment_date : to order by the date of the most recent comment for each post
• SQL:$sql_here : if you’re feeling advanced, you can directly specify the SQL for the ORDER BY clause by prepending SQL: to the $orderby value

Default value: 'date'

$order

Optional. Indicates whether the posts should be listed in ascending or descending order.

Possible values: 'ASC' or 'DESC'

Default value: 'DESC'

$offset

Optional. Number of posts 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'

$authors

Optional. Space-separated list of author IDs — leave empty to search for posts regardless of author.

Default value: ''

$post_type

Optional. Space-separated list of post_type values to consider in the search.

Possible values: post, page, attachment

Default value: 'post'

$post_status

Optional. Space-separated list of post_status values to consider in the search.

Possible values: publish, draft, private, pending, and/or future

Default value: 'publish'

$include_passworded_posts

Optional. Should passworded posts be included in the serach?

Possible values: true or false

Default value: false

$extra_sql_where_clause

Optional. Additional SQL to be added to the query’s WHERE clause, to facilitate refining the post search in a manner not achievable with existing arguments.

Default value: ''

The simplest examples would be the following (for brevity’s sake, in the examples I’m going to specify 3 as the number of posts I want returned):

<ul>
   Recent Posts
  <?php c2c_get_recent_posts(3); ?>
</ul>

Would output something like:

Recent Posts
• 08/03/2004: Patch: Dealing with multiple <!–more–>
• 08/03/2004: Patch: Balancing pre-’more’ tags
• 08/03/2004: Patch: Fixing balanceTags()

<ul>Recently Commented
   <?php c2c_get_recently_commented(3); ?>
</ul>

Would output something like:

Recently Commented
• Plugin: Category Image(s)
  08/23/2004 10:25 am
  14 Comments
• Plugin: Get Custom Field Values
  08/22/2004 04:35 pm
  18 Comments
• Plugin: wpPHPMailer
  08/16/2004 01:15 am
  11 Comments

<ul>Recently Updated
   <?php c2c_get_recently_modified(3); ?>
</ul>

Would output something like:

Recently Updated
• Plugin: Get Custom Field Values
  Updated: 08/22/2004
• Plugin: wpPHPMailer
  Updated: 08/17/2004
• Plugin: Hide or Cut Post Text
  Updated: 08/17/2004

But what you may really want is to run the Recent Posts/Recently Commented Posts/Recently Updated Posts/Random Posts calls and customize the listing output. That’s where the percent substitution tags come into play. The second argument to each of the three functions above is the $format argument. $format is a string that represents how each post found by the function should be output. Any percent tags (as listed and defined above) will be replaced with the appropriate data.

So, let’s say you want a list of recent posts, to include the post author’s name linked to the archive of all of that author’s posts, plus a short excerpt of the post. And let’s say you only want posts from category ‘34′. You’d do this:

<ul>
<?php c2c_get_recent_posts(3, "<li>%post_date%: %post_URL%<br />by: %post_author_posts%<br />%post_excerpt_short%</li>", "34"); ?>
</ul>

Which would output something like:

• 07/25/2004: Plugin: Hide or Cut Post Text
  by: Scott
  I’m pleased to announce the release…
• 07/08/2004: Plugin: Random File
  by: Scott
  I just finished the final touches…
• 07/08/2004: Plugin: Auto-hyperlink URLs
  by: Scott
  Finally, I managed to tackle a…

• 03 Apr 2008 : v3.0.1 - bugfix for SQL construction
• 31 Mar 2008 : v3.0 — Tons of updates! Compatible with WP 2.3+ and 2.5. Follow link for full update information.
• NOTE: Versions prior to v3.0 were documented here
• 27 Sep 2004 : v1.2 –
  • Added the ability to get random posts, and added the convenience function c2c_get_random_posts() to get them
  • Functions will now consider sticky posts (those in which ‘post_status’ gets set to ’sticky’) in addition to published posts
  • Changed license from BSD-new to MIT
• 05 Sep 2004 : v1.02 — Bugfix to immediately return if no posts match criteria
• 03 Sep 2004 : v1.01 — Bugfix for when $authors has more than one author
• 27 Aug 2004 : v1.0 — Released to the public