Customizable Post Listings v3.0

With great pleasure I announce the official release of Customizable Post Listings v3.0. This release has been years in the making, and I’m excited to finally let people in on the new features.

The plugin’s official homepage is located at


Here’s a recap of the new features and changes introduced in this new release.

  • Better administration!
    Options are now stored in the database and configurable via the plugin’s new admin options page.
  • Better documentation!
    The plugin’s admin options page includes documentation for all percent-substitution tags (54!), pseudo-function percent-substitution tags (5), template tags (4), and their arguments.
    Also, the plugin distribution zip file contains a readme.txt.
  • More features!
    • Almost three dozen new percent-substitution tags!
    • New feature of pseudo-function percent-substitution tags that are more dynamic than regular tags! (get custom field values, specially format a date, or call your own function!)
    • Can be used to find posts without formatting them!
    • Can be used to format posts you’ve already found!
    • List drafts, pending, or future posts, pages, recent commenters to a post, exclude categories and/or authors, and more, like never before!
  • Updated support for WordPress!
    Test through WP 2.3.3 and 2.5
    Support added for post_status, post_type, taxonomy, tags, etc
  • NOTE: Not fully compatible with how you may have been using older versions of this plugin

Not bad for a plugin 3.5+ years old and counting…

Kicking things off for coffee2code’s 14 Days of Plugins (updated plugin #1)…

Detailed ChangeLog follows after the cut…

NOTE: Users of any older version of Customizable Post Listings will want to review their usage and compare it to the new arguments for the various functions. More than likely you will have to change the way in which you call the functions! If no posts appear, or the posts that appear are not the posts you were expecting, this is probably the reason why…

Detailed ChangeLog

These are the detailed changes, which may or may not make sense to you depending on your familiarity with the previous features and internals of the plugin.

  • Added admin options page under Options → CPL (or in WP 2.5+: Settings → CPL). Formatting options are now saved to database, negating need to customize code within the plugin source file.
  • Admin options page also includes a listing and explanation of all percent-substitution tags, pseudo-function percent-substitution tags, template functions, and their arguments
  • The plugin now also works for drafts, and future-posts due to the addition of $post_status as an argument to the template functions, which can be used to specify a space-separated list of valid post_status values (i.e. ‘publish’, ‘draft’, ‘private’, ‘pending’, and/or ‘future’) (‘publish’ is the default)
  • The plugin now also works for pages due to the addition of $post_type as an argument to the template functions, which can be used to specify a space-separated list of valid post_type values (i.e. ‘post’, ‘page’, and/or ‘attachment’) (‘post’ is the default)
  • Fixed category support to now query against the taxonomy tables
    (no more “WordPress database error: [Table ‘wp_post2cat’ doesn’t exist]” errors)
  • Introduced the following new percent-substitution tags:
    • allcomments_count
    • allcomments_fancy
    • comments_count_URL
    • comments_fancy_URL
    • last_comment_excerpt
    • last_comment_excerpt_URL
    • last_comment_time
    • pingbacks_count
    • pingbacks_fancy
    • post_author_description
    • post_author_email
    • post_author_firstname
    • post_author_id
    • post_author_lastname
    • post_author_login
    • post_author_nickname
    • post_categories
    • post_categories_URL
    • post_content_full
    • post_content_upto_more
    • post_excerpt_full
    • post_guid
    • post_lat
    • post_lon
    • post_name
    • post_status
    • post_tags
    • post_tags_URL
    • post_time
    • post_type
    • post_URL_short
    • trackbacks_count
    • trackbacks_fancy
  • Introduced new concept of pseudo-function percent-substitution tags:
    • %post_custom(field,format,none)%
      A lite version of the Get Custom Field Values plugin to display custom fields.
    • %post_date(date_format)%
      Displays the post’s publication date using a custom date format, overriding the configured default format.
    • %post_other(other_field)%
      Retrieve the value of any post table field. This is useful for accessing a field that does not already have a percent-substitution tag counterpart (generally for fields added to the posts table by another plugin or for when WordPress updates the posts table to include something this plugin hasn’t been updated to handle yet), or if you need to programmatically determine what field you want during runtime.
    • %last_commenters(limit,more,between)%
      Lists the most recent commenters to the post.
    • %function(function_name,arg1,arg2,…)%
      Calls an arbitrary function (which can be sent percent-substitution tags which will get evaluated before the call)
  • The $categories argument now allows for multiple exclusions (any category in the list marked for exclusion means ALL categories listed are excluded; can’t mix inclusions and exclusions yet)
  • The $authors argument is now also handled like $categories (i.e. multiple exclusions, etc)
  • The $orderby argument now allows for SQL to be directly passed, instead of assuming the value relates to a post_* field. The value must be prepended with “SQL:” in order to be recognized as an SQL snippet, i.e. “SQL:SUBSTRING(posts.post_title,POSITION(‘ ‘ IN posts.post_title)+1)” would order posts by the second word in the title
  • Added extra optional argument $extra_sql_where_clause to allow customization of the query
  • %post_content% and %post_excerpt% are now stripped of <p> and <br /> HTML tags (use the new _full% version of those tags if you wish to retain those HTML tags). (I contend that filters need to run against the content; however, to negate wpautop and its cohorts which you may normally want but don’t want in the sidebar, I figured stripping of <p> and <br> tags is reasonable)
  • For %post_excerpt%, apply the filter ‘the_excerpt’ instead of trimming and stripping tags here
  • Fix that %last_comment_URL% should’ve been %last_comment_url%
  • For %post_author%, %post_author_posts%, and %post_author_url% : use get_the_author() instead of the_author()
  • For %post_author_url%, use get_the_author_url() instead of $authordata->user_url; added rel=”external” to link
  • c2c_get_recent_tagmap() now optionally echoes the string it creates via optional argument $echo (defaulted to false)
  • c2c_get_recent_tagmap() now returns the number of posts listed if $echo is true, otherwise it returns the string it would’ve echoed
  • Added new function c2c_get_get_custom() (a mini version of Get Custom Field Values plugin)
  • Fixed function naming conflict that prevented both this plugin and the Customizable Comment Listings plugin from being simultaneously active.
  • c2c_comment_count() now properly only considers comments that have been approved; it also now has an optional $comment_types argument, a space-separated list of valid comment_types (allows for counting any combination of comments, pingbacks, and trackbacks)
  • Added new internal settings: pingback_fancy, trackback_fancy, between_categories, between tags,, comment_excerpt_words, comment_excerpt_length, time_format, post_URL_short_words, post_URL_short_length
  • Removed idmode setting
  • Removed pre-WordPress2.3 support
  • WP2.x+ compatibility changes/improvements including: triggering of new filters and using newer stock accessor functions.
  • Aliased tablenames in SQL queries
  • Added help text about additional post_statuses and post_types
  • Changed description
  • Updated copyright date and version to 3.0
  • Added readme.txt and screenshots
  • Tested compatibility with WP 2.3.3 and 2.5

20 thoughts on “Customizable Post Listings v3.0

  1. Hi Scott,

    i like your plugin a lot and updated it today “right away”. But there seems to be a problem with some SQL-part. Maybe i am wrong but i think it should be
    $sql = "SELECT posts.*, MAX(comment_date) AS max_comment_date FROM $wpdb->comments AS comments, $wpdb->posts AS posts ";
    in line 629. The original part did not work – at least for me…

  2. Hi, thanks for keeping this updated! I just upgraded to WP 2.5 and had to make the necessary adjustments with various plugins.

    I’m having a problem using %post_excerpt%. In posts that don’t explicitly contain an excerpt, this plugin used to take the first words of the post itself. Now it seems to get confused. Is there any way to get that functionality back?

  3. Stéphane: Did you try using %post_excerpt_short%? That one uses the excerpt settings in the plugin’s admin options page to determine how many words or characters to use to make a short excerpt.

  4. Scott, thanks for your reply. Indeed I did try to use %post_excerpt_short% but found it to behave very oddly. All the other functions seem to be working, but for some reason, those related to the excerpt are not being properly displayed. I realize this isn’t very much for you to work from but the problem seems to depend on the context of the page. Given a certain page the excerpt doesn’t seem to follow the loop, it always gives the same output even though functions such as %post_URL% work properly.

  5. I was able to circumvent the problem but in the meantime I found something different. I was able to get the pseudo-function %function% to work with another plugin (star ratings) but using it in c2c_get_recent_posts, the output of %function% comes before anything else.

    For instance, if I use the following code: <?php c2c_get_recent_posts ($num_posts = 4,$format = "<li>%post_date% %post_URL% %function(sr_getsingle,%post_id%)%</li>",$categories = '20',$orderby = 'date',$order = 'DESC',$offset = 1,$date_format = 'M jS',$authors = '',$include_passworded_posts = false)?>

    The output of %function% appears before %post_date% %post_URL%

    Is this a bug?

  6. Stéphane: You were right; there was a bug related to the various post_excerpt tags. I have a confirmed fix for it, which will be released this week.

    Regarding your second issue, I don’t think that’s a bug. I believe the function that you are invoking, “sr_getsingle”, echoes its result when it is called. Since it is called while the post list is being assembled, that value will appear before your listing (and seemingly out of sequence). The key with using %function()% is that the function you call needs to return its result and not echo it. I’m not sure if the plugin you are are using (that is providing “sr_getsingle”) has a non-echoing version of the function or not, or if you can tell it not to echo.

    I’ll put it on the todo list to add an alternative to %function()% that will capture text that would’ve been output by a function and integrate it into the listing.


  7. Fantastic! I modified the function “sr_getsingle” (from Star Ratings) to return the result rather than echo it, it works! Thanks again for your excellent plugins and helpful support.

  8. Hello Scott:
    I didn’t realize you had a thread here for the latest version of your plugin, so please ignore my email to you.

    I’ve managed to figure out things, and it’s an awesome plugin! Once it works on my site, I plan to send a little donation love your way.

    Thanks again!

  9. Hi, Scott.
    Thank you for this great plugin. I use CPL 3.0.1 in my site (I can’t find comment form in 3.0.1 homepage so I write here. Sorry for this).

    Because I’m a complete newbie in programming, I just copy some syntax you posted on the plugin homepage. However the results for random post function are not as given. When I used:

    if (function_exists(‘c2c_get_random_posts’)) { c2c_get_random_posts(3, “%post_date%: %post_URL% by: %post_author_posts%%post_excerpt%”, “151 152”); }

    date, URL and author seem correctly displayed, but all of the three excerpts are similar. This problem is worsened as these three excerpts are not taken from one of the three displayed titles but always from my latest (most recent) post. Is my code incorrect? Thanks

  10. Hi Scott.

    This plugin is such a godsend for quickly adapting wordpress into almost any kind of CMS. I really hope you keep updating this as you have been. That’s always a concern when so much of a site’s functionality can begin to rely on such incredibly useful plugins… but I’m sure you know that already!

    There’s only one thing I would add to the wishlist if I could. I’d love to be able to show the comments enabled/disabled status of a post (perhaps with customisable text).

    I’m toying with the idea of using your plugin to display posts in a category as trouble tickets, and I’d like to use wordpress’ option to turn off comments as a way of closing tickets – so it would be great if the status could be displayed as Open/Closed or whatever.

    Cheers for your great work.

  11. Thanks so much for these plugins and for keeping them updated. Very much appreciated!

    I ran across an interesting way of showing recently commented posts that you might be interested in. It’s a non-WP blog, but it displays information similar to what you can show with c2c_get_recently_commented. The interesting difference to me is what is put in the ‘title’ field for the link – which then shows as a ‘tooltip’ when a user hovers. Your version says ‘View comment by (author)’ but their version shows an excerpt of the comment itself. Interesting! The site is here: and it’s the green ‘New Comments’ column.

    Anyway, just thought it might make an interesting option for some future version of CPL. Thanks again for your hard work!

  12. Hey I don’t really know my way around this kind of stuff but the $categories = ” function doesnt seem to be working for me. I’m using wordpress 2.8.4 if that changes things. Everything else is fine.

  13. I’d like to get random posts or recent posts with a specific tag. I see that I can get them for a specific category, but that’s not really what I need. Am I missing something?

Leave a Reply

Your email address will not be published.