get_the_category_list
Retrieve category list in either HTML list or custom format.
Description
(string) get_the_category_list( (string) $separator = '', (string) $parents = '', (bool) $post_id = false );
Returns (string)
Parameters (3)
- 0. $separator — Optional. (string) =>
''
- Optional, default is empty string. Separator for between the categories.
- 1. $parents — Optional. (string) =>
''
- How to display the parents.
- 2. $post_id — Optional. (bool) =>
false
- Post ID to retrieve categories.
Usage
if ( !function_exists( 'get_the_category_list' ) ) { require_once ABSPATH . WPINC . '/category-template.php'; } // Optional, default is empty string. Separator for between the categories. $separator = ''; // Optional. How to display the parents. $parents = ''; // Optional. Post ID to retrieve categories. $post_id = false; // NOTICE! Understand what this does before running. $result = get_the_category_list($separator, $parents, $post_id);
Defined (1)
The function is defined in the following location(s).
- /wp-includes/category-template.php
- 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 array $categories An array of the post's categories.
- * @param int|bool $post_id ID of the post we're retrieving categories for. When `false`, we assume the
- * current post in the loop.
- */
- if ( empty( $categories ) ) {
- /** This filter is documented in wp-includes/category-template.php */
- }
- $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 array $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 );
- }