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 coffee2code.com/wp-plugins/customizable-post-listings.

Highlights

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