I just completed 14 Days of WordPress Plugins + 7 Bonus Plugins!

Category Image(s)

Author:Scott Reilly
Version:1.5
Last update:14 April 2008
Compatibility:WP 2.2+, 2.3+ and 2.5+
Comments:go here
Download:[ zip ]
Description:

Display an image for each category associated with a post.

Extended Description

This plugin provides the templates tag c2c_the_category_image() which basically reproduces and extends the functionality of WordPress’s core function the_category() to add the ability to display a category image instead of the category name in the link to the category archive. With its $image_extensions argument defaulted to "", the plugin could be a drop-in replacement for the_category(). As is done in the_category(), the image or text for each category is also a link back to that category’s archive.

Related info about the function:

  • If $image_extensions is defined, but no image is found for the category, then nothing is displayed for that category.
  • $image_extensions can be defined as a space separated list of image extensions. Files will be checked with the image extensions in the order those extensions were provided; default is ‘png gif jpg’.
  • The number of category links/images displayed can be limited via the $limit argument
  • Category image <img> tags are defined with class=”catimage” for stylesheet manipulation.
  • The result can be filtered via the filter named “c2c_the_category_image”.
  • Must be run inside “the loop.”
  • c2c_get_category_image_list() is another provided function, which is identical to c2c_the_category_image() except that it doesn’t echo the result.

c2c_get_category_image_list() is another provided function, which is identical to c2c_the_category_image() except that it doesn’t echo the result.


Installation

  1. Download the file category-images.zip and unzip it into your wp-content/plugins/ directory.
  2. Activate the plugin through the ‘Plugins’ admin menu in WordPress.
  3. Create category image (.png unless you specify the extension in your call to c2c_the_category_image()) for each category you wish to have an image for, placing the image into the wp-content/images/ directory (unless you specify another location in your call to c2c_the_category_image()). Remember to give the filename the nice-name version of the category name (see note above).
  4. Make use of the c2c_the_category_image() template function in your template (see examples below).

Template Tag

The plugin provides one optional template tag for use in your theme templates.

Function

<?php function c2c_the_category_image(
   $seperator='',
   $parents='',
   $image_extensions='png gif jpg',
   $image_dir='/wp-content/images/',
   $use_name_if_no_image=false,
   $start_from='begin',
   $limit=999 ) ?>

Arguments

  • $separator
    Optional argument. The text and/or HTML to appear between each of a post’s category images.
  • $parent
    Optional argument. Honestly, I’m not quite sure if/when this argument is ever used or what it’s meant for, but I’ve taken it into account to maintain. Default is "".
  • $image_extensions
    Optional argument. A space-separated list of image extensions (case insensitive). If defined as "" then no image is retrieved and the category name is displayed instead (a la the_category()). Default is ‘png gif jpg’.
  • $image_dir
    Optional argument. The directory in which the category image(s) reside. The value should be a location relative to the main URL of your blog. Default is ‘/wp-content/images/’
  • $use_name_if_no_image
    Optional argument. Boolean value (true or false) indicating if the name of the category should be displayed for each category that does not have an associated image. Default is false.
  • $start_from
    Optional argument. How to traverse the list of post’s categories; either ‘begin’ or ‘end’. Default is ‘begin’
  • $limit
    Optional argument. The maximum number of category images to be displayed. Default is 999 (basically, no limit)

Tips & Examples

  • You can opt to treat only certain categories as having a graphical representation by defining an image for them but not creating images for the non-graphically represented categories (as in you can have a subset of categories that dictate what image to be displayed for the post).

  • You can take advantage of the $image_extension and/or $image_dir arguments to display different category icons under different contexts, i.e. if showing a $single post, choose to use a ‘png’ image, otherwise use ‘gif’; or locate your images in different directories ‘/wp-content/images/cat-images/small/’ and ‘/wp-content/images/cat-images/large/’ and decide based on context where to get the image(s) from:

    
  // In showing the post singularly, then use a larger image, else use a small image
  if ($single) {
  c2c_the_category_image('', '', 'gif', '/wp-content/images/cat-images/large/');
  } else {
  c2c_the_category_image('', '', 'gif', '/wp-content/images/cat-images/small/');
  }

  • Show all images in a comma-separated line:

    <?php c2c_the_category_image(', '); ?>

  • Show all images in an unordered list:

    <?php c2c_the_category_image();?>

  • Assuming one category per post, just show the category image without further HTML markup:

    <?php c2c_the_category_image(' '); // note the space in the argument, necessary to turn off default <ul> markups ?>


Release Log

  • 14 Apr 2008 : v1.5 — Release notes.
  • NOTE: Documentation and discussion about versions of this plugin earlier that v1.5 can be found here.
  • 17 May 2005: v1.2 released — Compatibility fix for WP1.5.1
  • 23 Mar 2005: v1.1 released — Same as v1.0 but compatible with WP1.5+
    • Change to accommodate new get_category_link() arguments
  • 23 Mar 2005: v1.0 released — Last version compatible with WP1.2. Changes include:
    • Added argument $use_name_if_no_image=false to allow showing cat name if no image was located
    • Tweaks to update c2c_the_category_image() with changes made to the_category() (mostly rel= stuff)
    • Changed default category images directory from /wp-images/ to /wp-content/images/
  • 12 Oct 2004 : v0.92 released — Fixed a pair of typos that prevented images from showing
  • 23 Sep 2004 : v0.91 released —
    • Now supports listing multiple image extensions
    • Prepended all functions with “c2c_” to avoid potential function name collision with other plugins or future core functions… NOTE: If you are upgrading from an earlier version of the plugin, you’ll need to change your calls from the_category_image() to c2c_category_image()
    • changed from BSD-new license to MIT license
  • 27 Jun 2004 : v0.9 released to the public

Copyright & Disclaimer

Copyright © 2004-2008 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

Thanks to all those who have contributed feedback and support!