Ticket #19780: 19780.4.diff

src/wp-includes/category-template.php

@@ -477 +477 @@
 }
 
 /**
- * Display or retrieve the HTML list of categories.
+ * Displays or retrieves an HTML list of categories.
  *
  * @since 2.1.0
- * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category` argument was modified to
- *              optionally accept an array of values.
+ * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category`
+ *              argument was modified to optionally accept an array of values.
+ * @since 4.6.0 Deprecated the 'current_category' argument in favor of 'current_term'. Was converted
+ *              to a wrapper function for wp_list_terms().
  *
+ * @see wp_list_terms()
+ *
  * @param string|array $args {
- *     Array of optional arguments.
+ *     Array of arguments to retrieve or display an HTML list of categories.
+ *     See wp_list_terms() for more arguments.
  *
- *     @type string       $show_option_all       Text to display for showing all categories. Default empty string.
- *     @type string       $show_option_none      Text to display for the 'no categories' option.
- *                                               Default 'No categories'.
- *     @type string       $orderby               The column to use for ordering categories. Default 'ID'.
- *     @type string       $order                 Which direction to order categories. Accepts 'ASC' or 'DESC'.
- *                                               Default 'ASC'.
- *     @type bool|int     $show_count            Whether to show how many posts are in the category. Default 0.
- *     @type bool|int     $hide_empty            Whether to hide categories that don't have any posts attached to them.
- *                                               Default 1.
- *     @type bool|int     $use_desc_for_title    Whether to use the category description as the title attribute.
- *                                               Default 1.
- *     @type string       $feed                  Text to use for the feed link. Default 'Feed for all posts filed
- *                                               under [cat name]'.
- *     @type string       $feed_type             Feed type. Used to build feed link. See {@link get_term_feed_link()}.
- *                                               Default empty string (default feed).
- *     @type string       $feed_image            URL of an image to use for the feed link. Default empty string.
- *     @type int          $child_of              Term ID to retrieve child terms of. See {@link get_terms()}. Default 0.
- *     @type array|string $exclude               Array or comma/space-separated string of term IDs to exclude.
- *                                               If `$hierarchical` is true, descendants of `$exclude` terms will also
- *                                               be excluded; see `$exclude_tree`. See {@link get_terms()}.
- *                                               Default empty string.
- *     @type array|string $exclude_tree          Array or comma/space-separated string of term IDs to exclude, along
- *                                               with their descendants. See {@link get_terms()}. Default empty string.
- *     @type bool|int     $echo                  True to echo markup, false to return it. Default 1.
- *     @type int|array    $current_category      ID of category, or array of IDs of categories, that should get the
- *                                               'current-cat' class. Default 0.
- *     @type bool         $hierarchical          Whether to include terms that have non-empty descendants.
- *                                               See {@link get_terms()}. Default true.
- *     @type string       $title_li              Text to use for the list title `<li>` element. Pass an empty string
- *                                               to disable. Default 'Categories'.
- *     @type bool         $hide_title_if_empty   Whether to hide the `$title_li` element if there are no terms in
- *                                               the list. Default false (title will always be shown).
- *     @type int          $depth                 Category depth. Used for tab indentation. Default 0.
- *     @type string       $taxonomy              Taxonomy name. Default 'category'.
- *     @type string       $separator             Separator between links. Default '<br />'.
+ *     @type string $taxonomy Taxonomy. Default 'category'.
  * }
- * @return false|string HTML content only if 'echo' argument is 0.
+ * @return false|string HTML content only if `echo' argument is 0|false.
  */
 function wp_list_categories( $args = '' ) {
+        $r = wp_parse_args( $args, array( 'taxonomy' => 'category' ) );
+
+        $original_echo_value = $r['echo'];
+
+        // Force to false to allow for passing through back-compat filters.
+        $r['echo'] = false;
+
+        // Back-compat for old 'current_category' argument.
+        if ( ! empty ( $r['current_category'] ) ) {
+                $r['current_term'] = $r['current_category'];
+        }
+
+        $output = wp_list_terms( $r );
+
+        /**
+         * Filter the HTML output of a categories list.
+         *
+         * @since 2.1.0
+         *
+         * @param string $output HTML output.
+         * @param array  $args   An array of taxonomy-listing arguments.
+         */
+        $html = apply_filters( 'wp_list_categories', $output, $args );
+
+        if ( $original_echo_value ) {
+                echo $html;
+        } else {
+                return $html;
+        }
+}
+
+/**
+ * Displays or retrieves an HTML list of terms.
+ *
+ * @since 4.6.0
+ *
+ * @see get_terms()
+ *
+ * @param string|array $args {
+ *     Array of arguments to retrieve or display an HTML list of terms.
+ *
+ *     @type int          $child_of            Term ID to retrieve child terms of. Default 0.
+ *     @type int|array    $current_term        Term ID, or array of term IDs that should get the 'current-term' class.
+ *                                             Default 0.
+ *     @type int          $depth               Category depth. Used for tab indentation. Default 0.
+ *     @type bool|int     $echo                True to echo markup, false to return it. Default 1|true.
+ *     @type array|string $exclude             Array or comma/space-separated string of term IDs to exclude.
+ *                                             If `$hierarchical` is true, descendants of `$exclude` terms will also
+ *                                             be excluded; see `$exclude_tree`. Default empty string.
+ *     @type array|string $exclude_tree        Array or comma/space-separated string of term IDs to exclude, along
+ *                                             with their descendants. Default empty string.
+ *     @type string       $feed                Text to use for the feed link. Default 'Feed for all posts filed
+ *                                             under [term name]'.
+ *     @type string       $feed_image          URL of an image to use for the feed link. Default empty string.
+ *     @type string       $feed_type           Feed type. Used to build feed link. See get_term_feed_link().
+ *                                             Default empty string (default feed).
+ *     @type bool|int     $hide_empty          Whether to hide terms that don't have any posts attached to them.
+ *                                             Default 1|true.
+ *     @type bool         $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in
+ *                                             the list. Default false (title will always be shown).
+ *     @type bool         $hierarchical        Whether to include terms that have non-empty descendants.
+ *                                             Default true.
+ *     @type string       $order               Which direction to order terms. Accepts 'ASC' or 'DESC'. Default 'ASC'.
+ *     @type string       $orderby             The column to use for ordering terms. Default 'ID'.
+ *     @type string       $separator           Separator between links. Default '<br />'.
+ *     @type bool|int     $show_count          Whether to show how many posts are in the term. Default 0|false.
+ *     @type string       $show_option_all     Text to display for showing all terms. Default empty string.
+ *     @type string       $show_option_none    Text to display for the 'no terms' option. Default is the value
+ *                                             of the 'no_terms' taxonomy label.
+ *     @type string       $taxonomy            Taxonomy name. Default null (required).
+ *     @type string       $title_li            Text to use for the list title `<li>` element. Pass an empty string
+ *                                             to disable. Default is the value of the 'name' label for `$taxonomy`.
+ *     @type bool|int     $use_desc_for_title  Whether to use the term description as the title attribute.
+ *                                             Default 1|true.
+ * }
+ * @return false|string HTML content only if 'echo' argument is 0|false. False if the taxonomy doesn't exist.
+ */
+function wp_list_terms( $args = array() ) {
         $defaults = array(
                 'child_of'            => 0,
                 'current_category'    => 0,
@@ -543 +592 @@
                 'separator'           => '<br />',
                 'show_count'          => 0,
                 'show_option_all'     => '',
-                'show_option_none'    => __( 'No categories' ),
+                'show_option_none'    => '',
                 'style'               => 'list',
-                'taxonomy'            => 'category',
-                'title_li'            => __( 'Categories' ),
+                'taxonomy'            => null,
+                'title_li'            => '',
                 'use_desc_for_title'  => 1,
         );
 
         $r = wp_parse_args( $args, $defaults );
 
-        if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] )
+        // Bail if the taxonomy is invalid.
+        if ( ! $taxonomy_object = get_taxonomy( $r['taxonomy'] ) ) {
+                return false;
+        }
+
+        if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
                 $r['pad_counts'] = true;
+        }
 
+        // Default to the 'name' taxonomy label.
+        if ( empty( $r['title_li'] ) ) {
+                $r['title_li'] = $taxonomy_object->labels->name;
+        }
+
         // Descendants of exclusions should be excluded too.
         if ( true == $r['hierarchical'] ) {
                 $exclude_tree = array();
@@ -571 +631 @@
                 $r['exclude'] = '';
         }
 
-        if ( ! isset( $r['class'] ) )
-                $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];
-
-        if ( ! taxonomy_exists( $r['taxonomy'] ) ) {
-                return false;
+        if ( ! isset( $r['class'] ) ) {
+                // Back-compat for categories.
+                $r['class'] = ( 'category' === $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];
         }
 
         $show_option_all = $r['show_option_all'];
-        $show_option_none = $r['show_option_none'];
 
-        $categories = get_categories( $r );
+        // Default to the 'no_terms' taxonomy label.
+        if ( empty( $r['show_option_none'] ) ) {
+                $show_option_none = $taxonomy_object->labels->no_terms;
+        } else {
+                $show_option_none = $r['show_option_none'];
+        }
 
+        $terms = get_categories( $r );
+
         $output = '';
-        if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) {
+        if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $terms ) || ! $r['hide_title_if_empty'] ) ) {
                 $output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>';
         }
-        if ( empty( $categories ) ) {
+        if ( empty( $terms ) ) {
                 if ( ! empty( $show_option_none ) ) {
                         if ( 'list' == $r['style'] ) {
                                 $output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
@@ -601 +665 @@
                         $posts_page = '';
 
                         // For taxonomies that belong only to custom post types, point to a valid archive.
-                        $taxonomy_object = get_taxonomy( $r['taxonomy'] );
                         if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) {
                                 foreach ( $taxonomy_object->object_type as $object_type ) {
                                         $_object_type = get_post_type_object( $object_type );
@@ -631 +694 @@
                         }
                 }
 
-                if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
+                if ( empty( $r['current_term'] ) && ( is_category() || is_tax() || is_tag() ) ) {
                         $current_term_object = get_queried_object();
                         if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) {
-                                $r['current_category'] = get_queried_object_id();
+                                $r['current_term'] = get_queried_object_id();
                         }
                 }
 
@@ -643 +706 @@
                 } else {
                         $depth = -1; // Flat.
                 }
-                $output .= walk_category_tree( $categories, $depth, $r );
+                $output .= walk_category_tree( $terms, $depth, $r );
         }
 
         if ( $r['title_li'] && 'list' == $r['style'] )
@@ -650 +713 @@
                 $output .= '</ul></li>';
 
         /**
-         * Filter the HTML output of a taxonomy list.
+         * Filter the HTML output of a terms list.
          *
-         * @since 2.1.0
+         * @since 4.6.0
          *
          * @param string $output HTML output.
-         * @param array  $args   An array of taxonomy-listing arguments.
+         * @param array  $args   An array of pre-processed taxonomy-listing arguments.
          */
-        $html = apply_filters( 'wp_list_categories', $output, $args );
+        $html = apply_filters( 'wp_list_terms', $output, $args );
 
         if ( $r['echo'] ) {
                 echo $html;