Package/plugin/module WordPress

Plugin: Customizable Post Listings

This plugin has been updated! Comments to this post are now closed. For the latest download, documentation, and link for posting new comments related to this plugin, visit the plugin’s new homepage at:
Customizable Post Listings
Scott Reilly
Last updated:
27 September 2004

Display Recent Posts, Recently Commented Posts, Recently Modified Posts, Random Posts, and other post listings using the post information of your choosing in an easily customizable manner. You can narrow post searches by specifying categories and/or authors, among other things.


List of percent substitution tags supported:

%comments_count% // Number of comments for post %comments_fancy% // Fancy reporting of comments: (see get_recent_tagmap()) %comments_url% // URL to top of comments section for post %comments_URL% // Post title linked to the top of the comments section on post's permalink page %last_comment_date% // Date of last comment for post %last_comment_id% // ID for last comment for post %last_comment_URL% // URL to most recent comment for post %last_commenter% // Author of last comment for post %last_commenter_URL // Linked (if author URL provided) of author of last comment for post %post_author% // Author for post %post_author_count% // Number of posts made by post author %post_author_posts% // Link to page of all of post author's posts %post_author_url% // Linked (if URL provided) name of post author %post_content% // Full content of the post %post_date% // Date for post %post_excerpt% // Excerpt for post %post_excerpt_short% // Customizably shorter excerpt, suitable for sidebar usage %post_id% // ID for post %post_modified% // Last modified date for post %post_title% // Title for post %post_url% // URL for post %post_URL% // Post title linked to post's permalink page

  1. Download the file and unzip it into your /wp-content/plugins/ directory.
    Copy and paste the the code ( customizable-post-listings.phps ) into a file called customizable-post-listings.php, and put that file into your /wp-content/plugins/ directory. Please ensure you do not introduce any spaces or other characters before the <?php or after the ?>
  2. Optional: Change configuration options in the file to your liking. In-code comments should help you there.
  3. Activate the plugin from your WordPress admin ‘Plugins’ page.
  4. Include one or more of the templates defined below into a template file (most likely sidebar.php)

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 = '', $include_passworded_posts = false)

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 = '', $include_passworded_posts = false)

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 = '', $include_passworded_posts = false)

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 = '', $include_passworded_posts = false)

  • $num_posts : The number of posts to return; default is 5
  • $format : A string that uses percent substitution tags to define the data you want displayed for each listing and how you want it displayed;set it to ” (two single-quotes) to return an array of the requested post objects without outputting anything.
  • $categories : A space separated list of category IDs to match against; leave empty to consider posts from any category
  • $order : The order with which the post listing should be sorted, either ‘ASC’ (for ascending) or ‘DESC’ (for descending); default is ‘DESC’
  • $offset : The number of posts to skip; default is 0
  • $date_format : Date format string, PHP-style, if different from the blog’s default date-format string
  • $authors : A space separated list of author IDs to match against; leave empty to consider posts from any blog author
  • $include_passworded_posts : A boolean value, either ‘true’ or ‘false’, indicating if passworded posts should be considered in the post search
Tips & Examples:

The “Recent” listings on the sidebar of this site all use this plugin.

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:

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

Would output something like:

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

Would output something like:

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:

Release Log:
  • 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
Copyright & Disclaimer:

Copyright (c) 2004 by Scott Reilly (aka coffee2code)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.



234 replies on “Plugin: Customizable Post Listings”

I successfully installed your cool spellchecker program, and it kicks in, but then I get this crazy error:

“/usr/local/share/aspell/en_US.dat can not be opened to read”

My webhost is, and they suggested to try ‘en_US.multi’ which I did, and got the same error.

Any suggestions?

Thank you very much.

Mark Bishop

Anton: Your question is probably a multi-part question, with different answers for different parts. So it really depends on what exactly you are asking for. The “loop” does set global variables that other functions rely upon for typical “in the loop” sorts of activities, in which case many of those functions wouldn’t work properly. I’m sure there are certain sorts of things that could be added to this plugin, or could be hacked in some way. Point out specific things you are looking to do and I can tell you how necessary the loop is for them.

Pierre: I anticipate improved category support, including the case which you brought up, in a future version. Complex category handling can be tricky, so how much I implement and when is still up in the air.

Nathan: Rest assured a comment_excerpt substitution tag will be included in the next release.

Mark: You have the wrong plugin developer. You probably want ColdForged.

I just downloaded this plugin yesterday.

I was trying to get recently_commented to output the date of the last comment, the name of the commenter link to the actual comment, and the title of post comment is in which is permalinked.

I don’t know much php, I can kinda read it, but not enough to code myself. Anyway, I played and played with the configurations to get it to do what I wanted, but it just wouldn’t do it.

You have %last_comment_url% defined in your code, so I had tried using that, but it just spit out %last_comment_url% on the page. It turns out that in the array at the bottom of your code, you have %last_comment_URL%, instead of %last_comment_url%. I made the slight adjustment in the array list and then wrapped %last_comment_url% in link html, and put that around %last_commenter% and now it does what I want. πŸ™‚ Yeah.

Oh, I also thought I’d mention that for %last_commenter_URL%, if a URL is not provided for the comment author, the author’s name is still clickable, but is directed to the current page.

Thanks for another awesome plugin! πŸ™‚

I’m very new to this system, and this is the first plugin im attempting to use.

I have problems installing it though:

I followed the installation instructions but it does not work. I simply placed the function:

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 = '',
 $include_passworded_posts = false)

in the index.php as it said, between line. If I add a ‘{‘ it bring up yet another error.

Can anyone explain what I am doing wrong?

oops sorry. For some reason it didn’t post this part of the message:

Parse error: parse error, unexpected ‘;’, expecting ‘{‘ in /home/fhlinux198/i/ on line 64

That is the error i get in my index.php

ColdForged: Heh; I’ve got my holds full with what I’ve got going here πŸ™‚ Incidentally, I’ve finally begun updating the plugin. I’m doing it in various stages; the interim steps are visible at I’ll probably be able to roll in most of your customizations, except for the post_view_count stuff, which probably goes beyond the scope of this plugin. Thanks for contributing!

Valerie: Thanks for pointing out those bugs. Their fixes will be in the next release.

Dan: What you pasted into index.php was the code defining the function and not the code that calls the function. Look under the Tips & Examples section for what you want to put into index.php. Namely, you’d want something like:

<?php c2c_get_recent_posts(); ?>

I got it working, it was my stupidity.

One more question: is it possible to have more than one class streamreader in a page? I wanted to draw the “get recent posts” from a different database to that of another on the page. Instead an error of: Fatal error: Cannot redeclare class streamreader in /home/fhlinux198/i/ on line 26

Thanks for another great plug-in, Scott!

I’ve got this up and running at om WP 1.5 but there’s one problem.

Where I’m using %last_comment_URL% it’s displaying but the permalink to the comment is actually

Should I just manually make the link like: %post_url%/#comment-%last_comment_id% ?

Ruby: a couple questions — there is a typo in the code… search for “%last_comment_URL%” (with the quotes) and replace it with “%last_comment_url%” (again, with the quotes). Then use the all lowercase version when you define your format string. Does that fix your problem? If not, did the scenario you mentioned work in 1.2 but not in 1.5?

Depending on what you’re looking to do, it may already be done in the latest version of the plugin, which I’m hoping to finish up and release within the next week.

I’m trying the same thing as Nikki [comment 39]. When it is taking the post-excerpt, it is taking/adding paragraph tags so that they end up in within the link and break my vailidation. Is there something in WP (1.5) I can disable or maybe a workaround?

I’m currently using (1,'&lt;a href="%post_url%" title="%post_title%"&gt;%post_excerpt%&lt;/a&gt;','14','date','DESC','0','d F Y','');

The docs state for $format : “A string that uses percent substitution tags to define the data you want displayed for each listing and how you want it displayed;set it to ” (two single-quotes) to return an array of the requested post objects without outputting anything.

I’m using:
$foo=c2c_get_recent_posts(1, $format=’%post_content%’);

but the post_content is still being displayed. I just want it stored in $foo for manipulation. How can I do this?

Thanks for this great plugin, Scott.
I’ve installed this plugin recently and noticed that %comments_count% actually counts all comments including ones marked as ‘spam’ and stored in the database.

So the function c2c_comment_count may be better if reads:

function c2c_comment_count ($post_id) {
  global $wpdb, $tablecomments;
  if (!isset($tablecomments)) $tablecomments = $wpdb-&gt;comments;
  return $wpdb-&gt;get_var("SELECT COUNT(*) FROM $tablecomments WHERE comment_post_ID = '$post_id' <strong>AND comment_approved = '1'</strong>");
} //end function c2c_comment_count()


hey, I tried installing this and I get:

“Parse error: parse error, unexpected T_STRING, expecting ‘&’ or T_VARIABLE or T_CONST in line 33” which is:

Β Β $format = “%post_date%: %post_URL%”,

no matter what type of plugin I try to get a “recent post” list going in my side bar, I get parse errors, was hoping you can help!

Hey, you make amazing plugins! I was just wondering, is it possible to combine this plugin and the custom field plugin? As in, in the format variable of the recent posts function, can I put the to get the input for that recent entry’s custom field into the recent post listing? I figure this is too good to be true and impossible, but I figured I’d check! If not, is there anyway to include an entry’s custom field into the recent listing? Thanks πŸ™‚

I’m liking this plugin but one problem I’m facing is that posts with long titles for recents posts in the side bar seemingly move over tot he content side and push the content down – is there a way to wrap the text so that if the title is long that it continues it on the next line? Or perhaps to create a shorter URI of the link.

SO for example instead of Ben goes shopping to the supermarket it becomes Ben goes….?

Please advise, and thanks in advance

Hi I discovered it was my own XHTML being invalid causing the problems. Works perfectly, my only problem is that the page now invalidates with the plugin – if that makes sense? Any tips one what I can do to get the page valid with the use of the plugin?

If you try to validate you’ll find many ul and li errors listed, this I assume is the output of the plugin in order to create the lists.

Hope you can help.

After enabling this plugin on my site, the site stopped redirecting when the actions (where actions mean: page redirect after post, edit, login, or logout) are taken and shows blank pages. I really need this plugin because this is the only one which enables what I want.

I would like to know, if someone has already faced this before and the solution hopefully. My version is 1.5 strayhorn.

Please help!!

Found a compatibilty problem!

IF you have this and the comments plugin installed, and then try to have activate both you will cause a “duplicate function” error. c2c_comment_count() function is declared in both plugins. Simple, but dodgy fix is just to rename one of the functions :P.. I guess there is a better way around this, however at least that way both plugins will still work independently …