WordPress.org

Make WordPress Core

Ticket #19780: 19780.4.diff

File 19780.4.diff, 13.2 KB (added by DrewAPicture, 5 years ago)

wp_list_terms()

  • src/wp-includes/category-template.php

     
    477477}
    478478
    479479/**
    480  * Display or retrieve the HTML list of categories.
     480 * Displays or retrieves an HTML list of categories.
    481481 *
    482482 * @since 2.1.0
    483  * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category` argument was modified to
    484  *              optionally accept an array of values.
     483 * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category`
     484 *              argument was modified to optionally accept an array of values.
     485 * @since 4.6.0 Deprecated the 'current_category' argument in favor of 'current_term'. Was converted
     486 *              to a wrapper function for wp_list_terms().
    485487 *
     488 * @see wp_list_terms()
     489 *
    486490 * @param string|array $args {
    487  *     Array of optional arguments.
     491 *     Array of arguments to retrieve or display an HTML list of categories.
     492 *     See wp_list_terms() for more arguments.
    488493 *
    489  *     @type string       $show_option_all       Text to display for showing all categories. Default empty string.
    490  *     @type string       $show_option_none      Text to display for the 'no categories' option.
    491  *                                               Default 'No categories'.
    492  *     @type string       $orderby               The column to use for ordering categories. Default 'ID'.
    493  *     @type string       $order                 Which direction to order categories. Accepts 'ASC' or 'DESC'.
    494  *                                               Default 'ASC'.
    495  *     @type bool|int     $show_count            Whether to show how many posts are in the category. Default 0.
    496  *     @type bool|int     $hide_empty            Whether to hide categories that don't have any posts attached to them.
    497  *                                               Default 1.
    498  *     @type bool|int     $use_desc_for_title    Whether to use the category description as the title attribute.
    499  *                                               Default 1.
    500  *     @type string       $feed                  Text to use for the feed link. Default 'Feed for all posts filed
    501  *                                               under [cat name]'.
    502  *     @type string       $feed_type             Feed type. Used to build feed link. See {@link get_term_feed_link()}.
    503  *                                               Default empty string (default feed).
    504  *     @type string       $feed_image            URL of an image to use for the feed link. Default empty string.
    505  *     @type int          $child_of              Term ID to retrieve child terms of. See {@link get_terms()}. Default 0.
    506  *     @type array|string $exclude               Array or comma/space-separated string of term IDs to exclude.
    507  *                                               If `$hierarchical` is true, descendants of `$exclude` terms will also
    508  *                                               be excluded; see `$exclude_tree`. See {@link get_terms()}.
    509  *                                               Default empty string.
    510  *     @type array|string $exclude_tree          Array or comma/space-separated string of term IDs to exclude, along
    511  *                                               with their descendants. See {@link get_terms()}. Default empty string.
    512  *     @type bool|int     $echo                  True to echo markup, false to return it. Default 1.
    513  *     @type int|array    $current_category      ID of category, or array of IDs of categories, that should get the
    514  *                                               'current-cat' class. Default 0.
    515  *     @type bool         $hierarchical          Whether to include terms that have non-empty descendants.
    516  *                                               See {@link get_terms()}. Default true.
    517  *     @type string       $title_li              Text to use for the list title `<li>` element. Pass an empty string
    518  *                                               to disable. Default 'Categories'.
    519  *     @type bool         $hide_title_if_empty   Whether to hide the `$title_li` element if there are no terms in
    520  *                                               the list. Default false (title will always be shown).
    521  *     @type int          $depth                 Category depth. Used for tab indentation. Default 0.
    522  *     @type string       $taxonomy              Taxonomy name. Default 'category'.
    523  *     @type string       $separator             Separator between links. Default '<br />'.
     494 *     @type string $taxonomy Taxonomy. Default 'category'.
    524495 * }
    525  * @return false|string HTML content only if 'echo' argument is 0.
     496 * @return false|string HTML content only if `echo' argument is 0|false.
    526497 */
    527498function wp_list_categories( $args = '' ) {
     499        $r = wp_parse_args( $args, array( 'taxonomy' => 'category' ) );
     500
     501        $original_echo_value = $r['echo'];
     502
     503        // Force to false to allow for passing through back-compat filters.
     504        $r['echo'] = false;
     505
     506        // Back-compat for old 'current_category' argument.
     507        if ( ! empty ( $r['current_category'] ) ) {
     508                $r['current_term'] = $r['current_category'];
     509        }
     510
     511        $output = wp_list_terms( $r );
     512
     513        /**
     514         * Filter the HTML output of a categories list.
     515         *
     516         * @since 2.1.0
     517         *
     518         * @param string $output HTML output.
     519         * @param array  $args   An array of taxonomy-listing arguments.
     520         */
     521        $html = apply_filters( 'wp_list_categories', $output, $args );
     522
     523        if ( $original_echo_value ) {
     524                echo $html;
     525        } else {
     526                return $html;
     527        }
     528}
     529
     530/**
     531 * Displays or retrieves an HTML list of terms.
     532 *
     533 * @since 4.6.0
     534 *
     535 * @see get_terms()
     536 *
     537 * @param string|array $args {
     538 *     Array of arguments to retrieve or display an HTML list of terms.
     539 *
     540 *     @type int          $child_of            Term ID to retrieve child terms of. Default 0.
     541 *     @type int|array    $current_term        Term ID, or array of term IDs that should get the 'current-term' class.
     542 *                                             Default 0.
     543 *     @type int          $depth               Category depth. Used for tab indentation. Default 0.
     544 *     @type bool|int     $echo                True to echo markup, false to return it. Default 1|true.
     545 *     @type array|string $exclude             Array or comma/space-separated string of term IDs to exclude.
     546 *                                             If `$hierarchical` is true, descendants of `$exclude` terms will also
     547 *                                             be excluded; see `$exclude_tree`. Default empty string.
     548 *     @type array|string $exclude_tree        Array or comma/space-separated string of term IDs to exclude, along
     549 *                                             with their descendants. Default empty string.
     550 *     @type string       $feed                Text to use for the feed link. Default 'Feed for all posts filed
     551 *                                             under [term name]'.
     552 *     @type string       $feed_image          URL of an image to use for the feed link. Default empty string.
     553 *     @type string       $feed_type           Feed type. Used to build feed link. See get_term_feed_link().
     554 *                                             Default empty string (default feed).
     555 *     @type bool|int     $hide_empty          Whether to hide terms that don't have any posts attached to them.
     556 *                                             Default 1|true.
     557 *     @type bool         $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in
     558 *                                             the list. Default false (title will always be shown).
     559 *     @type bool         $hierarchical        Whether to include terms that have non-empty descendants.
     560 *                                             Default true.
     561 *     @type string       $order               Which direction to order terms. Accepts 'ASC' or 'DESC'. Default 'ASC'.
     562 *     @type string       $orderby             The column to use for ordering terms. Default 'ID'.
     563 *     @type string       $separator           Separator between links. Default '<br />'.
     564 *     @type bool|int     $show_count          Whether to show how many posts are in the term. Default 0|false.
     565 *     @type string       $show_option_all     Text to display for showing all terms. Default empty string.
     566 *     @type string       $show_option_none    Text to display for the 'no terms' option. Default is the value
     567 *                                             of the 'no_terms' taxonomy label.
     568 *     @type string       $taxonomy            Taxonomy name. Default null (required).
     569 *     @type string       $title_li            Text to use for the list title `<li>` element. Pass an empty string
     570 *                                             to disable. Default is the value of the 'name' label for `$taxonomy`.
     571 *     @type bool|int     $use_desc_for_title  Whether to use the term description as the title attribute.
     572 *                                             Default 1|true.
     573 * }
     574 * @return false|string HTML content only if 'echo' argument is 0|false. False if the taxonomy doesn't exist.
     575 */
     576function wp_list_terms( $args = array() ) {
    528577        $defaults = array(
    529578                'child_of'            => 0,
    530579                'current_category'    => 0,
     
    543592                'separator'           => '<br />',
    544593                'show_count'          => 0,
    545594                'show_option_all'     => '',
    546                 'show_option_none'    => __( 'No categories' ),
     595                'show_option_none'    => '',
    547596                'style'               => 'list',
    548                 'taxonomy'            => 'category',
    549                 'title_li'            => __( 'Categories' ),
     597                'taxonomy'            => null,
     598                'title_li'            => '',
    550599                'use_desc_for_title'  => 1,
    551600        );
    552601
    553602        $r = wp_parse_args( $args, $defaults );
    554603
    555         if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] )
     604        // Bail if the taxonomy is invalid.
     605        if ( ! $taxonomy_object = get_taxonomy( $r['taxonomy'] ) ) {
     606                return false;
     607        }
     608
     609        if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
    556610                $r['pad_counts'] = true;
     611        }
    557612
     613        // Default to the 'name' taxonomy label.
     614        if ( empty( $r['title_li'] ) ) {
     615                $r['title_li'] = $taxonomy_object->labels->name;
     616        }
     617
    558618        // Descendants of exclusions should be excluded too.
    559619        if ( true == $r['hierarchical'] ) {
    560620                $exclude_tree = array();
     
    571631                $r['exclude'] = '';
    572632        }
    573633
    574         if ( ! isset( $r['class'] ) )
    575                 $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];
    576 
    577         if ( ! taxonomy_exists( $r['taxonomy'] ) ) {
    578                 return false;
     634        if ( ! isset( $r['class'] ) ) {
     635                // Back-compat for categories.
     636                $r['class'] = ( 'category' === $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];
    579637        }
    580638
    581639        $show_option_all = $r['show_option_all'];
    582         $show_option_none = $r['show_option_none'];
    583640
    584         $categories = get_categories( $r );
     641        // Default to the 'no_terms' taxonomy label.
     642        if ( empty( $r['show_option_none'] ) ) {
     643                $show_option_none = $taxonomy_object->labels->no_terms;
     644        } else {
     645                $show_option_none = $r['show_option_none'];
     646        }
    585647
     648        $terms = get_categories( $r );
     649
    586650        $output = '';
    587         if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) {
     651        if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $terms ) || ! $r['hide_title_if_empty'] ) ) {
    588652                $output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>';
    589653        }
    590         if ( empty( $categories ) ) {
     654        if ( empty( $terms ) ) {
    591655                if ( ! empty( $show_option_none ) ) {
    592656                        if ( 'list' == $r['style'] ) {
    593657                                $output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
     
    601665                        $posts_page = '';
    602666
    603667                        // For taxonomies that belong only to custom post types, point to a valid archive.
    604                         $taxonomy_object = get_taxonomy( $r['taxonomy'] );
    605668                        if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) {
    606669                                foreach ( $taxonomy_object->object_type as $object_type ) {
    607670                                        $_object_type = get_post_type_object( $object_type );
     
    631694                        }
    632695                }
    633696
    634                 if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
     697                if ( empty( $r['current_term'] ) && ( is_category() || is_tax() || is_tag() ) ) {
    635698                        $current_term_object = get_queried_object();
    636699                        if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) {
    637                                 $r['current_category'] = get_queried_object_id();
     700                                $r['current_term'] = get_queried_object_id();
    638701                        }
    639702                }
    640703
     
    643706                } else {
    644707                        $depth = -1; // Flat.
    645708                }
    646                 $output .= walk_category_tree( $categories, $depth, $r );
     709                $output .= walk_category_tree( $terms, $depth, $r );
    647710        }
    648711
    649712        if ( $r['title_li'] && 'list' == $r['style'] )
     
    650713                $output .= '</ul></li>';
    651714
    652715        /**
    653          * Filter the HTML output of a taxonomy list.
     716         * Filter the HTML output of a terms list.
    654717         *
    655          * @since 2.1.0
     718         * @since 4.6.0
    656719         *
    657720         * @param string $output HTML output.
    658          * @param array  $args   An array of taxonomy-listing arguments.
     721         * @param array  $args   An array of pre-processed taxonomy-listing arguments.
    659722         */
    660         $html = apply_filters( 'wp_list_categories', $output, $args );
     723        $html = apply_filters( 'wp_list_terms', $output, $args );
    661724
    662725        if ( $r['echo'] ) {
    663726                echo $html;