Retrieves category list for a post in either HTML list or custom format.
Description
Generally used for quick, delimited (e.g. comma-separated) lists of categories, as part of a post entry meta.
For a more powerful, list-based function, see wp_list_categories() .
See also
Parameters
$separator
stringoptional- Separator between the categories. By default, the links are placed in an unordered list. An empty string will result in the default behavior.
Default:
''
$parents
stringoptional- How to display the parents. Accepts
'multiple'
,'single'
, or empty.
Default:
''
$post_id
intoptional- ID of the post to retrieve categories for. Defaults to the current post.
Default:
false
Source
function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
global $wp_rewrite;
if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', '', $separator, $parents );
}
/**
* Filters the categories before building the category list.
*
* @since 4.4.0
*
* @param WP_Term[] $categories An array of the post's categories.
* @param int|false $post_id ID of the post to retrieve categories for.
* When `false`, defaults to the current post in the loop.
*/
$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
if ( empty( $categories ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
}
$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
$thelist = '';
if ( '' === $separator ) {
$thelist .= '<ul class="post-categories">';
foreach ( $categories as $category ) {
$thelist .= "\n\t<li>";
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
break;
case 'single':
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= $category->name . '</a></li>';
break;
case '':
default:
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
}
}
$thelist .= '</ul>';
} else {
$i = 0;
foreach ( $categories as $category ) {
if ( 0 < $i ) {
$thelist .= $separator;
}
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
break;
case 'single':
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= "$category->name</a>";
break;
case '':
default:
$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
}
++$i;
}
}
/**
* Filters the category or list of categories.
*
* @since 1.2.0
*
* @param string $thelist List of categories for the current post.
* @param string $separator Separator used between the categories.
* @param string $parents How to display the category parents. Accepts 'multiple',
* 'single', or empty.
*/
return apply_filters( 'the_category', $thelist, $separator, $parents );
}
Hooks
- apply_filters( ‘the_category’,
string $thelist ,string $separator ,string $parents ) Filters the category or list of categories.
- apply_filters( ‘the_category_list’,
WP_Term[] $categories ,int|false $post_id ) Filters the categories before building the category list.
Changelog
Version | Description |
---|---|
1.5.1 | Introduced. |
Display as List Items
By leaving the
$separator
value empty, it will generate an unordered list instead, complete with classes.Result:
Implementation in WordPress default Twenty Eleven theme
In
content-single.php
: