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”

This looks very promising ! I already started using it to generate title lists. Where would I toggle a “delimit to last 7 days” function , similar to this Mysql string
” between date_add(current_date, interval -7 day)
and date_add(current_date, interval 1 day) ” ? All hints are warmly welcomed ! Best Regards
Jonas / Germany

Jonas: Well, as it stands now the plugin doesn’t directly support specifying a date range. I’ll consider such a feature for a future version. I’m open to suggestions, though.

Category exclusions is trickier business, but I have a plan in mind on how to go about doing it. Should be part of the next release for this plugin, but I can’t quote you a date on that. For now, yeah, you’d have to explicitly list all the categories you want.

Everything seems to work as described except when I try to use $authors, which produces the following error:

Warning: Invalid argument supplied for foreach() in /blah/blah/blah/wp-content/plugins/customizable-post-listings.php on line 76

Database error: [You have an error in your SQL syntax near ') GROUP BY wp_posts.ID ORDER BY wp_posts.post_date DESC LIMIT 1, 5' at line 1]
SELECT DISTINCT * FROM wp_posts WHERE wp_posts.post_date <= '2004-09-03 14:49:04' AND wp_posts.post_status = 'publish' AND wp_posts.post_password = '' AND ( ) GROUP BY wp_posts.ID ORDER BY wp_posts.post_date DESC LIMIT 1, 5

Thanks, but doesn’t seem to do the trick. Tried 1.01 and, using (1, “%post_URL%
%post_excerpt_short%”, “”, “date”, “DESC”, 0, “m/d/Y”, “1”, false), now get:

Warning: Invalid argument supplied for foreach() in /blah/blah/blah/wp-content/plugins/customizable-post-listings.php on line 76

Database error: [You have an error in your SQL syntax near ') GROUP BY wp_posts.ID ORDER BY wp_posts.post_date DESC LIMIT 0, 1' at line 1]
SELECT DISTINCT * FROM wp_posts WHERE wp_posts.post_date <= '2004-09-03 16:05:05' AND wp_posts.post_status = 'publish' AND wp_posts.post_password = '' AND ( ) GROUP BY wp_posts.ID ORDER BY wp_posts.post_date DESC LIMIT 0, 1
Warning: Invalid argument supplied for foreach() in //blah/blah//wp-content/plugins/customizable-post-listings.php on line 140

Hmm, it seems to work for me trying what you indicated. It’s almost as if the function isn’t seeing the value of $authors. (The second bug being reported on line 140 is a result of the first bug, and trivial to fix.) You are calling the c2c_get_recent_posts() function, or one of the other two? Would you be up for me suggesting some debugging suggestions (or I could send you some debugging versions of the plugin) to try to track down the problem?

I am using the sticky posts hack and due to this I get this error for the comment part.

Warning: Invalid argument supplied for foreach() in c:\sites\single1\easydoesit\webroot\wp-content\plugins\customizable-post-listings.php on line 140

I’m sure Ill get this when my lates post becomes a sticky too.
Do you have a way to get around this because I really want this plugin on my site.

OK so I figured it out.

You have the line:
$sql .= "WHERE $tableposts.post_date <= '$now' AND $tableposts.post_status = 'publish' ";

which of course insures that it only looks for published posts but I have a value that is ‘sticky’ in my post_status field.

I changed the line to:
$sql .= "WHERE $tableposts.post_date <= '$now' AND $tableposts.post_status != 'draft' AND $tableposts.post_status != 'static' AND $tableposts.post_status != 'private'";

so that it would look at the ‘publish’ and ‘sticky’ posts.

I originally tried:
$sql .= "WHERE $tableposts.post_date <= '$now' AND $tableposts.post_status = 'publish' OR $tableposts.post_status = 'sticky' ";

but this caused wacky extra not commented posts. I don’t know why as I’m not a programmer.

Anyways thats how I fixed it.

First off, I have updated the plugin with a slight tweak, so it is now up to version 1.02.

Trevor: If you are comfortable with modifying the plugin code for debugging purposes, obtain the latest and where you see this line:

$auths = explode(' ', $authors);

Add a line before and two after it so it looks like this:

echo "authors = ($authors)<br />"; $auths = explode(' ', $authors); echo "auths ( "; print_r($auths); echo " )<br />"; echo "is_array? (".is_array($auths).")<br />";

Let me know what it says for your site.

mikey: What you tried initially would probably have worked if you added parentheses like so:

$sql .= "WHERE $tableposts.post_date <= '$now' AND ( $tableposts.post_status = 'publish' OR $tableposts.post_status = 'sticky' ) ";

I am considering the addition of this change to the plugin. Thanks for reporting the issue and finding the fix!

Please excuse me if I am being totally dumb here but is there a way that I can fix the dates into a UK format? I have my blog set to display dates in the way that we are used to nd I would like my recent lists to display day before month if at all possible


Beth: You can send the date format as one of the arguments to the function. The date format you want, i.e. 31/08/2004 (Aug 31, 2004), is achieved through the date format of ‘d/m/Y’. You would use that like so:

<?php c2c_get_recent_posts (5, "<li>%post_date%: %post_URL%</li>", '', 'date', 'DESC', 0, 'd/m/Y'); ?>

(you have to explicitly define all the arguments before the $date_format argument)

Or, alternatively, you could change the default value for the $date_format argument for each of the three functions by modifying the plugin file. Which, if you do, you should make note of so that in the event you upgrade the plugin you know what you need to change again (since upgrading will overwrite the plugin file).

Josh: Yes, but you have to change a value within the plugin file itself. Look for these lines in the function c2c_get_recent_tagmap():

//-- Some things you might want to configure -----
$excerpt_words = 6;  // Number of words to use for %post_excerpt_short%
$excerpt_length = 50;   // Number of characters to use for %post_excerpt_short%, only used if $excerpt_words is 0

Modify those to your liking. Keep in mind that in the format string you’ll want to use %post_excerpt_short%, which will honor the above settings, as opposed to %post_excerpt% which is the user- or WP- generated excerpt.

Like the code commenting says, if you want to limit by number of words, change the value of $excerpt_words to something else if the default of 6 doesn’t suit you. Or it you want the excerpt to be limited by number of characters, change $excerpt_words to 0 and change the value of $excerpt_length.

Does that accomplish what you need?

Hi, Scott, another great plugin.
I wonder if it’s possible to use a substitution tag in order to show the name of the category the post belong to, I mean, an output similar to this:
* Personal: post_title …
* Software: post titlel


Trevor: Sorry to have taken so long to follow up with you. On a test blog I tried to recreate your problem but have so far been unsuccessful. I had a second author (with the most recent overall post), and when I indicated I only wanted posts for author ‘1’, the post for author ‘2’ got skipped. If I didn’t specify an author, all posts were considered. And after examing the code, I can’t see a reason why it wouldn’t work like it’s supposed to. I’ll keep looking at it, but so far I’m coming up empty on it.

poper: I’ll add some sort of category substitution tag in the next release.

Thanks Scott. The date problem was easily fixed when I was feeling more alert. Sorry to have been stupid about it – blame Plugin Overload. 🙂

I list all the recent days posts on my blog so really would like the Recent list to list the previous n posts on days!=today.

Can that be done?



Matt: Thanks for the suggestion. I will include the ability to get random posts in the next release, which should be within the next few days.

Beth: Currently the plugin only supports skipping N posts and not posts from the last N days (where for your scenario N would be 1). Unless, of course, you only posted a certain number of posts per day or something. Otherwise, I’ll contemplate a way to honor the request, though no guarentees.

great plugin scott, i’m just going to implement it on a site.

using the most recent posts function, is there an easy way of only printing the date once, so you get a date, followed by all of the posts under that date, without printing another date until all of the posts for that date have been printed, and it is on to another date? eg:

Random Post 1
Random Post 2
Random Post 3

Random Post 4
Random Post 5 etc. ?

Hey, I just installed your plugin(nice!) there was only one problem…I put in the recenty posts ,recently commented, and recently updated.
The recent posts and recently commented worked fun but recently updated did not work at all and said function not found( i think) i browsed through the comments here and didnt see anything.. so i decided to go view your code..thinkin that it cant be that bad..and i found that you didnt have

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

as a variable…and i saw one that said modified instead of updated so i changed updated to modifiend so it looked like

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

instead and it worked fine!

Thank you Scott.

I’ve been looking at the code to see if I can modify it to meet a request from my users but a dunce like me needs significantly more comments in the code before attempting such ambition.

My users would like a single list of recently updated/added material so that new posts, edited posts, AND commented posts all appear in the one list. I’m trying to make get_recently_modified to do the trick for me and failing miserably. I *think* what my users want to see is a single list that would give:

Post Subject with link, Number of Comments – may be zero if new post – with link to most recent comment, and Author/Date/Time of the post/comment most recently added or edited.

I said I would try but it seems beyond me. Can you offer any pointers on where to modify the code in order to get a single list?


tom: I’ll consider your suggestion. There would be a number of changes necessary to accomplish what you ask, and I’m trying to be mindful of maintaining a balance of ease-of-use and complexity.

littleman09z: Oops, thanks for that catch. You’re right, the examples section referred to the non-existant c2c_get_recently_updated. As you figured out, the function I meant to write (and have now fixed) was c2c_get_recently_modified.

Beth: Take a look at the sidebar and you’ll see a “For Beth” section (this’ll be temporary). It is a recently_modified listing that includes information about each listed post’s most recent comment/commenter. Granted, it should be more pleasing about reporting non-existent comments. The command to get that list was:

<?php c2c_get_recently_modified(5,'<li>%post_URL% (%comments_count%)<br />Last comment: %last_commenter% at <a href="%last_comment_url%" title="Read the comment">%last_comment_date%</a></li>'); ?>

I could probably add a percent-substitution tag to repesent a link of the last_commenter’s name linked to the comment, and a link of the last comment date to the last comment.

A greater degree of difficulty is added if you want to order the listing based on both the recently-commented dates and recently-modified dates (new posts are considered as being recently modified).

Excellent plugin! I hit one little snag while installing that, hopefully, will have a quick solution:

I need to exlcude category nine (as it is my miniblog) from the ‘Recent Entries’ section of my new design. I’m using the following bit of code:

&lt;?php c2c_get_recent_posts(4, "&lt;dd&gt;%post_URL%&lt;/dd&gt;\n", '1,3,4,5,6,7,8', 'date', 'DESC', 1); ?&gt;

It seems that, in doing so, the posts no longer sort by date – they sort by category, then date. Most of my entries are in categories one and eight and those in category eight are not even being included in the sort.

Any ideas? Thanks in advance.

Thanks for a groovy code!! It took a little fiddling but I was able to use it to post the most recent posts in my “Take Action!” Category on the site. There was a problem at first when I tried to make a post be sticky using another script ( I wasn’t able to make a post sticky AND show up under the most recently posted in a particular category..) but I will take what I can get! Thanks again! =)

Plugin updated to v1.1

This release features these changes:

* 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

The plugin appears to fumble with ampersands in the permalink’s title tag For instance, if the post title is “Jack & Jill” the link title will show Jack &amp;amp; Jill. This results in problems with all html entities, especially the more likely to be used single quotes & double quotes.

I read in the wordpress forums that previous versions of wordpress had these problems, while version 1.2 mingus and up do not.

I edited version 1.1 of your plugin on line 262 changing this:
title="View post '.htmlspecialchars(strip_tags($title)).'"

to this:
title="View post '.$title.'"

This appears to have solved the problem. The html character entities are now being encoded properly into their hex equivalents minus the ampersand problem. I hope the htmlspecialchars section didn’t have any further particular significance I’m unaware of?

It’s a minor problem solved, which makes this an invaluable plugin. I was using a get recent posts “hack” found in the wordpress wiki, but it performed a query for each post retrieved, so if I wanted to retrieve the last 15 posts (offset by 5) it would perform 15 queries. Your version is much faster and only executes a single query.

Scott, I have an suggestion for a feature regarding c2c_get_recent_posts. Let’s say I’m viewing the single/permalink page of a “recent” entry and I’m showing the last 5 recent entries in the sidebar. It would be nice if the recent entries list excluded the permalink page I’m currently viewing from the list. It’s unnecessary to display that particular recent entry link it if I’m currently on that page. Just something to think about.

Tyrone: Thanks for pointing out the issue regarding the use of htmlspecialchars(). I’ll go back and review why I put it there in the first place and verify that it needs taking out. Also, thanks for your other suggestion; I’ll give it some consideration.

Lawrence: WordPress doesn’t keep track of when/how often posts get read, so that information isn’t readily available to this plugin. There are plugins that allow you to keep track of that information. I’m not familiar with how they’re designed. Unless they are designed in a very specific way (by adding visitor counts to a new column in the wp_posts table) it is unlikely you can use this plugin without modification to take advantage of that data. Otherwise, you’ll either have to use another plugin for all your “most popular posts” needs, or modify this plugin to take advantage of the info the other plugin has recorded.

I’m running a photolog, and wanted the previous 4 entries as thumbnails just below. I downloaded your plugin, set the offset to 1 in the file and then used this:

<?php c2c_get_recent_posts(4,'<a href="%post_url%" title="%post_title%">%post_excerpt%</a>'); ?>

Thank you an incredible amount. This SO rocks.
Why didn’t I find it sooner?!


thank you for this killer update to your already very useful plugins.

when you said you “might look into it…” i crossed my fingers, but i bet nobody expected such a comprehensive, well documented, update.


thank you.

i’m having trouble displaying the recent posts from a certain category. the code i’ve tried:

<?php c2c_get_recent_posts(5, "photography"); ?>
<?php c2c_get_recent_posts(5, 'photography'); ?>
<?php c2c_get_recent_posts(5, photography); ?>

photography is a category and there are sufficient posts in it…

Comments are closed.