| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Taxonomy API: Core category-specific template tags 4 * 5 * @package WordPress 6 * @subpackage Template 7 * @since 1.2.0 8 */ 9 10 /** 11 * Retrieve category link URL. 12 * 13 * @since 1.0.0 14 * @see get_term_link() 15 * 16 * @param int|object $category Category ID or object. 17 * @return string Link on success, empty string if category does not exist. 18 */ 19 function get_category_link( $category ) { 20 if ( ! is_object( $category ) ) { 21 $category = (int) $category; 22 } 23 24 $category = get_term_link( $category ); 25 26 if ( is_wp_error( $category ) ) { 27 return ''; 28 } 29 30 return $category; 31 } 32 33 /** 34 * Retrieve category parents with separator. 35 * 36 * @since 1.2.0 37 * @since 4.8.0 The `$visited` parameter was deprecated and renamed to `$deprecated`. 38 * 39 * @param int $id Category ID. 40 * @param bool $link Optional, default is false. Whether to format with link. 41 * @param string $separator Optional, default is '/'. How to separate categories. 42 * @param bool $nicename Optional, default is false. Whether to use nice name for display. 43 * @param array $deprecated Not used. 44 * @return string|WP_Error A list of category parents on success, WP_Error on failure. 45 */ 46 function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $deprecated = array() ) { 47 48 if ( ! empty( $deprecated ) ) { 49 _deprecated_argument( __FUNCTION__, '4.8.0' ); 50 } 51 52 $format = $nicename ? 'slug' : 'name'; 53 54 $args = array( 55 'separator' => $separator, 56 'link' => $link, 57 'format' => $format, 58 ); 59 60 return get_term_parents_list( $id, 'category', $args ); 61 } 62 63 /** 64 * Retrieve post categories. 65 * 66 * This tag may be used outside The Loop by passing a post id as the parameter. 67 * 68 * Note: This function only returns results from the default "category" taxonomy. 69 * For custom taxonomies use get_the_terms(). 70 * 71 * @since 0.71 72 * 73 * @param int $id Optional, default to current post ID. The post ID. 74 * @return WP_Term[] Array of WP_Term objects, one for each category assigned to the post. 75 */ 76 function get_the_category( $id = false ) { 77 $categories = get_the_terms( $id, 'category' ); 78 if ( ! $categories || is_wp_error( $categories ) ) { 79 $categories = array(); 80 } 81 82 $categories = array_values( $categories ); 83 84 foreach ( array_keys( $categories ) as $key ) { 85 _make_cat_compat( $categories[ $key ] ); 86 } 87 88 /** 89 * Filters the array of categories to return for a post. 90 * 91 * @since 3.1.0 92 * @since 4.4.0 Added `$id` parameter. 93 * 94 * @param WP_Term[] $categories An array of categories to return for the post. 95 * @param int|false $id ID of the post. 96 */ 97 return apply_filters( 'get_the_categories', $categories, $id ); 98 } 99 100 /** 101 * Retrieve category name based on category ID. 102 * 103 * @since 0.71 104 * 105 * @param int $cat_ID Category ID. 106 * @return string|WP_Error Category name on success, WP_Error on failure. 107 */ 108 function get_the_category_by_ID( $cat_ID ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid 109 $cat_ID = (int) $cat_ID; 110 $category = get_term( $cat_ID ); 111 112 if ( is_wp_error( $category ) ) { 113 return $category; 114 } 115 116 return ( $category ) ? $category->name : ''; 117 } 118 119 /** 120 * Retrieve category list for a post in either HTML list or custom format. 121 * 122 * @since 1.5.1 123 * 124 * @global WP_Rewrite $wp_rewrite WordPress rewrite component. 125 * 126 * @param string $separator Optional. Separator between the categories. By default, the links are placed 127 * in an unordered list. An empty string will result in the default behavior. 128 * @param string $parents Optional. How to display the parents. 129 * @param int $post_id Optional. Post ID to retrieve categories. 130 * @return string 131 */ 132 function get_the_category_list( $separator = '', $parents = '', $post_id = false ) { 133 global $wp_rewrite; 134 if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) { 135 /** This filter is documented in wp-includes/category-template.php */ 136 return apply_filters( 'the_category', '', $separator, $parents ); 137 } 138 139 /** 140 * Filters the categories before building the category list. 141 * 142 * @since 4.4.0 143 * 144 * @param WP_Term[] $categories An array of the post's categories. 145 * @param int|bool $post_id ID of the post we're retrieving categories for. When `false`, we assume the 146 * current post in the loop. 147 */ 148 $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id ); 149 150 if ( empty( $categories ) ) { 151 /** This filter is documented in wp-includes/category-template.php */ 152 return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents ); 153 } 154 155 $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"'; 156 157 $thelist = ''; 158 if ( '' == $separator ) { 159 $thelist .= '<ul class="post-categories">'; 160 foreach ( $categories as $category ) { 161 $thelist .= "\n\t<li>"; 162 switch ( strtolower( $parents ) ) { 163 case 'multiple': 164 if ( $category->parent ) { 165 $thelist .= get_category_parents( $category->parent, true, $separator ); 166 } 167 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>'; 168 break; 169 case 'single': 170 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>'; 171 if ( $category->parent ) { 172 $thelist .= get_category_parents( $category->parent, false, $separator ); 173 } 174 $thelist .= $category->name . '</a></li>'; 175 break; 176 case '': 177 default: 178 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>'; 179 } 180 } 181 $thelist .= '</ul>'; 182 } else { 183 $i = 0; 184 foreach ( $categories as $category ) { 185 if ( 0 < $i ) { 186 $thelist .= $separator; 187 } 188 switch ( strtolower( $parents ) ) { 189 case 'multiple': 190 if ( $category->parent ) { 191 $thelist .= get_category_parents( $category->parent, true, $separator ); 192 } 193 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>'; 194 break; 195 case 'single': 196 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>'; 197 if ( $category->parent ) { 198 $thelist .= get_category_parents( $category->parent, false, $separator ); 199 } 200 $thelist .= "$category->name</a>"; 201 break; 202 case '': 203 default: 204 $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>'; 205 } 206 ++$i; 207 } 208 } 209 210 /** 211 * Filters the category or list of categories. 212 * 213 * @since 1.2.0 214 * 215 * @param string $thelist List of categories for the current post. 216 * @param string $separator Separator used between the categories. 217 * @param string $parents How to display the category parents. Accepts 'multiple', 218 * 'single', or empty. 219 */ 220 return apply_filters( 'the_category', $thelist, $separator, $parents ); 221 } 222 223 /** 224 * Checks if the current post is within any of the given categories. 225 * 226 * The given categories are checked against the post's categories' term_ids, names and slugs. 227 * Categories given as integers will only be checked against the post's categories' term_ids. 228 * 229 * Prior to v2.5 of WordPress, category names were not supported. 230 * Prior to v2.7, category slugs were not supported. 231 * Prior to v2.7, only one category could be compared: in_category( $single_category ). 232 * Prior to v2.7, this function could only be used in the WordPress Loop. 233 * As of 2.7, the function can be used anywhere if it is provided a post ID or post object. 234 * 235 * For more information on this and similar theme functions, check out 236 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 237 * Conditional Tags} article in the Theme Developer Handbook. 238 * 239 * @since 1.2.0 240 * 241 * @param int|string|array $category Category ID, name or slug, or array of said. 242 * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0) 243 * @return bool True if the current post is in any of the given categories. 244 */ 245 function in_category( $category, $post = null ) { 246 if ( empty( $category ) ) { 247 return false; 248 } 249 250 return has_category( $category, $post ); 251 } 252 253 /** 254 * Display category list for a post in either HTML list or custom format. 255 * 256 * @since 0.71 257 * 258 * @param string $separator Optional. Separator between the categories. By default, the links are placed 259 * in an unordered list. An empty string will result in the default behavior. 260 * @param string $parents Optional. How to display the parents. 261 * @param int $post_id Optional. Post ID to retrieve categories. 262 */ 263 function the_category( $separator = '', $parents = '', $post_id = false ) { 264 echo get_the_category_list( $separator, $parents, $post_id ); 265 } 266 267 /** 268 * Retrieve category description. 269 * 270 * @since 1.0.0 271 * 272 * @param int $category Optional. Category ID. Will use global category ID by default. 273 * @return string Category description, available. 274 */ 275 function category_description( $category = 0 ) { 276 return term_description( $category ); 277 } 278 279 /** 280 * Display or retrieve the HTML dropdown list of categories. 281 * 282 * The 'hierarchical' argument, which is disabled by default, will override the 283 * depth argument, unless it is true. When the argument is false, it will 284 * display all of the categories. When it is enabled it will use the value in 285 * the 'depth' argument. 286 * 287 * @since 2.1.0 288 * @since 4.2.0 Introduced the `value_field` argument. 289 * @since 4.6.0 Introduced the `required` argument. 290 * 291 * @param array|string $args { 292 * Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct() 293 * for information on additional accepted arguments. 294 * 295 * @type string $show_option_all Text to display for showing all categories. Default empty. 296 * @type string $show_option_none Text to display for showing no categories. Default empty. 297 * @type string $option_none_value Value to use when no category is selected. Default empty. 298 * @type string $orderby Which column to use for ordering categories. See get_terms() for a list 299 * of accepted values. Default 'id' (term_id). 300 * @type bool $pad_counts See get_terms() for an argument description. Default false. 301 * @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents. 302 * Default 0. 303 * @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their 304 * bool equivalents. Default 1. 305 * @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool 306 * equivalents. Default 0. 307 * @type int $depth Maximum depth. Default 0. 308 * @type int $tab_index Tab index for the select element. Default 0 (no tabindex). 309 * @type string $name Value for the 'name' attribute of the select element. Default 'cat'. 310 * @type string $id Value for the 'id' attribute of the select element. Defaults to the value 311 * of `$name`. 312 * @type string $class Value for the 'class' attribute of the select element. Default 'postform'. 313 * @type int|string $selected Value of the option that should be selected. Default 0. 314 * @type string $value_field Term field that should be used to populate the 'value' attribute 315 * of the option elements. Accepts any valid term field: 'term_id', 'name', 316 * 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', 317 * 'parent', 'count'. Default 'term_id'. 318 * @type string|array $taxonomy Name of the category or categories to retrieve. Default 'category'. 319 * @type bool $hide_if_empty True to skip generating markup if no categories are found. 320 * Default false (create select element even if no categories are found). 321 * @type bool $required Whether the `<select>` element should have the HTML5 'required' attribute. 322 * Default false. 323 * } 324 * @return string HTML dropdown list of categories. 325 */ 326 function wp_dropdown_categories( $args = '' ) { 327 $defaults = array( 328 'show_option_all' => '', 329 'show_option_none' => '', 330 'orderby' => 'id', 331 'order' => 'ASC', 332 'show_count' => 0, 333 'hide_empty' => 1, 334 'child_of' => 0, 335 'exclude' => '', 336 'echo' => 1, 337 'selected' => 0, 338 'hierarchical' => 0, 339 'name' => 'cat', 340 'id' => '', 341 'class' => 'postform', 342 'depth' => 0, 343 'tab_index' => 0, 344 'taxonomy' => 'category', 345 'hide_if_empty' => false, 346 'option_none_value' => -1, 347 'value_field' => 'term_id', 348 'required' => false, 349 ); 350 351 $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0; 352 353 // Back compat. 354 if ( isset( $args['type'] ) && 'link' == $args['type'] ) { 355 _deprecated_argument( 356 __FUNCTION__, 357 '3.0.0', 358 sprintf( 359 /* translators: 1: "type => link", 2: "taxonomy => link_category" */ 360 __( '%1$s is deprecated. Use %2$s instead.' ), 361 '<code>type => link</code>', 362 '<code>taxonomy => link_category</code>' 363 ) 364 ); 365 $args['taxonomy'] = 'link_category'; 366 } 367 368 // Parse incoming $args into an array and merge it with $defaults. 369 $parsed_args = wp_parse_args( $args, $defaults ); 370 371 $option_none_value = $parsed_args['option_none_value']; 372 373 if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) { 374 $parsed_args['pad_counts'] = true; 375 } 376 377 $tab_index = $parsed_args['tab_index']; 378 379 $tab_index_attribute = ''; 380 if ( (int) $tab_index > 0 ) { 381 $tab_index_attribute = " tabindex=\"$tab_index\""; 382 } 383 384 // Avoid clashes with the 'name' param of get_terms(). 385 $get_terms_args = $parsed_args; 386 unset( $get_terms_args['name'] ); 387 $categories = get_terms( $get_terms_args ); 388 389 $name = esc_attr( $parsed_args['name'] ); 390 $class = esc_attr( $parsed_args['class'] ); 391 $id = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name; 392 $required = $parsed_args['required'] ? 'required' : ''; 393 394 if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) { 395 $output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n"; 396 } else { 397 $output = ''; 398 } 399 if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) { 400 401 /** 402 * Filters a taxonomy drop-down display element. 403 * 404 * A variety of taxonomy drop-down display elements can be modified 405 * just prior to display via this filter. Filterable arguments include 406 * 'show_option_none', 'show_option_all', and various forms of the 407 * term name. 408 * 409 * @since 1.2.0 410 * 411 * @see wp_dropdown_categories() 412 * 413 * @param string $element Category name. 414 * @param WP_Term|null $category The category object, or null if there's no corresponding category. 415 */ 416 $show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null ); 417 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n"; 418 } 419 420 if ( ! empty( $categories ) ) { 421 422 if ( $parsed_args['show_option_all'] ) { 423 424 /** This filter is documented in wp-includes/category-template.php */ 425 $show_option_all = apply_filters( 'list_cats', $parsed_args['show_option_all'], null ); 426 $selected = ( '0' === strval( $parsed_args['selected'] ) ) ? " selected='selected'" : ''; 427 $output .= "\t<option value='0'$selected>$show_option_all</option>\n"; 428 } 429 430 if ( $parsed_args['show_option_none'] ) { 431 432 /** This filter is documented in wp-includes/category-template.php */ 433 $show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null ); 434 $selected = selected( $option_none_value, $parsed_args['selected'], false ); 435 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n"; 436 } 437 438 if ( $parsed_args['hierarchical'] ) { 439 $depth = $parsed_args['depth']; // Walk the full depth. 440 } else { 441 $depth = -1; // Flat. 442 } 443 $output .= walk_category_dropdown_tree( $categories, $depth, $parsed_args ); 444 } 445 446 if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) { 447 $output .= "</select>\n"; 448 } 449 450 /** 451 * Filters the taxonomy drop-down output. 452 * 453 * @since 2.1.0 454 * 455 * @param string $output HTML output. 456 * @param array $parsed_args Arguments used to build the drop-down. 457 */ 458 $output = apply_filters( 'wp_dropdown_cats', $output, $parsed_args ); 459 460 if ( $parsed_args['echo'] ) { 461 echo $output; 462 } 463 464 return $output; 465 } 466 467 /** 468 * Display or retrieve the HTML list of categories. 469 * 470 * @since 2.1.0 471 * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. 472 * @since 4.4.0 The `current_category` argument was modified to optionally accept an array of values. 473 * 474 * @param array|string $args { 475 * Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct() 476 * for information on additional accepted arguments. 477 * 478 * @type int|array $current_category ID of category, or array of IDs of categories, that should get the 479 * 'current-cat' class. Default 0. 480 * @type int $depth Category depth. Used for tab indentation. Default 0. 481 * @type bool|int $echo True to echo markup, false to return it. Default 1. 482 * @type array|string $exclude Array or comma/space-separated string of term IDs to exclude. 483 * If `$hierarchical` is true, descendants of `$exclude` terms will also 484 * be excluded; see `$exclude_tree`. See get_terms(). 485 * Default empty string. 486 * @type array|string $exclude_tree Array or comma/space-separated string of term IDs to exclude, along 487 * with their descendants. See get_terms(). Default empty string. 488 * @type string $feed Text to use for the feed link. Default 'Feed for all posts filed 489 * under [cat name]'. 490 * @type string $feed_image URL of an image to use for the feed link. Default empty string. 491 * @type string $feed_type Feed type. Used to build feed link. See get_term_feed_link(). 492 * Default empty string (default feed). 493 * @type bool $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in 494 * the list. Default false (title will always be shown). 495 * @type string $separator Separator between links. Default '<br />'. 496 * @type bool|int $show_count Whether to show how many posts are in the category. Default 0. 497 * @type string $show_option_all Text to display for showing all categories. Default empty string. 498 * @type string $show_option_none Text to display for the 'no categories' option. 499 * Default 'No categories'. 500 * @type string $style The style used to display the categories list. If 'list', categories 501 * will be output as an unordered list. If left empty or another value, 502 * categories will be output separated by `<br>` tags. Default 'list'. 503 * @type string $title_li Text to use for the list title `<li>` element. Pass an empty string 504 * to disable. Default 'Categories'. 505 * @type bool|int $use_desc_for_title Whether to use the category description as the title attribute. 506 * Default 1. 507 * } 508 * @return false|string HTML list of categories only if 'echo' argument is 0. 509 */ 510 function wp_list_categories( $args = '' ) { 511 $defaults = array( 512 'child_of' => 0, 513 'current_category' => 0, 514 'depth' => 0, 515 'echo' => 1, 516 'exclude' => '', 517 'exclude_tree' => '', 518 'feed' => '', 519 'feed_image' => '', 520 'feed_type' => '', 521 'hide_empty' => 1, 522 'hide_title_if_empty' => false, 523 'hierarchical' => true, 524 'order' => 'ASC', 525 'orderby' => 'name', 526 'separator' => '<br />', 527 'show_count' => 0, 528 'show_option_all' => '', 529 'show_option_none' => __( 'No categories' ), 530 'style' => 'list', 531 'taxonomy' => 'category', 532 'title_li' => __( 'Categories' ), 533 'use_desc_for_title' => 1, 534 ); 535 536 $parsed_args = wp_parse_args( $args, $defaults ); 537 538 if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) { 539 $parsed_args['pad_counts'] = true; 540 } 541 542 // Descendants of exclusions should be excluded too. 543 if ( true == $parsed_args['hierarchical'] ) { 544 $exclude_tree = array(); 545 546 if ( $parsed_args['exclude_tree'] ) { 547 $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude_tree'] ) ); 548 } 549 550 if ( $parsed_args['exclude'] ) { 551 $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $parsed_args['exclude'] ) ); 552 } 553 554 $parsed_args['exclude_tree'] = $exclude_tree; 555 $parsed_args['exclude'] = ''; 556 } 557 558 if ( ! isset( $parsed_args['class'] ) ) { 559 $parsed_args['class'] = ( 'category' == $parsed_args['taxonomy'] ) ? 'categories' : $parsed_args['taxonomy']; 560 } 561 562 if ( ! taxonomy_exists( $parsed_args['taxonomy'] ) ) { 563 return false; 564 } 565 566 $show_option_all = $parsed_args['show_option_all']; 567 $show_option_none = $parsed_args['show_option_none']; 568 569 $categories = get_categories( $parsed_args ); 570 571 $output = ''; 572 if ( $parsed_args['title_li'] && 'list' == $parsed_args['style'] && ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] ) ) { 573 $output = '<li class="' . esc_attr( $parsed_args['class'] ) . '">' . $parsed_args['title_li'] . '<ul>'; 574 } 575 if ( empty( $categories ) ) { 576 if ( ! empty( $show_option_none ) ) { 577 if ( 'list' == $parsed_args['style'] ) { 578 $output .= '<li class="cat-item-none">' . $show_option_none . '</li>'; 579 } else { 580 $output .= $show_option_none; 581 } 582 } 583 } else { 584 if ( ! empty( $show_option_all ) ) { 585 586 $posts_page = ''; 587 588 // For taxonomies that belong only to custom post types, point to a valid archive. 589 $taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] ); 590 if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) { 591 foreach ( $taxonomy_object->object_type as $object_type ) { 592 $_object_type = get_post_type_object( $object_type ); 593 594 // Grab the first one. 595 if ( ! empty( $_object_type->has_archive ) ) { 596 $posts_page = get_post_type_archive_link( $object_type ); 597 break; 598 } 599 } 600 } 601 602 // Fallback for the 'All' link is the posts page. 603 if ( ! $posts_page ) { 604 if ( 'page' == get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) { 605 $posts_page = get_permalink( get_option( 'page_for_posts' ) ); 606 } else { 607 $posts_page = home_url( '/' ); 608 } 609 } 610 611 $posts_page = esc_url( $posts_page ); 612 if ( 'list' == $parsed_args['style'] ) { 613 $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>"; 614 } else { 615 $output .= "<a href='$posts_page'>$show_option_all</a>"; 616 } 617 } 618 619 if ( empty( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) { 620 $current_term_object = get_queried_object(); 621 if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) { 622 $parsed_args['current_category'] = get_queried_object_id(); 623 } 624 } 625 626 if ( $parsed_args['hierarchical'] ) { 627 $depth = $parsed_args['depth']; 628 } else { 629 $depth = -1; // Flat. 630 } 631 $output .= walk_category_tree( $categories, $depth, $parsed_args ); 632 } 633 634 if ( $parsed_args['title_li'] && 'list' == $parsed_args['style'] && ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] ) ) { 635 $output .= '</ul></li>'; 636 } 637 638 /** 639 * Filters the HTML output of a taxonomy list. 640 * 641 * @since 2.1.0 642 * 643 * @param string $output HTML output. 644 * @param array $args An array of taxonomy-listing arguments. 645 */ 646 $html = apply_filters( 'wp_list_categories', $output, $args ); 647 648 if ( $parsed_args['echo'] ) { 649 echo $html; 650 } else { 651 return $html; 652 } 653 } 654 655 /** 656 * Displays a tag cloud. 657 * 658 * @since 2.3.0 659 * @since 4.8.0 Added the `show_count` argument. 660 * 661 * @param array|string $args { 662 * Optional. Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud() 663 * and get_terms() for the full lists of arguments that can be passed in `$args`. 664 * 665 * @type int $number The number of tags to display. Accepts any positive integer 666 * or zero to return all. Default 0 (all tags). 667 * @type string $link Whether to display term editing links or term permalinks. 668 * Accepts 'edit' and 'view'. Default 'view'. 669 * @type string $post_type The post type. Used to highlight the proper post type menu 670 * on the linked edit page. Defaults to the first post type 671 * associated with the taxonomy. 672 * @type bool $echo Whether or not to echo the return value. Default true. 673 * } 674 * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument. 675 * Otherwise, this function outputs the tag cloud. 676 */ 677 function wp_tag_cloud( $args = '' ) { 678 $defaults = array( 679 'smallest' => 8, 680 'largest' => 22, 681 'unit' => 'pt', 682 'number' => 45, 683 'format' => 'flat', 684 'separator' => "\n", 685 'orderby' => 'name', 686 'order' => 'ASC', 687 'exclude' => '', 688 'include' => '', 689 'link' => 'view', 690 'taxonomy' => 'post_tag', 691 'post_type' => '', 692 'echo' => true, 693 'show_count' => 0, 694 ); 695 $args = wp_parse_args( $args, $defaults ); 696 697 $tags = get_terms( 698 array_merge( 699 $args, 700 array( 701 'orderby' => 'count', 702 'order' => 'DESC', 703 ) 704 ) 705 ); // Always query top tags 706 707 if ( empty( $tags ) || is_wp_error( $tags ) ) { 708 return; 709 } 710 711 foreach ( $tags as $key => $tag ) { 712 if ( 'edit' == $args['link'] ) { 713 $link = get_edit_term_link( $tag->term_id, $tag->taxonomy, $args['post_type'] ); 714 } else { 715 $link = get_term_link( intval( $tag->term_id ), $tag->taxonomy ); 716 } 717 if ( is_wp_error( $link ) ) { 718 return; 719 } 720 721 $tags[ $key ]->link = $link; 722 $tags[ $key ]->id = $tag->term_id; 723 } 724 725 $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args 726 727 /** 728 * Filters the tag cloud output. 729 * 730 * @since 2.3.0 731 * 732 * @param string $return HTML output of the tag cloud. 733 * @param array $args An array of tag cloud arguments. 734 */ 735 $return = apply_filters( 'wp_tag_cloud', $return, $args ); 736 737 if ( 'array' == $args['format'] || empty( $args['echo'] ) ) { 738 return $return; 739 } 740 741 echo $return; 742 } 743 744 /** 745 * Default topic count scaling for tag links. 746 * 747 * @since 2.9.0 748 * 749 * @param int $count Number of posts with that tag. 750 * @return int Scaled count. 751 */ 752 function default_topic_count_scale( $count ) { 753 return round( log10( $count + 1 ) * 100 ); 754 } 755 756 /** 757 * Generates a tag cloud (heatmap) from provided data. 758 * 759 * @todo Complete functionality. 760 * @since 2.3.0 761 * @since 4.8.0 Added the `show_count` argument. 762 * 763 * @param WP_Term[] $tags Array of WP_Term objects to generate the tag cloud for. 764 * @param string|array $args { 765 * Optional. Array or string of arguments for generating a tag cloud. 766 * 767 * @type int $smallest Smallest font size used to display tags. Paired 768 * with the value of `$unit`, to determine CSS text 769 * size unit. Default 8 (pt). 770 * @type int $largest Largest font size used to display tags. Paired 771 * with the value of `$unit`, to determine CSS text 772 * size unit. Default 22 (pt). 773 * @type string $unit CSS text size unit to use with the `$smallest` 774 * and `$largest` values. Accepts any valid CSS text 775 * size unit. Default 'pt'. 776 * @type int $number The number of tags to return. Accepts any 777 * positive integer or zero to return all. 778 * Default 0. 779 * @type string $format Format to display the tag cloud in. Accepts 'flat' 780 * (tags separated with spaces), 'list' (tags displayed 781 * in an unordered list), or 'array' (returns an array). 782 * Default 'flat'. 783 * @type string $separator HTML or text to separate the tags. Default "\n" (newline). 784 * @type string $orderby Value to order tags by. Accepts 'name' or 'count'. 785 * Default 'name'. The {@see 'tag_cloud_sort'} filter 786 * can also affect how tags are sorted. 787 * @type string $order How to order the tags. Accepts 'ASC' (ascending), 788 * 'DESC' (descending), or 'RAND' (random). Default 'ASC'. 789 * @type int|bool $filter Whether to enable filtering of the final output 790 * via {@see 'wp_generate_tag_cloud'}. Default 1|true. 791 * @type string $topic_count_text Nooped plural text from _n_noop() to supply to 792 * tag counts. Default null. 793 * @type callable $topic_count_text_callback Callback used to generate nooped plural text for 794 * tag counts based on the count. Default null. 795 * @type callable $topic_count_scale_callback Callback used to determine the tag count scaling 796 * value. Default default_topic_count_scale(). 797 * @type bool|int $show_count Whether to display the tag counts. Default 0. Accepts 798 * 0, 1, or their bool equivalents. 799 * } 800 * @return string|array Tag cloud as a string or an array, depending on 'format' argument. 801 */ 802 function wp_generate_tag_cloud( $tags, $args = '' ) { 803 $defaults = array( 804 'smallest' => 8, 805 'largest' => 22, 806 'unit' => 'pt', 807 'number' => 0, 808 'format' => 'flat', 809 'separator' => "\n", 810 'orderby' => 'name', 811 'order' => 'ASC', 812 'topic_count_text' => null, 813 'topic_count_text_callback' => null, 814 'topic_count_scale_callback' => 'default_topic_count_scale', 815 'filter' => 1, 816 'show_count' => 0, 817 ); 818 819 $args = wp_parse_args( $args, $defaults ); 820 821 $return = ( 'array' === $args['format'] ) ? array() : ''; 822 823 if ( empty( $tags ) ) { 824 return $return; 825 } 826 827 // Juggle topic counts. 828 if ( isset( $args['topic_count_text'] ) ) { 829 // First look for nooped plural support via topic_count_text. 830 $translate_nooped_plural = $args['topic_count_text']; 831 } elseif ( ! empty( $args['topic_count_text_callback'] ) ) { 832 // Look for the alternative callback style. Ignore the previous default. 833 if ( $args['topic_count_text_callback'] === 'default_topic_count_text' ) { 834 /* translators: %s: Number of items (tags). */ 835 $translate_nooped_plural = _n_noop( '%s item', '%s items' ); 836 } else { 837 $translate_nooped_plural = false; 838 } 839 } elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) { 840 // If no callback exists, look for the old-style single_text and multiple_text arguments. 841 // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingle,WordPress.WP.I18n.NonSingularStringLiteralPlural 842 $translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] ); 843 } else { 844 // This is the default for when no callback, plural, or argument is passed in. 845 /* translators: %s: Number of items (tags). */ 846 $translate_nooped_plural = _n_noop( '%s item', '%s items' ); 847 } 848 849 /** 850 * Filters how the items in a tag cloud are sorted. 851 * 852 * @since 2.8.0 853 * 854 * @param WP_Term[] $tags Ordered array of terms. 855 * @param array $args An array of tag cloud arguments. 856 */ 857 $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args ); 858 if ( empty( $tags_sorted ) ) { 859 return $return; 860 } 861 862 if ( $tags_sorted !== $tags ) { 863 $tags = $tags_sorted; 864 unset( $tags_sorted ); 865 } else { 866 if ( 'RAND' === $args['order'] ) { 867 shuffle( $tags ); 868 } else { 869 // SQL cannot save you; this is a second (potentially different) sort on a subset of data. 870 if ( 'name' === $args['orderby'] ) { 871 uasort( $tags, '_wp_object_name_sort_cb' ); 872 } else { 873 uasort( $tags, '_wp_object_count_sort_cb' ); 874 } 875 876 if ( 'DESC' === $args['order'] ) { 877 $tags = array_reverse( $tags, true ); 878 } 879 } 880 } 881 882 if ( $args['number'] > 0 ) { 883 $tags = array_slice( $tags, 0, $args['number'] ); 884 } 885 886 $counts = array(); 887 $real_counts = array(); // For the alt tag 888 foreach ( (array) $tags as $key => $tag ) { 889 $real_counts[ $key ] = $tag->count; 890 $counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count ); 891 } 892 893 $min_count = min( $counts ); 894 $spread = max( $counts ) - $min_count; 895 if ( $spread <= 0 ) { 896 $spread = 1; 897 } 898 $font_spread = $args['largest'] - $args['smallest']; 899 if ( $font_spread < 0 ) { 900 $font_spread = 1; 901 } 902 $font_step = $font_spread / $spread; 903 904 $aria_label = false; 905 /* 906 * Determine whether to output an 'aria-label' attribute with the tag name and count. 907 * When tags have a different font size, they visually convey an important information 908 * that should be available to assistive technologies too. On the other hand, sometimes 909 * themes set up the Tag Cloud to display all tags with the same font size (setting 910 * the 'smallest' and 'largest' arguments to the same value). 911 * In order to always serve the same content to all users, the 'aria-label' gets printed out: 912 * - when tags have a different size 913 * - when the tag count is displayed (for example when users check the checkbox in the 914 * Tag Cloud widget), regardless of the tags font size 915 */ 916 if ( $args['show_count'] || 0 !== $font_spread ) { 917 $aria_label = true; 918 } 919 920 // Assemble the data that will be used to generate the tag cloud markup. 921 $tags_data = array(); 922 foreach ( $tags as $key => $tag ) { 923 $tag_id = isset( $tag->id ) ? $tag->id : $key; 924 925 $count = $counts[ $key ]; 926 $real_count = $real_counts[ $key ]; 927 928 if ( $translate_nooped_plural ) { 929 $formatted_count = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) ); 930 } else { 931 $formatted_count = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args ); 932 } 933 934 $tags_data[] = array( 935 'id' => $tag_id, 936 'url' => '#' != $tag->link ? $tag->link : '#', 937 'role' => '#' != $tag->link ? '' : ' role="button"', 938 'name' => $tag->name, 939 'formatted_count' => $formatted_count, 940 'slug' => $tag->slug, 941 'real_count' => $real_count, 942 'class' => 'tag-cloud-link tag-link-' . $tag_id, 943 'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step, 944 'aria_label' => $aria_label ? sprintf( ' aria-label="%1$s (%2$s)"', esc_attr( $tag->name ), esc_attr( $formatted_count ) ) : '', 945 'show_count' => $args['show_count'] ? '<span class="tag-link-count"> (' . $real_count . ')</span>' : '', 946 ); 947 } 948 949 /** 950 * Filters the data used to generate the tag cloud. 951 * 952 * @since 4.3.0 953 * 954 * @param array $tags_data An array of term data for term used to generate the tag cloud. 955 */ 956 $tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data ); 957 958 $a = array(); 959 960 // Generate the output links array. 961 foreach ( $tags_data as $key => $tag_data ) { 962 $class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 ); 963 $a[] = sprintf( 964 '<a href="%1$s"%2$s class="%3$s" style="font-size: %4$s;"%5$s>%6$s%7$s</a>', 965 esc_url( $tag_data['url'] ), 966 $tag_data['role'], 967 esc_attr( $class ), 968 esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ), 969 $tag_data['aria_label'], 970 esc_html( $tag_data['name'] ), 971 $tag_data['show_count'] 972 ); 973 } 974 975 switch ( $args['format'] ) { 976 case 'array': 977 $return =& $a; 978 break; 979 case 'list': 980 /* 981 * Force role="list", as some browsers (sic: Safari 10) don't expose to assistive 982 * technologies the default role when the list is styled with `list-style: none`. 983 * Note: this is redundant but doesn't harm. 984 */ 985 $return = "<ul class='wp-tag-cloud' role='list'>\n\t<li>"; 986 $return .= join( "</li>\n\t<li>", $a ); 987 $return .= "</li>\n</ul>\n"; 988 break; 989 default: 990 $return = join( $args['separator'], $a ); 991 break; 992 } 993 994 if ( $args['filter'] ) { 995 /** 996 * Filters the generated output of a tag cloud. 997 * 998 * The filter is only evaluated if a true value is passed 999 * to the $filter argument in wp_generate_tag_cloud(). 1000 * 1001 * @since 2.3.0 1002 * 1003 * @see wp_generate_tag_cloud() 1004 * 1005 * @param array|string $return String containing the generated HTML tag cloud output 1006 * or an array of tag links if the 'format' argument 1007 * equals 'array'. 1008 * @param WP_Term[] $tags An array of terms used in the tag cloud. 1009 * @param array $args An array of wp_generate_tag_cloud() arguments. 1010 */ 1011 return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args ); 1012 } else { 1013 return $return; 1014 } 1015 } 1016 1017 /** 1018 * Serves as a callback for comparing objects based on name. 1019 * 1020 * Used with `uasort()`. 1021 * 1022 * @since 3.1.0 1023 * @access private 1024 * 1025 * @param object $a The first object to compare. 1026 * @param object $b The second object to compare. 1027 * @return int Negative number if `$a->name` is less than `$b->name`, zero if they are equal, 1028 * or greater than zero if `$a->name` is greater than `$b->name`. 1029 */ 1030 function _wp_object_name_sort_cb( $a, $b ) { 1031 return strnatcasecmp( $a->name, $b->name ); 1032 } 1033 1034 /** 1035 * Serves as a callback for comparing objects based on count. 1036 * 1037 * Used with `uasort()`. 1038 * 1039 * @since 3.1.0 1040 * @access private 1041 * 1042 * @param object $a The first object to compare. 1043 * @param object $b The second object to compare. 1044 * @return bool Whether the count value for `$a` is greater than the count value for `$b`. 1045 */ 1046 function _wp_object_count_sort_cb( $a, $b ) { 1047 return ( $a->count > $b->count ); 1048 } 1049 1050 // 1051 // Helper functions 1052 // 1053 1054 /** 1055 * Retrieve HTML list content for category list. 1056 * 1057 * @since 2.1.0 1058 * @since 5.3.0 Formalized the existing `...$args` parameter by adding it 1059 * to the function signature. 1060 * 1061 * @uses Walker_Category to create HTML list content. 1062 * @see Walker::walk() for parameters and return description. 1063 * 1064 * @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments. 1065 * @return string 1066 */ 1067 function walk_category_tree( ...$args ) { 1068 // The user's options are the third parameter. 1069 if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) { 1070 $walker = new Walker_Category; 1071 } else { 1072 $walker = $args[2]['walker']; 1073 } 1074 return $walker->walk( ...$args ); 1075 } 1076 1077 /** 1078 * Retrieve HTML dropdown (select) content for category list. 1079 * 1080 * @since 2.1.0 1081 * @since 5.3.0 Formalized the existing `...$args` parameter by adding it 1082 * to the function signature. 1083 * 1084 * @uses Walker_CategoryDropdown to create HTML dropdown content. 1085 * @see Walker::walk() for parameters and return description. 1086 * 1087 * @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments. 1088 * @return string 1089 */ 1090 function walk_category_dropdown_tree( ...$args ) { 1091 // The user's options are the third parameter. 1092 if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) { 1093 $walker = new Walker_CategoryDropdown; 1094 } else { 1095 $walker = $args[2]['walker']; 1096 } 1097 return $walker->walk( ...$args ); 1098 } 1099 1100 // 1101 // Tags 1102 // 1103 1104 /** 1105 * Retrieve the link to the tag. 1106 * 1107 * @since 2.3.0 1108 * @see get_term_link() 1109 * 1110 * @param int|object $tag Tag ID or object. 1111 * @return string Link on success, empty string if tag does not exist. 1112 */ 1113 function get_tag_link( $tag ) { 1114 return get_category_link( $tag ); 1115 } 1116 1117 /** 1118 * Retrieve the tags for a post. 1119 * 1120 * @since 2.3.0 1121 * 1122 * @param int $id Post ID. 1123 * @return array|false|WP_Error Array of tag objects on success, false on failure. 1124 */ 1125 function get_the_tags( $id = 0 ) { 1126 1127 /** 1128 * Filters the array of tags for the given post. 1129 * 1130 * @since 2.3.0 1131 * 1132 * @see get_the_terms() 1133 * 1134 * @param WP_Term[] $terms An array of tags for the given post. 1135 */ 1136 return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) ); 1137 } 1138 1139 /** 1140 * Retrieve the tags for a post formatted as a string. 1141 * 1142 * @since 2.3.0 1143 * 1144 * @param string $before Optional. Before tags. 1145 * @param string $sep Optional. Between tags. 1146 * @param string $after Optional. After tags. 1147 * @param int $id Optional. Post ID. Defaults to the current post. 1148 * @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure. 1149 */ 1150 function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) { 1151 1152 /** 1153 * Filters the tags list for a given post. 1154 * 1155 * @since 2.3.0 1156 * 1157 * @param string $tag_list List of tags. 1158 * @param string $before String to use before tags. 1159 * @param string $sep String to use between the tags. 1160 * @param string $after String to use after tags. 1161 * @param int $id Post ID. 1162 */ 1163 return apply_filters( 'the_tags', get_the_term_list( $id, 'post_tag', $before, $sep, $after ), $before, $sep, $after, $id ); 1164 } 1165 1166 /** 1167 * Retrieve the tags for a post. 1168 * 1169 * @since 2.3.0 1170 * 1171 * @param string $before Optional. Before list. 1172 * @param string $sep Optional. Separate items using this. 1173 * @param string $after Optional. After list. 1174 */ 1175 function the_tags( $before = null, $sep = ', ', $after = '' ) { 1176 if ( null === $before ) { 1177 $before = __( 'Tags: ' ); 1178 } 1179 1180 $the_tags = get_the_tag_list( $before, $sep, $after ); 1181 1182 if ( ! is_wp_error( $the_tags ) ) { 1183 echo $the_tags; 1184 } 1185 } 1186 1187 /** 1188 * Retrieve tag description. 1189 * 1190 * @since 2.8.0 1191 * 1192 * @param int $tag Optional. Tag ID. Will use global tag ID by default. 1193 * @return string Tag description, available. 1194 */ 1195 function tag_description( $tag = 0 ) { 1196 return term_description( $tag ); 1197 } 1198 1199 /** 1200 * Retrieve term description. 1201 * 1202 * @since 2.8.0 1203 * @since 4.9.2 The `$taxonomy` parameter was deprecated. 1204 * 1205 * @param int $term Optional. Term ID. Will use global term ID by default. 1206 * @param null $deprecated Deprecated argument. 1207 * @return string Term description, available. 1208 */ 1209 function term_description( $term = 0, $deprecated = null ) { 1210 if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) { 1211 $term = get_queried_object(); 1212 if ( $term ) { 1213 $term = $term->term_id; 1214 } 1215 } 1216 $description = get_term_field( 'description', $term ); 1217 return is_wp_error( $description ) ? '' : $description; 1218 } 1219 1220 /** 1221 * Retrieve the terms of the taxonomy that are attached to the post. 1222 * 1223 * @since 2.5.0 1224 * 1225 * @param int|WP_Post $post Post ID or object. 1226 * @param string $taxonomy Taxonomy name. 1227 * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms 1228 * or the post does not exist, WP_Error on failure. 1229 */ 1230 function get_the_terms( $post, $taxonomy ) { 1231 $post = get_post( $post ); 1232 if ( ! $post ) { 1233 return false; 1234 } 1235 1236 $terms = get_object_term_cache( $post->ID, $taxonomy ); 1237 if ( false === $terms ) { 1238 $terms = wp_get_object_terms( $post->ID, $taxonomy ); 1239 if ( ! is_wp_error( $terms ) ) { 1240 $term_ids = wp_list_pluck( $terms, 'term_id' ); 1241 wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' ); 1242 } 1243 } 1244 1245 /** 1246 * Filters the list of terms attached to the given post. 1247 * 1248 * @since 3.1.0 1249 * 1250 * @param WP_Term[]|WP_Error $terms Array of attached terms, or WP_Error on failure. 1251 * @param int $post_id Post ID. 1252 * @param string $taxonomy Name of the taxonomy. 1253 */ 1254 $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy ); 1255 1256 if ( empty( $terms ) ) { 1257 return false; 1258 } 1259 1260 return $terms; 1261 } 1262 1263 /** 1264 * Retrieve a post's terms as a list with specified format. 1265 * 1266 * @since 2.5.0 1267 * 1268 * @param int $id Post ID. 1269 * @param string $taxonomy Taxonomy name. 1270 * @param string $before Optional. Before list. 1271 * @param string $sep Optional. Separate items using this. 1272 * @param string $after Optional. After list. 1273 * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure. 1274 */ 1275 function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = '' ) { 1276 $terms = get_the_terms( $id, $taxonomy ); 1277 1278 if ( is_wp_error( $terms ) ) { 1279 return $terms; 1280 } 1281 1282 if ( empty( $terms ) ) { 1283 return false; 1284 } 1285 1286 $links = array(); 1287 1288 foreach ( $terms as $term ) { 1289 $link = get_term_link( $term, $taxonomy ); 1290 if ( is_wp_error( $link ) ) { 1291 return $link; 1292 } 1293 $links[] = '<a href="' . esc_url( $link ) . '" rel="tag">' . $term->name . '</a>'; 1294 } 1295 1296 /** 1297 * Filters the term links for a given taxonomy. 1298 * 1299 * The dynamic portion of the filter name, `$taxonomy`, refers 1300 * to the taxonomy slug. 1301 * 1302 * @since 2.5.0 1303 * 1304 * @param string[] $links An array of term links. 1305 */ 1306 $term_links = apply_filters( "term_links-{$taxonomy}", $links ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores 1307 1308 return $before . join( $sep, $term_links ) . $after; 1309 } 1310 1311 /** 1312 * Retrieve term parents with separator. 1313 * 1314 * @since 4.8.0 1315 * 1316 * @param int $term_id Term ID. 1317 * @param string $taxonomy Taxonomy name. 1318 * @param string|array $args { 1319 * Array of optional arguments. 1320 * 1321 * @type string $format Use term names or slugs for display. Accepts 'name' or 'slug'. 1322 * Default 'name'. 1323 * @type string $separator Separator for between the terms. Default '/'. 1324 * @type bool $link Whether to format as a link. Default true. 1325 * @type bool $inclusive Include the term to get the parents for. Default true. 1326 * } 1327 * @return string|WP_Error A list of term parents on success, WP_Error or empty string on failure. 1328 */ 1329 function get_term_parents_list( $term_id, $taxonomy, $args = array() ) { 1330 $list = ''; 1331 $term = get_term( $term_id, $taxonomy ); 1332 1333 if ( is_wp_error( $term ) ) { 1334 return $term; 1335 } 1336 1337 if ( ! $term ) { 1338 return $list; 1339 } 1340 1341 $term_id = $term->term_id; 1342 1343 $defaults = array( 1344 'format' => 'name', 1345 'separator' => '/', 1346 'link' => true, 1347 'inclusive' => true, 1348 ); 1349 1350 $args = wp_parse_args( $args, $defaults ); 1351 1352 foreach ( array( 'link', 'inclusive' ) as $bool ) { 1353 $args[ $bool ] = wp_validate_boolean( $args[ $bool ] ); 1354 } 1355 1356 $parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' ); 1357 1358 if ( $args['inclusive'] ) { 1359 array_unshift( $parents, $term_id ); 1360 } 1361 1362 foreach ( array_reverse( $parents ) as $term_id ) { 1363 $parent = get_term( $term_id, $taxonomy ); 1364 $name = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name; 1365 1366 if ( $args['link'] ) { 1367 $list .= '<a href="' . esc_url( get_term_link( $parent->term_id, $taxonomy ) ) . '">' . $name . '</a>' . $args['separator']; 1368 } else { 1369 $list .= $name . $args['separator']; 1370 } 1371 } 1372 1373 return $list; 1374 } 1375 1376 /** 1377 * Display the terms in a list. 1378 * 1379 * @since 2.5.0 1380 * 1381 * @param int $id Post ID. 1382 * @param string $taxonomy Taxonomy name. 1383 * @param string $before Optional. Before list. 1384 * @param string $sep Optional. Separate items using this. 1385 * @param string $after Optional. After list. 1386 * @return false|void False on WordPress error. 1387 */ 1388 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) { 1389 $term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after ); 1390 1391 if ( is_wp_error( $term_list ) ) { 1392 return false; 1393 } 1394 1395 /** 1396 * Filters the list of terms to display. 1397 * 1398 * @since 2.9.0 1399 * 1400 * @param string $term_list List of terms to display. 1401 * @param string $taxonomy The taxonomy name. 1402 * @param string $before String to use before the terms. 1403 * @param string $sep String to use between the terms. 1404 * @param string $after String to use after the terms. 1405 */ 1406 echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after ); 1407 } 1408 1409 /** 1410 * Check if the current post has any of given category. 1411 * 1412 * @since 3.1.0 1413 * 1414 * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for. 1415 * @param int|object $post Optional. Post to check instead of the current post. 1416 * @return bool True if the current post has any of the given categories (or any category, if no category specified). 1417 */ 1418 function has_category( $category = '', $post = null ) { 1419 return has_term( $category, 'category', $post ); 1420 } 1421 1422 /** 1423 * Checks if the current post has any of given tags. 1424 * 1425 * The given tags are checked against the post's tags' term_ids, names and slugs. 1426 * Tags given as integers will only be checked against the post's tags' term_ids. 1427 * If no tags are given, determines if post has any tags. 1428 * 1429 * Prior to v2.7 of WordPress, tags given as integers would also be checked against the post's tags' names and slugs (in addition to term_ids) 1430 * Prior to v2.7, this function could only be used in the WordPress Loop. 1431 * As of 2.7, the function can be used anywhere if it is provided a post ID or post object. 1432 * 1433 * For more information on this and similar theme functions, check out 1434 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 1435 * Conditional Tags} article in the Theme Developer Handbook. 1436 * 1437 * @since 2.6.0 1438 * 1439 * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for. 1440 * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0) 1441 * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). 1442 */ 1443 function has_tag( $tag = '', $post = null ) { 1444 return has_term( $tag, 'post_tag', $post ); 1445 } 1446 1447 /** 1448 * Check if the current post has any of given terms. 1449 * 1450 * The given terms are checked against the post's terms' term_ids, names and slugs. 1451 * Terms given as integers will only be checked against the post's terms' term_ids. 1452 * If no terms are given, determines if post has any terms. 1453 * 1454 * @since 3.1.0 1455 * 1456 * @param string|int|array $term Optional. The term name/term_id/slug or array of them to check for. 1457 * @param string $taxonomy Taxonomy name 1458 * @param int|object $post Optional. Post to check instead of the current post. 1459 * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). 1460 */ 1461 function has_term( $term = '', $taxonomy = '', $post = null ) { 1462 $post = get_post( $post ); 1463 1464 if ( ! $post ) { 1465 return false; 1466 } 1467 1468 $r = is_object_in_term( $post->ID, $taxonomy, $term ); 1469 if ( is_wp_error( $r ) ) { 1470 return false; 1471 } 1472 1473 return $r; 1474 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sat Nov 23 20:47:33 2019 | Cross-referenced by PHPXref 0.7 |