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”

garnet read the instructions at the top with regards to categories – I do this myself and it works great.

Does anyone know how to specify the number of words or characters for an excerpt. Any chance this level of flexability could be added? The excerpt_short_ is a single line, and exludes any formatting and images, whereas the Excerpt option offers the exclusions but is too big. The configuration of charactes and words would allow a middle ground I Think.

Would be great if it can be added.

Great plugin

dear scott:

I had been blundering through wordpress trying to create a new website with feeds from our webblog all weekend. Then I found your pluggin and it saved me. Thank you, I will always remember.


@ dydrec use offset to exclude posts read the instructions at the top on how to do this.

scott: is there anyway to truncate the title of the URL? I;m using the recent excerpts, but I need to truncate the title to about 5 words or less.


scott: thanx for your great plugin in! One quick question. I’like to list the last 5 post of the author of the current page. I’ve tried with: %post_date% - %post_URL%", "", "date", "DESC","0", "d/m/Y", "'"); ?&gt;, but it doesn’t work. Is it possible to do what i have in mind? Thank you!

I use this plugin to show random posts but sometimes it diplays post titles longer than my sidebar. How can I get shorter titles?

I’d like to truncate the them. Please help.


post title (before):
this is the title number 1

post title (after):
this is the title…

zonekiller I believe scott is working on an update, so just be patient for a while, he’s including truncation of titles, which is something I am very keen to see included as are a few others, so this will be quite an update. looking forward to it

zonekiller I believe scott is working on an update, so just be patient for a while, he’s including truncation of titles, which is something I am very keen to see included as are a few others, so this will be quite an update. looking forward to it

Thank you sekhu!

excellent plugin!

as a feature request, would it be possible to add a variable for limiting the queries by date?

I’m trying to show a random post from a particular category, but only want it to pick from the last 30 days, rather than the entire category’s archive

great plugin-

question: i want to display in my sidebar 5 most recent posts plus short excerpt. but the way i have it set up, the excerpt from the first post repeats itself in the other 4.
here’s what i’m using

[code]%post_date%: %post_URL%-%post_excerpt_short%”)?>[/code]

is this correct?

Using the c2c_get_recent_posts – and I would like omit the post title and have just the date itself be the link to the post. Is there an easy way to do this? So, instead of looking like this:

20050505: This is the title

I want, just the date and for the date to be the new permalink to the post.

Also, don’t know much about php – most everything I do is a painstaking bout of ‘let’s change that and see what happens’ sort of programming. How do I use both the c2c_get_recent_posts and the c2c_comment_count together, so that it prints the comment count after the post title.

Thanks in advance


Another vote for “recent static page” functionality. Essentially I’d like to be able to display the “x” (in my case, either 3 or 5) most recent static pages that are a child of a certain page in the hierarchy.

So, for example, in the context of my site, I’d like to be able to generate a list of the 5 most recent gear reviews (using the Page function, not Posts) which would be displayed in the sidebar template.

You had mentioned a few months ago (above in the comments) that someone could tweak the current release to achieve similar functionality. Is this still the case, or will a new release be available soon?

Your plugin has been very helpful for posts… if I can get it to work with pages, I’ll be very grateful.

hi scott, i’ve just come across a requirement for this for myself, and perhaps something you could add to an update?

I’ve been wanting to place the category for the recent list for an entry.

for example:

category name date of entry post title link excerpt

any chance this could be added to the next version?

Way cool! I think that this is just the thing I was looking for. The ability to define the excerpt is superb.
I am wondering – as a css noob – how do I go about applying css to the elements of this plugin? I have everything in a div which allows me some editing – p, a, etc… For instance, I want to specify how the date looks… I know there is an easy way to go about it.. just haven’t found it yet!

Thanks for a great tool!


Hey, a great plug-in! This is exactly what I need for my website.

However, I’m having trouble showing posts by a single author. I’m adding the code to the author.php page, where I want it to be a profile/bio page + recent posts of that particular author.

I would really like to find a way to make the author id value into a variable, instead of a constant number.

I tried various things including:

[in the plug-in file]
$authors = '$author_id',

[in author.php file]

Please let me know if it is even possible.

– Kevin

I was just wondering when the next release of this plugin is coming out.

I am using it right now to show the 5 most recent posts. I have many categories and it would be nice to be able to list what category the recent post is from.



I’m a rank beginner at WP and php. I’ve found your Customizable Post Listings plugin to be very valuable. First of all: thank you.

I’ve got not only to put a list of recent posts in the sidebar, but also to string a list of titles of the posts on the main page across the top of that page. I was hoping to be able to hotlink the titles in that list to the items themselves on the main page (as opposed to their permalink, single page appearances).

I’m half way there, because I’ve caused my index to create a name anchor using the “the_title” function for each item on the main page.

But when I try to force your $format = "&ldquo;%post_title%&rdquo;, ", to create a link to the named anchor, I get errors no matter how I try. I’ve surrounded your %post_title%with the appropriate markup and have even tried to escape the number sign. No luck. I’ve also tried to substitute the php the_title function for your percent function in the href; again no luck.

Rather than continuing to thrash ignorantly, I thought I’d ask you if you can see a way to accomplish what I want. To repeat: I’m after a list — a table of contents, if you will — for the main page, with each title in the list hotlinked to the item itself on the main page.

Any help would be very greatly appreciated.



Does using this plugin eat into the # of posts set in WP Preference?

I am using it in my sidebar as a sort of “Asides”. In WP Preference, I set to display at least 7 posts. The plugin in my sidebar displays 4 posts from cat1 and the index page, excluding cat1, should at least display 7 posts, but instead only shows 3.

any advice? thanks.

Hi there,

I’d like to display a list of all posts and pages recently updated or posted. With

“); ?>

I get the most recently modified blog posts, displayed in the way I want, but I don’t get pages which were recently modified or posted.

Any way to achieve that? 🙂

Thanks ahead for wrapping your brain around this 😉


I replace braces to show the code – hopefully:

{?php c2c_get_recently_modified(15, “%post_date%: %post_URL%{br /}”); ?}

I’ve been working with MCincubus and mdawaffe to turn the category.php into a customizable category page without using the category-6.php and category-15.php customizable category template technique. We’ve managed to convert all kinds of things into conditional tags that generate content based upon the category and it’s parent, but we’re stuck with a problem with this tag.

query_vars['cat'], "%post_URL%", $cat); ?&gt;

I hope that goes in as code.

During the process, the $num_posts got left out. It was still generating the list, so we didn’t notice until after all the rest of the testing.

I’d like to add back in the number of posts (10), but I can’t get it to work with the query and $cat reference. Any ideas? I’ve tried:

query_vars['cat'], "%post_URL%", $cat); ?&gt;

And using single and double quotes around things, but it totally stops the list from generating. The first one works, it just generates 3 posts in one place, 5 in another, and 15 in another.

Any help would be appreciated. We’re writing this up for the Codex. Thanks!!

Thanks for you plugins it’s very good. I test the Comment post and when i active the plugin give me the follow error…
Fatal error: Cannot redeclare c2c_comment_count() (previously declared in C:\mi webs\wordpress\wp-content\plugins\customizable-comment-listings.php:197) in C:\mi webs\wordpress\wp-content\plugins\customizable-post-listings.php on line 140

help me…thanks.

?? My first comment disappeared. OK, again:

I want to show the real author names instead of the nice names. I am using “%post_author_posts%”

How can I get the real names? Is there a patch already for this?


Help me!!! When i try active the plugin provoque this error: Fatal error: Cannot redeclare c2c_comment_count() (previously declared in C:\mi webs\wordpress\wp-content\plugins\customizable-comment-listings.php:197) in C:\mi webs\wordpress\wp-content\plugins\customizable-post-listings.php on line 140

Help me!!!

Greetings !
In reference to commet:53 above, does anyone have the link to the modified code by ColdForged?? The link provided by coldforged doesnt seem to work. I need the modified code so that i could add links to the fancy comments.

Comments are closed.