Category Image(s)

Author:Scott Reilly
Version:1.7.3
First released:2004-12-21
Last update:2012-06-11
Compatibility:WP 2.2 – 3.4.2
Download:[ zip ]
Description:

Version: 1.7.3

Display an image for each category associated with a post.

Extended Description

Display an image for each category associated with a post.

Notes:

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 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.

Links: Plugin Homepage | Plugin Directory Page | Author Homepage

Find out more at the plugin’s WordPress Plugin Repository page.


Installation

  1. Unzip category-images.zip inside the /wp-content/plugins/ directory (or install via the built-in WordPress plugin installer)
  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.
  4. Make use of the c2c_the_category_image() template function in your template (see examples below).

Template Tags

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

Functions

  • <?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 ) ?>

This displays the image associated with a post’s categories.

Arguments

  • $separator
    Optional argument. The text and/or HTML to appear between each of a post’s category images.

  • $parents
    Optional argument. Allows you to specify if you want ancestor categories of a post’s category to be imaged and linked as well. Valid options are ‘multiple’, ‘single’, and ”. 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)

  • $post_id
    Optional argument. The Post ID. If false, then use the current post (i.e. while in the loop). Default is false.

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 ( is_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 ?>

Filters

The plugin exposes two filters and one action for hooking. Typically, customizations utilizing these hooks would be put into your active theme’s functions.php file, or used by another plugin.

c2c_get_category_image (filter)

The ‘c2c_get_category_image’ hook allows you to use an alternative approach to safely invoke c2c_get_category_image() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

  • same as for c2c_get_category_image()

Example:

Instead of:

`<?php $cat_images = c2c_get_category_image( $cat ); ?>`

Do:

`<?php $cat_images = apply_filters( 'c2c_get_category_image', $cat ); ?>`

c2c_get_the_category_image_list (filter)

The ‘c2c_get_the_category_image_list’ hook allows you to use an alternative approach to safely invoke c2c_get_the_category_image_list() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

  • same as for c2c_get_the_category_image_list()

Example:

Instead of:

`<?php $cat_list = c2c_get_the_category_image_list(); ?>`

Do:

`<?php $cat_list = apply_filters( 'c2c_get_the_category_image_list', '' ); ?>`

c2c_the_category_image (action)

The ‘c2c_the_category_image’ hook allows you to use an alternative approach to safely invoke c2c_the_category_image() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

  • same as for c2c_the_category_image()

Example:

Instead of:

`<?php c2c_the_category_image(); ?>`

Do:

`<?php do_action( 'c2c_the_category_image' ); ?>`

Release Log

1.7.3

  • Re-license as GPLv2 or later (from X11)
  • Add ‘License’ and ‘License URI’ header tags to readme.txt and plugin file
  • Remove ending PHP close tag
  • Note compatibility through WP 3.4+

1.7.2

  • Note compatibility through WP 3.3+
  • Add link to plugin directory page to readme.txt
  • Note many TODO ideas
  • Update copyright date (2012)

1.7.1

  • Note compatibility through WP 3.2+
  • Minor code formatting changes (spacing)
  • Minor readme.txt formatting changes
  • Add plugin homepage and author links in description in readme.txt
  • Update copyright date (2011)

1.7

  • Rename filter ‘c2c_the_category_image’ to ‘c2c_category_image_list’
  • Add hooks ‘c2c_get_category_image’ (filter), ‘c2c_get_the_category_image_list’ (filter), and ‘c2c_the_category_image’ (action) to respond to the function of the same name so that users can use the apply_filters() or do_action() notation for invoking template tags
  • Change to make leading and trailing forward slashes optional for $image_dir value
  • Wrap each global function in function_exists() check
  • Remove docs from top of plugin file (all that and more are in readme.txt)
  • Note compatibility with WP 2.9+, 3.0+
  • Minor tweaks to code formatting (spacing)
  • Add Changelog, Filters, and Upgrade Notice sections to readme.txt
  • Add PHPDoc documentation
  • Add package info to top of plugin file
  • Update copyright date
  • Remove trailing whitespace

1.6 (unreleased)

1.5

  • Move plugin into its own sub-directory
  • Lots of changes to ensure compatibility with latest releases of WP
  • Add function c2c_get_the_category_image_list() and move code from c2c_the_category_image() into it (but non-echoing though)
  • Change c2c_the_category_image() to simply echo result of c2c_get_the_category_image_list()
  • Use $cat->name instead $cat->cat_name
  • Use term_id instead of cat_ID
  • Allow filter of result via the filter named “c2c_the_category_image”.
  • Add readme.txt
  • Minor code formatting changes
  • Add installation instructions
  • Change plugin description
  • Change Plugin URI
  • Change Author URI
  • Note compatibility with WP 2.3+, 2.5+
  • Update copyright date

1.2

  • Compatibility fix for WP1.5.1

1.1

  • Same as v1.0 but compatible with WP1.5+
  • Change to accommodate new get_category_link() arguments

1.0

  • Last version compatible with WP 1.2
  • Add 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)
  • Change default category images directory from /wp-images/ to /wp-content/images/

0.92

  • Fix a pair of typos that prevented images from showing

0.91

  • 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()
  • Change from BSD-new license to MIT license

0.9

  • Initial public release

Copyright & Disclaimer

Copyright © 2004-2015 by Scott Reilly (aka coffee2code)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.


Discussion / Support

Have any questions, comments, or suggestions? Please provide them via the plugin’s WordPress.org support forum. I’ll do my best to reply in a timely fashion and help as best I can.

Unfortunately, I cannot provide guaranteed support, nor do I provide support via any other means.

Was this plugin useful useful to you? Consider giving it a rating. If you’re inclined to give it a poor rating, please first post to the support forum to give me a chance to address or explain the situation.