3

I've created a custom taxonomy:

add_action( 'init', 'create_collection_taxonomies', 0 );
function create_collection_taxonomies() {
    $labels = array(
        'name'                       => _x( 'Collection Tags', 'taxonomy general name' ),
        'singular_name'              => _x( 'Collection Tag', 'taxonomy singular name' ),
        'search_items'               => __( 'Search Collection Tags' ),
        'popular_items'              => __( 'Popular Collection Tags' ),
        'all_items'                  => __( 'All Collection Tags' ),
        'parent_item'                => __( 'Parent Collection Tag' ),
        'parent_item_colon'          => __( 'Parent Collection Tag' ),
        'edit_item'                  => __( 'Edit Collection Tag' ),
        'update_item'                => __( 'Update Collection Tag' ),
        'add_new_item'               => __( 'Add New Collection Tag' ),
        'new_item_name'              => __( 'New Collection Tag Name' ),
        'menu_name'                  => __( 'Collections Tags' ),
    );

    $args = array(
        'description'           => 'Used to select promo/video for display in app.',
        'hierarchical'          => true,
        'labels'                => $labels,
        'show_ui'               => true,
        'show_admin_column'     => true,
        'query_var'             => true,
        'rewrite'               => array( 'slug' => 'CollectionTag' ),
    );

    register_taxonomy( 'CollectionTag', array('collection', 'videos', 'promos'), $args );
}

I added the description argument thinking it would appear in the taxonomy metabox in the WP admin; however, that doesn't seem to be the case.

I did find this post from 2011, saying I would have to use jQuery to get a description added to the box, but it seems odd we can define a description without being able to use it.

Am I misunderstanding the purpose of this argument from what I'm reading in the Codex? How do I get this description to appear within the meta box for this taxonomy?

1
  • I think this is a neat question - I'd also like to know how to add the description to the taxonomy metabox and the taxonomy edit admin page. +1
    – Howdy_McGee
    Jun 17, 2016 at 14:41

2 Answers 2

6

Looking at the files that create the metabox, there isn't anything to really hook into that will allow us to add the description so we'll need to use jQuery. Since the script is extremely small, I've opted not to put it into an external file but instead use the admin_footer hook:

/**
 * Prepend taxonomy descriptions to taxonomy metaboxes
 */
function append_taxonomy_descriptions_metabox() {
    $post_types = array( 'page' );          // Array of Accepted Post Types
    $screen     = get_current_screen();     // Get current user screen

    if( 'edit' !== $screen->parent_base ) { // IF we're not on an edit page - just return
        return;
    }

    // IF the current post type is in our array
    if( in_array( $screen->post_type, $post_types ) ) {
        $taxonomies = get_object_taxonomies( $screen->post_type, 'objects' );   // Grab all taxonomies for that post type

        // Ensure taxonomies are not empty
        if( ! empty( $taxonomies ) ) : ?>

            <script type="text/javascript">

              <?php foreach( $taxonomies as $taxonomy ) : ?>

                var tax_slug = '<?php echo $taxonomy->name; ?>';
                var tax_desc = '<?php echo $taxonomy->description; ?>';

                // Add the description via jQuery
                jQuery( '#' + tax_slug + 'div div.inside' ).prepend( '<p>' + tax_desc + '</p>' );

              <?php endforeach; ?>

            </script>

        <?php endif;
    }
}
add_action( 'admin_footer', 'append_taxonomy_descriptions_metabox' );

We have a $post_types array to test against so we don't add this to every post type or every page but only certain pages. We could do the same for taxonomies but I have not in this scenario.


BONUS MATERIAL

The below will add the description to the Admin taxonomy page ( where you add new terms ). We use a much easier hook add_action( '{$taxonomy}_pre_add_form' ):

/**
 * Prepend taxonomy description to Add New Term form
 */
function CollectionTag_admin_edit_description( $tax_slug ) {

    // Grab the Taxonomy Object
    $tax_obj = get_taxonomy( $tax_slug );

    // IF the description is set on our object
    if( property_exists( $tax_obj, 'description' ) ) {
        echo '<h2>Description</h2>';
        echo apply_filters( 'the_content', $tax_obj->description );
    }
}
add_action( 'CollectionTag_pre_add_form', 'CollectionTag_admin_edit_description' );
2
  • The first block of code works beautiful Howdy. However, I had to remove the check on the $screen->parent_base value. Even while in an Edit page, it did not return "edit" as expected and was causing the function to fail out. Once I removed that, it performed as expected.
    – Yazmin
    Jun 17, 2016 at 19:45
  • 1
    A minor tweak for newer versions of WordPress (I'm using 4.9.5) ... Replace this jQuery( '#' + tax_slug + 'div div.inside' ).prepend( '<p>' + tax_desc + '</p>' ); with this: jQuery( '#tagsdiv-' + tax_slug + ' div.inside' ).prepend( '<p>' + tax_desc + '</p>' );
    – Davey
    May 2, 2018 at 7:54
0

Dynamic versions of the accepted answers:

To add the description to each of your public taxonomies with a dynamic version of Howdy's {$taxonomy}_pre_add_form action dynamically without coding one for each of your taxonomies use the following:

/**
 * Prepend taxonomy description to Add New Term form for each taxonomy
 */
add_action('init', 'MCMLXV_add_taxonomy_decriptions');
function MCMLXV_add_taxonomy_decriptions()
{
    $args = array(
        'public'   => true,
        '_builtin' => false
    );
    $taxonomies = get_taxonomies($args, 'names', 'and');
    foreach ($taxonomies as $key => $taxonomy) {
    // Create a dynamic anonymous function foreach of our taxonomies 
    // and pass the taxonomy name variable to the anonymous function
        add_action($taxonomy . '_pre_add_form', function ($taxonomy) {
            // Grab the Taxonomy Object
            $tax_obj = get_taxonomy($taxonomy);

            // IF the description is set on our object
            if (property_exists($tax_obj, 'description')) {
                echo '<h2>Description</h2>';
                echo apply_filters('the_content', $tax_obj->description);
            }
        });
    }
}

To combine the above answers by Howdy_McGee and Davey to be dynamic based on if the taxonomy hierarchal is set to false (ie tags or custom tag taxonomies) and to make the js variables unique I used the following:

<script type="text/javascript" id="mythemehere_taxonomy_metabox_description">
    <?php foreach ($taxonomies as $taxonomy) { ?>
        <?php if ($taxonomy->hierarchical == false) { ?>

            // Unique variables per tax
            var tax_slug_<?php echo $taxonomy->name; ?> = '<?php echo $taxonomy->name; ?>';
            var tax_desc_<?php echo $taxonomy->name; ?> = '<?php echo $taxonomy->description; ?>';

            // jQuery targeting of hierarchal false taxonomies (tags)
            jQuery('#tagsdiv-' + tax_slug_<?php echo $taxonomy->name; ?> + ' div.inside').prepend('<p>' + tax_desc_<?php echo $taxonomy->description; ?> + '</p>');

        <?php } else { ?>

            // Unique variables per tax
            var tax_slug_<?php echo $taxonomy->name; ?> = '<?php echo $taxonomy->name; ?>';
            var tax_desc_<?php echo $taxonomy->name; ?> = '<?php echo $taxonomy->description; ?>';

            // jQuery targeting of hierarchal true taxonomies (categories)
            jQuery('#' + tax_slug_<?php echo $taxonomy->name; ?> + 'div div.inside').prepend('<p>' + tax_desc_<?php echo $taxonomy->name; ?> + '</p>');

        <?php } ?>
     <?php } ?>
</script>

This will output something like the following:


<script type="text/javascript" id="mythemehere_taxonomy_metabox_description">
    var tax_slug_portfolio_category = 'portfolio_category';
    var tax_desc_portfolio_category = 'this is your unique description';
    // Add the description via jQuery
    jQuery('#' + tax_slug_portfolio_category + 'div div.inside').prepend('<p>' + tax_desc_portfolio_category + '</p>');
                                                                                 
    var tax_slug_portfolio_tag = 'portfolio_tag';
    var tax_desc_portfolio_tag = 'this is your unique description';
    // Add the description via jQuery
    jQuery('#tagsdiv-' + tax_slug_portfolio_tag + ' div.inside').prepend('<p>' + tax_desc_portfolio_tag + '</p>');

All the answers above and in my code above also assumes you have set the description and hierarchal in your register_taxonomy($args). Leaving out all the unnecessary arguments for this example:

    $args = array(
        'hierarchical' => true,
        'description' => 'this is your unique description',
    );
    register_taxonomy('portfolio_category', array('portfolio'), $args);

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.