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:
coffee2code.com/wp-plugins/customizable-post-listings
Name:
Customizable Post Listings
Author:
Scott Reilly
Version:
1.1
Last updated:
27 September 2004
Description:

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.

Notes:

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

Installation:
  1. Download the file customizable-post-listings.zip and unzip it into your /wp-content/plugins/ directory.
    -OR-
    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)
Functions:

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.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements:
N/A

234 thoughts on “Plugin: Customizable Post Listings

  1. My host, Dreamhost, has shut my website or my comments down twice because the query run by Customizable Post Listings was using too much server time. You can read about this in detail on my blog, if you want, but here’s a paragraph from a recent email they sent me:

    The query was running a lot (several times a minute? maybe a lot more than that?), it was examining more than 80,000 rows (you should shoot for less than 5000; see the EXPLAIN statement), and quite importantly, it was taking 36 seconds (should take less than one second).

    Part of the problem is that my blog has an extremely active comments section, leading to a huge comments table.

    Do you have any advice for me? I love the CPL plug-in, and would really like to continue using it – in fact, it’s essential for a blog like mine, in which conversations can continue for weeks on one blog comments thread. But, obviously, I can’t run it if it causes DreamHost to shut me down.

    Thanks very much for your time, and for creating this plug in.

  2. I need the same function as pierre as I wanted to use this to pull out featured posts from specific categories..

    I was going to use a feature category and then pull out stories which were in both the featured category and the specific “sport” or “news” category.. to create the featured stories seciton..

  3. If you want to use catg name like a tag you can do that:

    find:

            case '%post_title%':
              if (!$title) { $title = the_title('', '', false); }
              $new = $title;
              break;

    after add this:
            case '%catg_title%':
                         $cat_name = get_the_category_by_ID(the_category_ID(false));
                         $new = $cat_name;
               break;

    find this:
    "%post_title%", // Title for post

    after add:
    "%catg_title%", // Title for catg

    After this little tweak you can use %catg_title% to display category name

    Ex.:
    c2c_get_recent_posts('',"%post_URL%%catg_title%%post_excerpt%", '1', 'date', 'DESC','1','','','', false); ?&gt;

  4. I include the below code into my sidebar.php:

    Recent Articles”;
    c2c_get_recent_posts (7,”%post_URL%”,’’,’date’,
    ‘DESC’,1,’m/d/Y’);
    echo “”;
    } ?>

    all I got is this error although i have already activated the plugin.

    Parse error: parse error, unexpected ‘>’

    Please help, Thanks a million

  5. Is it possible to remove the bullet points on the side of each recent comment? (See site under comments header for example). I would like the comments to be flush to the left side. Any help would be greatly appreciated.

  6. I’m having real trouble applying different styles to the date and post title. I want a list which shows date/post, date/post and have a template with a UL and a class to separate the styles. How can this be done?

    Rhanks,

    Sam.

  7. I was looking for a plugin that lists all post headings on my home page and this plugin did the job for me. I just have a simple listing now, but would like to enhance it as below :
    category1 :
    post 1 heading by author
    post 2 heading by author
    …..
    category 2:
    ….

    Any help appreciated ..

  8. Pingback: Aleeya dotNet
  9. I’d like to use this plugin but i can’t get it to work.

    On my mainpage i would like 5 posts (with read more) and below it the headlines off 25 other posts.

    Iam using the Blix theme and wp1.5.2

    What i did:
    – Download & Upload the plugin
    – Activate it
    – Pasted one of the funtions above into the index.php in the exerp(not the regular index.php but the one into the provided by blix, in the same folder as the side bar).

    When i reload the page i get an error.

    Could you please help me out?

  10. Hi Scott, hope you can help. I’m getting double spacing on this :

    On my other theme it looked fine in single spacing, but now it doesnt look very good with my new theme, could you have a quick look at let me know what I might need to tweak?

    Any tips would be greatly appreciated!!
    thx!

  11. Pingback: Matt Brett »
  12. Pingback: Wu Ge’s World

Comments are closed.