Summery Summery
Display or retrieve the HTML list of categories.
Syntax Syntax
Parameters Parameters
- $args
-
(Optional) Array of optional arguments.
- 'child_of'
(int) Term ID to retrieve child terms of. See get_terms(). Default 0. - '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) True to echo markup, false to return it. 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_empty'
(bool|int) Whether to hide categories that don't have any posts attached to them. Default 1. - '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). - 'hierarchical'
(bool) Whether to include terms that have non-empty descendants. See get_terms(). Default true. - 'order'
(string) Which direction to order categories. Accepts 'ASC' or 'DESC'. Default 'ASC'. - 'orderby'
(string) The column to use for ordering categories. Default 'name'. - 'separator'
(string) Separator between links. Default<br />
. - 'show_count'
(bool|int) Whether to show how many posts are in the category. 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'. - 'taxonomy'
(string) Taxonomy name. Default 'category'. - '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. Default 1.
Default value: ''
- 'child_of'
Return Return
(false|string) HTML content only if 'echo' argument is 0.
Source Source
File: wp-includes/category-template.php
* categories will be output separated by `<br>` tags. Default 'list'. * @type string $title_li Text to use for the list title `<li>` element. Pass an empty string * to disable. Default 'Categories'. * @type bool|int $use_desc_for_title Whether to use the category description as the title attribute. * Accepts 0, 1, or their bool equivalents. Default 1. * } * @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. */ 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>'; } /**
Advertisement
Changelog Changelog
Version | Description |
---|---|
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. |
2.1.0 | Introduced. |