Parentless Categories

Descripción

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_parentless_categories() lists those categories, except for categories that are parents to other assigned categories.

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», «Cucumber», and «Pumpkin» to a post, c2c_parentless_categories() would return a list that consists of: «Cucumber», and «Pumpkin». Notice that since «Fruiting» was a parent to a directly assigned category, it is not included in the list.

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 categories: <?php c2c_parentless_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_parentless_categories(); ?>

Outputs something like:

<ul><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_parentless_categories( ',' ); ?></ul>

Outputs something like:

<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 | GitHub | Author Homepage

Etiquetas de la plantilla

The plugin provides three optional template tags for use in your theme templates.

Functions

  • <?php function c2c_parentless_categories( $separator = '', $post_id = false ) ?>
    Outputs the parentless categories.

  • <?php function c2c_get_parentless_categories_list( $separator = '', $post_id = false ) ?>
    Gets the list of parentless categories.

  • <?php function c2c_get_parentless_categories( $post_id = false, $omit_ancestors = true ) ?>
    Returns the list of parentless categories for the specified post.

Argumentos

  • $separator
    Optional argument. (string) String to use as the separator. Default is », which indicates unordered list markup should be used.

  • $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’.

Ejemplos

  • (See Description section)

Hooks

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_parentless_categories (action), c2c_get_parentless_categories_list, c2c_get_parentless_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)

Ejemplo:

Instead of:

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

Do:

<?php do_action( 'c2c_parentless_categories', ',' ); ?>

c2c_parentless_categories_list (filter)

The ‘c2c_parentless_categories_list’ filter allows you to customize or override the return value of the c2c_parentless_categories_list() function.

Arguments:

  • string $thelist : the HTML-formatted list of categories, or __( 'Uncategorized' ) if the post didn’t have any categories, or an empty string if the post’s post type doesn’t support 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

Ejemplo:

/**
 * Amend comma-separated parentless categories listing with a special string.
 *
 * @param  string $thelist The parentless categories list.
 * @param  string $separator Optional. String to use as the separator.
 * @return string
 */
function c2c_parentless_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_parentless_categories_list', 'customize_c2c_parentless_categories_list' );

c2c_get_parentless_categories_omit_ancestors (filter)

The ‘c2c_get_parentless_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

Ejemplo:

// Don't omit ancestors unless they are the immediate parent of an assigned category
add_filter( 'c2c_get_parentless_categories_omit_ancestors', '__return_false' );

Instalación

  1. Install via the built-in WordPress plugin installer. Or download and unzip parentless-categories.zip inside the plugins directory for your site (typically wp-content/plugins/)
  2. Activate the plugin through the ‘Plugins’ admin menu in WordPress
  3. Optional: Add filters for ‘c2c_parentless_categories_list’ to filter parentless category listing
  4. Use the template tag <?php c2c_parentless_categories(); ?> in a theme template somewhere inside «the loop»

FAQ

Why isn’t an assigned category for the post showing up in the `c2c_parentless_categories()` listing?

If an assigned category is the parent for one or more other assigned categories for the post, then the category parent is not included in the listing.

Does this plugin include unit tests?

Yes.

Colaboradores y desarrolladores

«Parentless Categories» es un software de código abierto. Las siguientes personas han colaborado con este plugin.

Colaboradores

Traduce «Parentless Categories» a tu idioma.

¿Interesado en el desarrollo?

Revisa el código , echa un vistazo al repositorio SVN o suscríbete al registro de desarrollo por RSS.

Registro de cambios

2.1.2 (2019-11-23)

  • Change: Note compatibility through WP 5.3+
  • Change: Update copyright date (2020)

2.1.1 (2019-06-23)

  • Change: Update unit test install script and bootstrap to use latest WP unit test repo
  • Change: Note compatibility through WP 5.2+
  • Change: Make minor code formatting tweaks
  • Change: Update readme.txt documentation for c2c_parentless_categories_list hook to reflect potential for first argument to be empty string

2.1 (2019-03-24)

  • New: Check that the post’s post type supports categories before attempting to list any (and if it doesn’t, apply c2c_parentless_categories_list filter against empty string)
  • New: Add CHANGELOG.md file and move all but most recent changelog entries into it
  • New: Add inline documentation for hooks
  • Change: Use apply_filters_deprecated() to formally deprecate the ‘parentless_categories’ filter
  • Change: Specify plugin’s textdomain to translation calls for strings
  • Change: Cast return value of c2c_get_parentless_categories_omit_ancestors filter as boolean
  • Change: Use sprintf() to produce markup rather than concatenating various strings, function calls, and variables
  • Change: Minor refactor to reduce duplication of code
  • Change: Split paragraph in README.md’s «Support» section into two
  • Change: Note compatibility through WP 5.1+
  • Change: Drop compatibility with versions of WP older than 4.6
  • Change: Update copyright date (2019)
  • Change: Update License URI to be HTTPS

Full changelog is available in CHANGELOG.md.