WordPress at a glance

wp_list_categories() WP 1.0

Display or retrieve the HTML list of categories.

  • 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.
Hooks from function:
Return

false/String. HTML content only if 'echo' argument is 0.

Usage

wp_list_categories( $args );
$args(string/array)

Array of optional arguments.

  • $child_of (int)
    Term ID to retrieve child terms of. See get_terms().

  • $current_category (int/array)
    ID of category, or array of IDs of categories, that should get the 'current-cat' class.

  • $depth (int)
    Category depth. Used for tab indentation.

  • $echo (true/false/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; $exclude_tree. See get_terms().
    Default: empty string

  • $exclude_tree (array/string)
    Array or comma/space-separated string of term IDs to exclude, along with their descendants. See get_terms().
    Default: empty string

  • $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.
    Default: empty string

  • $feed_type (string)
    Feed type. Used to build feed link. See get_term_feed_link().
    Default: empty string (default feed)

  • $hide_empty (true/false/int)
    Whether to hide categories that don't have any posts attached to them.
    Default: 1

  • $hide_title_if_empty (true/false)
    Whether to hide the $title_li element if there are no terms in the list.
    Default: false (title will always be shown)

  • $hierarchical (true/false)
    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 (true/false/int)
    Whether to show how many posts are in the category.

  • $show_option_all (string)
    Text to display for showing all categories.
    Default: empty string

  • $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 (true/false/int)
    Whether to use the category description as the title attribute.
    Default: 1

Default: ''

Code of wp_list_categories: wp-includes/category-template.php VER 4.9.8

<?php
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,
	);

	$r = wp_parse_args( $args, $defaults );

	if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] )
		$r['pad_counts'] = true;

	// Descendants of exclusions should be excluded too.
	if ( true == $r['hierarchical'] ) {
		$exclude_tree = array();

		if ( $r['exclude_tree'] ) {
			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude_tree'] ) );
		}

		if ( $r['exclude'] ) {
			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude'] ) );
		}

		$r['exclude_tree'] = $exclude_tree;
		$r['exclude'] = '';
	}

	if ( ! isset( $r['class'] ) )
		$r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];

	if ( ! taxonomy_exists( $r['taxonomy'] ) ) {
		return false;
	}

	$show_option_all = $r['show_option_all'];
	$show_option_none = $r['show_option_none'];

	$categories = get_categories( $r );

	$output = '';
	if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) {
		$output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>';
	}
	if ( empty( $categories ) ) {
		if ( ! empty( $show_option_none ) ) {
			if ( 'list' == $r['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( $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 );

					// 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' == $r['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( $r['current_category'] ) && ( 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();
			}
		}

		if ( $r['hierarchical'] ) {
			$depth = $r['depth'];
		} else {
			$depth = -1; // Flat.
		}
		$output .= walk_category_tree( $categories, $depth, $r );
	}

	if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['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 ( $r['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

Related Functions

From tag: List (wp_list)

More from category: Categories

More from Template Tags: Taxonomies (category, tag)

No comments
    Hello, !     Log In . Register