=== Category Image(s) === Contributors: coffee2code Donate link: http://coffee2code.com/donate Tags: category, categories, image, icon, post, coffee2code License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Requires at least: 2.2 Tested up to: 3.4 Stable tag: 1.7.3 Version: 1.7.3 Display an image for each category associated with a post. == 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](http://coffee2code.com/wp-plugins/category-images/) | [Plugin Directory Page](http://wordpress.org/extend/plugins/category-images/) | [Author Homepage](http://coffee2code.com) == Installation == 1. Unzip `category-images.zip` inside the `/wp-content/plugins/` directory (or install via the built-in WordPress plugin installer) 1. Activate the plugin through the 'Plugins' admin menu in WordPress 1. 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. 1. 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 = * `` 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: `` * Show all images in an unordered list: `` * Assuming one category per post, just show the category image without further HTML markup: ` 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: `` Do: `` = 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: `` Do: `` = 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: `` Do: `` == Changelog == = 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) == * Add optional arg $post_id (default of false) to c2c_get_the_category_image_list() to allow specifying a post * Send $separator as arg in calls to get_category_parents() * Use get_options() instead of get_settings() * Note compatibility with WP 2.6+, 2.7+, 2.8+ * Update copyright date = 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 == Upgrade Notice == = 1.7.3 = Trivial update: noted compatibility through WP 3.4+; explicitly stated license = 1.7.2 = Trivial update: noted compatibility through WP 3.3+ = 1.7.1 = Trivial update: noted compatibility through WP 3.2+ = 1.7 = Recommended update. Highlights: added multiple hooks to allow customization; made leading and trailing slashes in paths optional; allow sending post_id arg to c2c_get_the_category_image_list(); verified WP 3.0 compatibility; other miscellaneous tweaks and fixes.