Peer Categories

Screenshots

This plugin provides a template tag which acts a modified version of WordPress’s built-in template tag, the_category(). the_category() lists all categories directly assigned to the specified post. c2c_peer_categories() lists those categories PLUS any categories that are peer to those categories and MINUS categories that are parents to other assigned categories. Peer categories are categories that all share the same category parent. For example, assume your category structure is hierarchical and looks like this: Vegetables |-- Leafy | |-- Broccoli | |-- Bok Choy | |-- Celery |-- Fruiting | |-- Bell Pepper | |-- Cucumber | |-- Pumpkin |-- Podded | |-- Chickpea | |-- Lentil | |-- Soybean If you directly assigned the categories “Fruiting” and “Pumpkin” to a post, peer_categories() would return a list that consists of: “Bell Pepper”, “Cucumber”, and “Pumpkin”. Notice that since “Fruiting” was a parent to a directly assigned category, it and its peers are not included in the list. If only “Fruiting” were selected as a category, then “Leafy”, “Fruiting”, and “Podded” would have been listed. By default, categories are listed as an HTML list. The first argument to the template tag allows you to define a custom separator, e.g. to have a simple comma-separated list of peer categories: <?php c2c_peer_categories(','); ?>. As with categories listed via the_category(), categories that are listed are presented as links to the respective category’s archive page. Example usage (based on preceding example): <?php c2c_peer_categories(); ?> Outputs something like: <ul><li><a href="http://yourblog.com/category/fruiting/bell-pepper">Bell Pepper</a></li> <li><a href="http://yourblog.com/category/fruiting/cucumber">Cucumber</a></li> <li><a href="http://yourblog.com/category/fruiting/pumpkin">Pumpkin</a></li></ul> <?php c2c_peer_categories( ',' ); ?></ul> Outputs something like: <a href="http://yourblog.com/category/fruiting/bell-pepper">Bell Pepper</a>, <a href="http://yourblog.com/category/fruiting/cucumber">Cucumber</a>, <a href="http://yourblog.com/category/fruiting/pumpkin">Pumpkin</a> Links: Plugin Homepage | Plugin Directory Page | Author Homepage Template Tags The plugin provides three optional template tag for use in your theme templates. Functions <?php function c2c_peer_categories( $separator = '', $post_id = false ) ?> Outputs the peer categories. <?php function c2c_get_peer_categories_list( $separator = '', $post_id = false ) ?> Gets the list of peer categories. <?php function c2c_get_peer_categories( $post_id = false, $omit_ancestors = true ) ?> Returns the list of peer categories for the specified post. Arguments $separator Optional argument. (string) String to use as the separator. $post_id Optional argument. (int) Post ID. If ‘false’, then the current post is assumed. Default is ‘false’. $omit_ancestors Optional argument. (bool) Should any ancestor categories be omitted from being listed? If false, then only categories that are directly assigned to another directly assigned category are omitted. Default is ‘true’. Examples (See Description section) Filters The plugin is further customizable via five hooks. Code using these filters should ideally be put into a mu-plugin or site-specific plugin (which is beyond the scope of this readme to explain). Less ideally, you could put them in your active theme’s functions.php file. c2c_peer_categories (action), c2c_get_peer_categories_list, c2c_get_peer_categories (filters) These actions and filters allow you to use an alternative approach to safely invoke each of the identically named function in such a way that if the plugin were deactivated or deleted, then your calls to the functions won’t cause errors on your site. Arguments: (see respective functions) Example: Instead of: <?php c2c_peer_categories( ',' ); ?> or Do (respectively): <?php do_action( 'c2c_peer_categories', ',' ); ?> or c2c_peer_categories_list (filter) The ‘c2c_peer_categories_list’ filter allows you to customize or override the return value of the of c2c_peer_categories_list() function. Arguments: string $thelist : the generated list of categories with complete HTML markup, or __( ‘Uncategorized’ ) if the post didn’t have any categories string $separator : the separator specified by the user, or ” if not specified int|false $post_id : the ID of the post, or false to indicate the current post Example: /** * Amend comma-separated peer categories listing with a special string. * * @param string $thelist The peer categories list. * @param string $separator Optional. String to use as the separator. * @return string */ function c2c_peer_categories_list( $thelist, $separator ) { // If not categorized, do nothing if ( __( 'Uncategorized' ) == $thelist ) { return $thelist; } // Add a message after a comma separated listing. if ( ',' == $separator ) { $thelist .= " (* not all assigned categories are being listed)"; } return $thelist; } add_filter( 'c2c_peer_categories_list', 'customize_c2c_peer_categories_list' ); c2c_get_peer_categories_omit_ancestors (filter) The ‘c2c_get_peer_categories_omit_ancestors’ filter allows you to customize or override the function argument indicating if ancestor categories of all directly assigned categories (even if directly assigned themselves) should be omitted from the return list of categories. By default, this argument is true. Arguments: bool $omit_ancestors : the $omit_categories argument sent to the function, otherwise implicitly assumed to be the default Example: // Don't omit ancestors unless they are the immediate parent of an assigned category add_filter( 'c2c_get_peer_categories_omit_ancestors', '__return_false' );