Parameters Parameters
- $args
-
(array|string) (Optional) Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct() for information on additional accepted arguments.
- ‘current_category’
(int|array) ID of category, or array of IDs of categories, that should get the ‘current-cat’ class. Default 0. - ‘depth’
(int) Category depth. Used for tab indentation. Default 0. - ‘echo’
(bool|int) Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1. - ‘exclude’
(array|string) 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 get_terms(). - ‘exclude_tree’
(array|string) Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms(). - ‘feed’
(string) Text to use for the feed link. Default ‘Feed for all posts filed under [cat name]’. - ‘feed_image’
(string) URL of an image to use for the feed link. - ‘feed_type’
(string) Feed type. Used to build feed link. See get_term_feed_link(). Default empty string (default feed). - ‘hide_title_if_empty’
(bool) Whether to hide the$title_li
element if there are no terms in the list. Default false (title will always be shown). - ‘separator’
(string) Separator between links. Default<br />
. - ‘show_count’
(bool|int) Whether to include post counts. Accepts 0, 1, or their bool equivalents. Default 0. - ‘show_option_all’
(string) Text to display for showing all categories. - ‘show_option_none’
(string) Text to display for the ‘no categories’ option. Default ‘No categories’. - ‘style’
(string) The style used to display the categories list. If ‘list’, categories will be output as an unordered list. If left empty or another value, categories will be output separated by<br>
tags. Default ‘list’. - ‘title_li’
(string) Text to use for the list title<li>
element. Pass an empty string to disable. Default ‘Categories’. - ‘use_desc_for_title’
(bool|int) Whether to use the category description as the title attribute. Accepts 0, 1, or their bool equivalents. Default 1.
Default value: ”
- ‘current_category’
Return Return
(void|string|false) Void if ‘echo’ argument is true, HTML list of categories if ‘echo’ is false. False if the taxonomy does not exist.
More Information More Information
If you need a function that does not format the results, try get_categories().
Usage Usage
By default, wp_list_categories() displays:
- No link to all categories
- Sorts the list of Categories by the Category name in ascending order
- Displayed in an unordered list style
- Does not show the post count
- Displays only Categories with posts
- Sets the title attribute to the Category Description
- Is not restricted to the child_of any Category
- No feed or feed image used
- Does not exclude any Category and includes all Categories
- Displays the active Category with the CSS Class-Suffix ‘ current-cat’
- Shows the Categories in hierarchical indented fashion
- Display Category as the heading over the list
- No SQL LIMIT is imposed (‘number’ => 0 is not shown above)
- Displays (echos) the categories
- No limit to depth
- All categories.
- The list is rendered using a new walker object of the the Walker_Category class
Source Source
File: wp-includes/category-template.php
523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 |
function wp_list_categories( $args = '' ) { $defaults = array ( 'child_of' => 0, 'current_category' => 0, 'depth' => 0, 'echo' => 1, 'exclude' => '' , 'exclude_tree' => '' , 'feed' => '' , 'feed_image' => '' , 'feed_type' => '' , 'hide_empty' => 1, 'hide_title_if_empty' => false, 'hierarchical' => true, 'order' => 'ASC' , 'orderby' => 'name' , 'separator' => '<br />' , 'show_count' => 0, 'show_option_all' => '' , 'show_option_none' => __( 'No categories' ), 'style' => 'list' , 'taxonomy' => 'category' , 'title_li' => __( 'Categories' ), 'use_desc_for_title' => 1, ); $parsed_args = wp_parse_args( $args , $defaults ); if ( ! isset( $parsed_args [ 'pad_counts' ] ) && $parsed_args [ 'show_count' ] && $parsed_args [ 'hierarchical' ] ) { $parsed_args [ 'pad_counts' ] = true; } // Descendants of exclusions should be excluded too. if ( true == $parsed_args [ 'hierarchical' ] ) { $exclude_tree = array (); if ( $parsed_args [ 'exclude_tree' ] ) { $exclude_tree = array_merge ( $exclude_tree , wp_parse_id_list( $parsed_args [ 'exclude_tree' ] ) ); } if ( $parsed_args [ 'exclude' ] ) { $exclude_tree = array_merge ( $exclude_tree , wp_parse_id_list( $parsed_args [ 'exclude' ] ) ); } $parsed_args [ 'exclude_tree' ] = $exclude_tree ; $parsed_args [ 'exclude' ] = '' ; } if ( ! isset( $parsed_args [ 'class' ] ) ) { $parsed_args [ 'class' ] = ( 'category' === $parsed_args [ 'taxonomy' ] ) ? 'categories' : $parsed_args [ 'taxonomy' ]; } if ( ! taxonomy_exists( $parsed_args [ 'taxonomy' ] ) ) { return false; } $show_option_all = $parsed_args [ 'show_option_all' ]; $show_option_none = $parsed_args [ 'show_option_none' ]; $categories = get_categories( $parsed_args ); $output = '' ; if ( $parsed_args [ 'title_li' ] && 'list' === $parsed_args [ 'style' ] && ( ! empty ( $categories ) || ! $parsed_args [ 'hide_title_if_empty' ] ) ) { $output = '<li class="' . esc_attr( $parsed_args [ 'class' ] ) . '">' . $parsed_args [ 'title_li' ] . '<ul>' ; } if ( empty ( $categories ) ) { if ( ! empty ( $show_option_none ) ) { if ( 'list' === $parsed_args [ 'style' ] ) { $output .= '<li class="cat-item-none">' . $show_option_none . '</li>' ; } else { $output .= $show_option_none ; } } } else { if ( ! empty ( $show_option_all ) ) { $posts_page = '' ; // For taxonomies that belong only to custom post types, point to a valid archive. $taxonomy_object = get_taxonomy( $parsed_args [ 'taxonomy' ] ); if ( ! in_array( 'post' , $taxonomy_object ->object_type, true ) && ! in_array( 'page' , $taxonomy_object ->object_type, true ) ) { foreach ( $taxonomy_object ->object_type as $object_type ) { $_object_type = get_post_type_object( $object_type ); // Grab the first one. if ( ! empty ( $_object_type ->has_archive ) ) { $posts_page = get_post_type_archive_link( $object_type ); break ; } } } // Fallback for the 'All' link is the posts page. if ( ! $posts_page ) { if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) { $posts_page = get_permalink( get_option( 'page_for_posts' ) ); } else { $posts_page = home_url( '/' ); } } $posts_page = esc_url( $posts_page ); if ( 'list' === $parsed_args [ 'style' ] ) { $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>" ; } else { $output .= "<a href='$posts_page'>$show_option_all</a>" ; } } if ( empty ( $parsed_args [ 'current_category' ] ) && ( is_category() || is_tax() || is_tag() ) ) { $current_term_object = get_queried_object(); if ( $current_term_object && $parsed_args [ 'taxonomy' ] === $current_term_object ->taxonomy ) { $parsed_args [ 'current_category' ] = get_queried_object_id(); } } if ( $parsed_args [ 'hierarchical' ] ) { $depth = $parsed_args [ 'depth' ]; } else { $depth = -1; // Flat. } $output .= walk_category_tree( $categories , $depth , $parsed_args ); } if ( $parsed_args [ 'title_li' ] && 'list' === $parsed_args [ 'style' ] && ( ! empty ( $categories ) || ! $parsed_args [ 'hide_title_if_empty' ] ) ) { $output .= '</ul></li>' ; } /** * Filters the HTML output of a taxonomy 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 ( $parsed_args [ 'echo' ] ) { echo $html ; } else { return $html ; } } |
Changelog Changelog
Version | Description |
---|---|
4.4.0 | The current_category argument was modified to optionally accept an array of values. |
2.1.0 | Introduced. |