Index: src/wp-includes/category-template.php =================================================================== --- src/wp-includes/category-template.php (revision 37196) +++ src/wp-includes/category-template.php (working copy) @@ -477,54 +477,103 @@ } /** - * 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 `
  • ` 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 '
    '. + * @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 '
    '. + * @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 `
  • ` 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,18 +592,29 @@ 'separator' => '
    ', '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,23 +631,27 @@ $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 = '
  • ' . $r['title_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;