| [ 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 ) { 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 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 string|array $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 content only if 'echo' argument is 0. 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 /* translators: 1: "type => link", 2: "taxonomy => link_category" */ 359 sprintf( 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 $r = wp_parse_args( $args, $defaults ); 369 $option_none_value = $r['option_none_value']; 370 371 if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) { 372 $r['pad_counts'] = true; 373 } 374 375 $tab_index = $r['tab_index']; 376 377 $tab_index_attribute = ''; 378 if ( (int) $tab_index > 0 ) { 379 $tab_index_attribute = " tabindex=\"$tab_index\""; 380 } 381 382 // Avoid clashes with the 'name' param of get_terms(). 383 $get_terms_args = $r; 384 unset( $get_terms_args['name'] ); 385 $categories = get_terms( $r['taxonomy'], $get_terms_args ); 386 387 $name = esc_attr( $r['name'] ); 388 $class = esc_attr( $r['class'] ); 389 $id = $r['id'] ? esc_attr( $r['id'] ) : $name; 390 $required = $r['required'] ? 'required' : ''; 391 392 if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) { 393 $output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n"; 394 } else { 395 $output = ''; 396 } 397 if ( empty( $categories ) && ! $r['hide_if_empty'] && ! empty( $r['show_option_none'] ) ) { 398 399 /** 400 * Filters a taxonomy drop-down display element. 401 * 402 * A variety of taxonomy drop-down display elements can be modified 403 * just prior to display via this filter. Filterable arguments include 404 * 'show_option_none', 'show_option_all', and various forms of the 405 * term name. 406 * 407 * @since 1.2.0 408 * 409 * @see wp_dropdown_categories() 410 * 411 * @param string $element Category name. 412 * @param WP_Term|null $category The category object, or null if there's no corresponding category. 413 */ 414 $show_option_none = apply_filters( 'list_cats', $r['show_option_none'], null ); 415 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n"; 416 } 417 418 if ( ! empty( $categories ) ) { 419 420 if ( $r['show_option_all'] ) { 421 422 /** This filter is documented in wp-includes/category-template.php */ 423 $show_option_all = apply_filters( 'list_cats', $r['show_option_all'], null ); 424 $selected = ( '0' === strval( $r['selected'] ) ) ? " selected='selected'" : ''; 425 $output .= "\t<option value='0'$selected>$show_option_all</option>\n"; 426 } 427 428 if ( $r['show_option_none'] ) { 429 430 /** This filter is documented in wp-includes/category-template.php */ 431 $show_option_none = apply_filters( 'list_cats', $r['show_option_none'], null ); 432 $selected = selected( $option_none_value, $r['selected'], false ); 433 $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n"; 434 } 435 436 if ( $r['hierarchical'] ) { 437 $depth = $r['depth']; // Walk the full depth. 438 } else { 439 $depth = -1; // Flat. 440 } 441 $output .= walk_category_dropdown_tree( $categories, $depth, $r ); 442 } 443 444 if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) { 445 $output .= "</select>\n"; 446 } 447 /** 448 * Filters the taxonomy drop-down output. 449 * 450 * @since 2.1.0 451 * 452 * @param string $output HTML output. 453 * @param array $r Arguments used to build the drop-down. 454 */ 455 $output = apply_filters( 'wp_dropdown_cats', $output, $r ); 456 457 if ( $r['echo'] ) { 458 echo $output; 459 } 460 return $output; 461 } 462 463 /** 464 * Display or retrieve the HTML list of categories. 465 * 466 * @since 2.1.0 467 * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category` argument was modified to 468 * optionally accept an array of values. 469 * 470 * @param string|array $args { 471 * Array of optional arguments. 472 * 473 * @type int $child_of Term ID to retrieve child terms of. See get_terms(). Default 0. 474 * @type int|array $current_category ID of category, or array of IDs of categories, that should get the 475 * 'current-cat' class. Default 0. 476 * @type int $depth Category depth. Used for tab indentation. Default 0. 477 * @type bool|int $echo True to echo markup, false to return it. Default 1. 478 * @type array|string $exclude Array or comma/space-separated string of term IDs to exclude. 479 * If `$hierarchical` is true, descendants of `$exclude` terms will also 480 * be excluded; see `$exclude_tree`. See get_terms(). 481 * Default empty string. 482 * @type array|string $exclude_tree Array or comma/space-separated string of term IDs to exclude, along 483 * with their descendants. See get_terms(). Default empty string. 484 * @type string $feed Text to use for the feed link. Default 'Feed for all posts filed 485 * under [cat name]'. 486 * @type string $feed_image URL of an image to use for the feed link. Default empty string. 487 * @type string $feed_type Feed type. Used to build feed link. See get_term_feed_link(). 488 * Default empty string (default feed). 489 * @type bool|int $hide_empty Whether to hide categories that don't have any posts attached to them. 490 * Default 1. 491 * @type bool $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in 492 * the list. Default false (title will always be shown). 493 * @type bool $hierarchical Whether to include terms that have non-empty descendants. 494 * See get_terms(). Default true. 495 * @type string $order Which direction to order categories. Accepts 'ASC' or 'DESC'. 496 * Default 'ASC'. 497 * @type string $orderby The column to use for ordering categories. Default 'name'. 498 * @type string $separator Separator between links. Default '<br />'. 499 * @type bool|int $show_count Whether to show how many posts are in the category. Default 0. 500 * @type string $show_option_all Text to display for showing all categories. Default empty string. 501 * @type string $show_option_none Text to display for the 'no categories' option. 502 * Default 'No categories'. 503 * @type string $style The style used to display the categories list. If 'list', categories 504 * will be output as an unordered list. If left empty or another value, 505 * categories will be output separated by `<br>` tags. Default 'list'. 506 * @type string $taxonomy Taxonomy name. Default 'category'. 507 * @type string $title_li Text to use for the list title `<li>` element. Pass an empty string 508 * to disable. Default 'Categories'. 509 * @type bool|int $use_desc_for_title Whether to use the category description as the title attribute. 510 * Default 1. 511 * } 512 * @return false|string HTML content only if 'echo' argument is 0. 513 */ 514 function wp_list_categories( $args = '' ) { 515 $defaults = array( 516 'child_of' => 0, 517 'current_category' => 0, 518 'depth' => 0, 519 'echo' => 1, 520 'exclude' => '', 521 'exclude_tree' => '', 522 'feed' => '', 523 'feed_image' => '', 524 'feed_type' => '', 525 'hide_empty' => 1, 526 'hide_title_if_empty' => false, 527 'hierarchical' => true, 528 'order' => 'ASC', 529 'orderby' => 'name', 530 'separator' => '<br />', 531 'show_count' => 0, 532 'show_option_all' => '', 533 'show_option_none' => __( 'No categories' ), 534 'style' => 'list', 535 'taxonomy' => 'category', 536 'title_li' => __( 'Categories' ), 537 'use_desc_for_title' => 1, 538 ); 539 540 $r = wp_parse_args( $args, $defaults ); 541 542 if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) { 543 $r['pad_counts'] = true; 544 } 545 546 // Descendants of exclusions should be excluded too. 547 if ( true == $r['hierarchical'] ) { 548 $exclude_tree = array(); 549 550 if ( $r['exclude_tree'] ) { 551 $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude_tree'] ) ); 552 } 553 554 if ( $r['exclude'] ) { 555 $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude'] ) ); 556 } 557 558 $r['exclude_tree'] = $exclude_tree; 559 $r['exclude'] = ''; 560 } 561 562 if ( ! isset( $r['class'] ) ) { 563 $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy']; 564 } 565 566 if ( ! taxonomy_exists( $r['taxonomy'] ) ) { 567 return false; 568 } 569 570 $show_option_all = $r['show_option_all']; 571 $show_option_none = $r['show_option_none']; 572 573 $categories = get_categories( $r ); 574 575 $output = ''; 576 if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) { 577 $output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>'; 578 } 579 if ( empty( $categories ) ) { 580 if ( ! empty( $show_option_none ) ) { 581 if ( 'list' == $r['style'] ) { 582 $output .= '<li class="cat-item-none">' . $show_option_none . '</li>'; 583 } else { 584 $output .= $show_option_none; 585 } 586 } 587 } else { 588 if ( ! empty( $show_option_all ) ) { 589 590 $posts_page = ''; 591 592 // For taxonomies that belong only to custom post types, point to a valid archive. 593 $taxonomy_object = get_taxonomy( $r['taxonomy'] ); 594 if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) { 595 foreach ( $taxonomy_object->object_type as $object_type ) { 596 $_object_type = get_post_type_object( $object_type ); 597 598 // Grab the first one. 599 if ( ! empty( $_object_type->has_archive ) ) { 600 $posts_page = get_post_type_archive_link( $object_type ); 601 break; 602 } 603 } 604 } 605 606 // Fallback for the 'All' link is the posts page. 607 if ( ! $posts_page ) { 608 if ( 'page' == get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) { 609 $posts_page = get_permalink( get_option( 'page_for_posts' ) ); 610 } else { 611 $posts_page = home_url( '/' ); 612 } 613 } 614 615 $posts_page = esc_url( $posts_page ); 616 if ( 'list' == $r['style'] ) { 617 $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>"; 618 } else { 619 $output .= "<a href='$posts_page'>$show_option_all</a>"; 620 } 621 } 622 623 if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) { 624 $current_term_object = get_queried_object(); 625 if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) { 626 $r['current_category'] = get_queried_object_id(); 627 } 628 } 629 630 if ( $r['hierarchical'] ) { 631 $depth = $r['depth']; 632 } else { 633 $depth = -1; // Flat. 634 } 635 $output .= walk_category_tree( $categories, $depth, $r ); 636 } 637 638 if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) { 639 $output .= '</ul></li>'; 640 } 641 642 /** 643 * Filters the HTML output of a taxonomy list. 644 * 645 * @since 2.1.0 646 * 647 * @param string $output HTML output. 648 * @param array $args An array of taxonomy-listing arguments. 649 */ 650 $html = apply_filters( 'wp_list_categories', $output, $args ); 651 652 if ( $r['echo'] ) { 653 echo $html; 654 } else { 655 return $html; 656 } 657 } 658 659 /** 660 * Displays a tag cloud. 661 * 662 * @since 2.3.0 663 * @since 4.8.0 Added the `show_count` argument. 664 * 665 * @param array|string $args { 666 * Optional. Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud() 667 * and get_terms() for the full lists of arguments that can be passed in `$args`. 668 * 669 * @type int $number The number of tags to display. Accepts any positive integer 670 * or zero to return all. Default 0 (all tags). 671 * @type string $link Whether to display term editing links or term permalinks. 672 * Accepts 'edit' and 'view'. Default 'view'. 673 * @type string $post_type The post type. Used to highlight the proper post type menu 674 * on the linked edit page. Defaults to the first post type 675 * associated with the taxonomy. 676 * @type bool $echo Whether or not to echo the return value. Default true. 677 * } 678 * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument. 679 * Otherwise, this function outputs the tag cloud. 680 */ 681 function wp_tag_cloud( $args = '' ) { 682 $defaults = array( 683 'smallest' => 8, 684 'largest' => 22, 685 'unit' => 'pt', 686 'number' => 45, 687 'format' => 'flat', 688 'separator' => "\n", 689 'orderby' => 'name', 690 'order' => 'ASC', 691 'exclude' => '', 692 'include' => '', 693 'link' => 'view', 694 'taxonomy' => 'post_tag', 695 'post_type' => '', 696 'echo' => true, 697 'show_count' => 0, 698 ); 699 $args = wp_parse_args( $args, $defaults ); 700 701 $tags = get_terms( 702 $args['taxonomy'], 703 array_merge( 704 $args, 705 array( 706 'orderby' => 'count', 707 'order' => 'DESC', 708 ) 709 ) 710 ); // Always query top tags 711 712 if ( empty( $tags ) || is_wp_error( $tags ) ) { 713 return; 714 } 715 716 foreach ( $tags as $key => $tag ) { 717 if ( 'edit' == $args['link'] ) { 718 $link = get_edit_term_link( $tag->term_id, $tag->taxonomy, $args['post_type'] ); 719 } else { 720 $link = get_term_link( intval( $tag->term_id ), $tag->taxonomy ); 721 } 722 if ( is_wp_error( $link ) ) { 723 return; 724 } 725 726 $tags[ $key ]->link = $link; 727 $tags[ $key ]->id = $tag->term_id; 728 } 729 730 $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args 731 732 /** 733 * Filters the tag cloud output. 734 * 735 * @since 2.3.0 736 * 737 * @param string $return HTML output of the tag cloud. 738 * @param array $args An array of tag cloud arguments. 739 */ 740 $return = apply_filters( 'wp_tag_cloud', $return, $args ); 741 742 if ( 'array' == $args['format'] || empty( $args['echo'] ) ) { 743 return $return; 744 } 745 746 echo $return; 747 } 748 749 /** 750 * Default topic count scaling for tag links. 751 * 752 * @since 2.9.0 753 * 754 * @param int $count Number of posts with that tag. 755 * @return int Scaled count. 756 */ 757 function default_topic_count_scale( $count ) { 758 return round( log10( $count + 1 ) * 100 ); 759 } 760 761 /** 762 * Generates a tag cloud (heatmap) from provided data. 763 * 764 * @todo Complete functionality. 765 * @since 2.3.0 766 * @since 4.8.0 Added the `show_count` argument. 767 * 768 * @param WP_Term[] $tags Array of WP_Term objects to generate the tag cloud for. 769 * @param string|array $args { 770 * Optional. Array or string of arguments for generating a tag cloud. 771 * 772 * @type int $smallest Smallest font size used to display tags. Paired 773 * with the value of `$unit`, to determine CSS text 774 * size unit. Default 8 (pt). 775 * @type int $largest Largest font size used to display tags. Paired 776 * with the value of `$unit`, to determine CSS text 777 * size unit. Default 22 (pt). 778 * @type string $unit CSS text size unit to use with the `$smallest` 779 * and `$largest` values. Accepts any valid CSS text 780 * size unit. Default 'pt'. 781 * @type int $number The number of tags to return. Accepts any 782 * positive integer or zero to return all. 783 * Default 0. 784 * @type string $format Format to display the tag cloud in. Accepts 'flat' 785 * (tags separated with spaces), 'list' (tags displayed 786 * in an unordered list), or 'array' (returns an array). 787 * Default 'flat'. 788 * @type string $separator HTML or text to separate the tags. Default "\n" (newline). 789 * @type string $orderby Value to order tags by. Accepts 'name' or 'count'. 790 * Default 'name'. The {@see 'tag_cloud_sort'} filter 791 * can also affect how tags are sorted. 792 * @type string $order How to order the tags. Accepts 'ASC' (ascending), 793 * 'DESC' (descending), or 'RAND' (random). Default 'ASC'. 794 * @type int|bool $filter Whether to enable filtering of the final output 795 * via {@see 'wp_generate_tag_cloud'}. Default 1|true. 796 * @type string $topic_count_text Nooped plural text from _n_noop() to supply to 797 * tag counts. Default null. 798 * @type callable $topic_count_text_callback Callback used to generate nooped plural text for 799 * tag counts based on the count. Default null. 800 * @type callable $topic_count_scale_callback Callback used to determine the tag count scaling 801 * value. Default default_topic_count_scale(). 802 * @type bool|int $show_count Whether to display the tag counts. Default 0. Accepts 803 * 0, 1, or their bool equivalents. 804 * } 805 * @return string|array Tag cloud as a string or an array, depending on 'format' argument. 806 */ 807 function wp_generate_tag_cloud( $tags, $args = '' ) { 808 $defaults = array( 809 'smallest' => 8, 810 'largest' => 22, 811 'unit' => 'pt', 812 'number' => 0, 813 'format' => 'flat', 814 'separator' => "\n", 815 'orderby' => 'name', 816 'order' => 'ASC', 817 'topic_count_text' => null, 818 'topic_count_text_callback' => null, 819 'topic_count_scale_callback' => 'default_topic_count_scale', 820 'filter' => 1, 821 'show_count' => 0, 822 ); 823 824 $args = wp_parse_args( $args, $defaults ); 825 826 $return = ( 'array' === $args['format'] ) ? array() : ''; 827 828 if ( empty( $tags ) ) { 829 return $return; 830 } 831 832 // Juggle topic counts. 833 if ( isset( $args['topic_count_text'] ) ) { 834 // First look for nooped plural support via topic_count_text. 835 $translate_nooped_plural = $args['topic_count_text']; 836 } elseif ( ! empty( $args['topic_count_text_callback'] ) ) { 837 // Look for the alternative callback style. Ignore the previous default. 838 if ( $args['topic_count_text_callback'] === 'default_topic_count_text' ) { 839 $translate_nooped_plural = _n_noop( '%s item', '%s items' ); 840 } else { 841 $translate_nooped_plural = false; 842 } 843 } elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) { 844 // If no callback exists, look for the old-style single_text and multiple_text arguments. 845 // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingle,WordPress.WP.I18n.NonSingularStringLiteralPlural 846 $translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] ); 847 } else { 848 // This is the default for when no callback, plural, or argument is passed in. 849 $translate_nooped_plural = _n_noop( '%s item', '%s items' ); 850 } 851 852 /** 853 * Filters how the items in a tag cloud are sorted. 854 * 855 * @since 2.8.0 856 * 857 * @param WP_Term[] $tags Ordered array of terms. 858 * @param array $args An array of tag cloud arguments. 859 */ 860 $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args ); 861 if ( empty( $tags_sorted ) ) { 862 return $return; 863 } 864 865 if ( $tags_sorted !== $tags ) { 866 $tags = $tags_sorted; 867 unset( $tags_sorted ); 868 } else { 869 if ( 'RAND' === $args['order'] ) { 870 shuffle( $tags ); 871 } else { 872 // SQL cannot save you; this is a second (potentially different) sort on a subset of data. 873 if ( 'name' === $args['orderby'] ) { 874 uasort( $tags, '_wp_object_name_sort_cb' ); 875 } else { 876 uasort( $tags, '_wp_object_count_sort_cb' ); 877 } 878 879 if ( 'DESC' === $args['order'] ) { 880 $tags = array_reverse( $tags, true ); 881 } 882 } 883 } 884 885 if ( $args['number'] > 0 ) { 886 $tags = array_slice( $tags, 0, $args['number'] ); 887 } 888 889 $counts = array(); 890 $real_counts = array(); // For the alt tag 891 foreach ( (array) $tags as $key => $tag ) { 892 $real_counts[ $key ] = $tag->count; 893 $counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count ); 894 } 895 896 $min_count = min( $counts ); 897 $spread = max( $counts ) - $min_count; 898 if ( $spread <= 0 ) { 899 $spread = 1; 900 } 901 $font_spread = $args['largest'] - $args['smallest']; 902 if ( $font_spread < 0 ) { 903 $font_spread = 1; 904 } 905 $font_step = $font_spread / $spread; 906 907 $aria_label = false; 908 /* 909 * Determine whether to output an 'aria-label' attribute with the tag name and count. 910 * When tags have a different font size, they visually convey an important information 911 * that should be available to assistive technologies too. On the other hand, sometimes 912 * themes set up the Tag Cloud to display all tags with the same font size (setting 913 * the 'smallest' and 'largest' arguments to the same value). 914 * In order to always serve the same content to all users, the 'aria-label' gets printed out: 915 * - when tags have a different size 916 * - when the tag count is displayed (for example when users check the checkbox in the 917 * Tag Cloud widget), regardless of the tags font size 918 */ 919 if ( $args['show_count'] || 0 !== $font_spread ) { 920 $aria_label = true; 921 } 922 923 // Assemble the data that will be used to generate the tag cloud markup. 924 $tags_data = array(); 925 foreach ( $tags as $key => $tag ) { 926 $tag_id = isset( $tag->id ) ? $tag->id : $key; 927 928 $count = $counts[ $key ]; 929 $real_count = $real_counts[ $key ]; 930 931 if ( $translate_nooped_plural ) { 932 $formatted_count = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) ); 933 } else { 934 $formatted_count = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args ); 935 } 936 937 $tags_data[] = array( 938 'id' => $tag_id, 939 'url' => '#' != $tag->link ? $tag->link : '#', 940 'role' => '#' != $tag->link ? '' : ' role="button"', 941 'name' => $tag->name, 942 'formatted_count' => $formatted_count, 943 'slug' => $tag->slug, 944 'real_count' => $real_count, 945 'class' => 'tag-cloud-link tag-link-' . $tag_id, 946 'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step, 947 'aria_label' => $aria_label ? sprintf( ' aria-label="%1$s (%2$s)"', esc_attr( $tag->name ), esc_attr( $formatted_count ) ) : '', 948 'show_count' => $args['show_count'] ? '<span class="tag-link-count"> (' . $real_count . ')</span>' : '', 949 ); 950 } 951 952 /** 953 * Filters the data used to generate the tag cloud. 954 * 955 * @since 4.3.0 956 * 957 * @param array $tags_data An array of term data for term used to generate the tag cloud. 958 */ 959 $tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data ); 960 961 $a = array(); 962 963 // Generate the output links array. 964 foreach ( $tags_data as $key => $tag_data ) { 965 $class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 ); 966 $a[] = sprintf( 967 '<a href="%1$s"%2$s class="%3$s" style="font-size: %4$s;"%5$s>%6$s%7$s</a>', 968 esc_url( $tag_data['url'] ), 969 $tag_data['role'], 970 esc_attr( $class ), 971 esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ), 972 $tag_data['aria_label'], 973 esc_html( $tag_data['name'] ), 974 $tag_data['show_count'] 975 ); 976 } 977 978 switch ( $args['format'] ) { 979 case 'array': 980 $return =& $a; 981 break; 982 case 'list': 983 /* 984 * Force role="list", as some browsers (sic: Safari 10) don't expose to assistive 985 * technologies the default role when the list is styled with `list-style: none`. 986 * Note: this is redundant but doesn't harm. 987 */ 988 $return = "<ul class='wp-tag-cloud' role='list'>\n\t<li>"; 989 $return .= join( "</li>\n\t<li>", $a ); 990 $return .= "</li>\n</ul>\n"; 991 break; 992 default: 993 $return = join( $args['separator'], $a ); 994 break; 995 } 996 997 if ( $args['filter'] ) { 998 /** 999 * Filters the generated output of a tag cloud. 1000 * 1001 * The filter is only evaluated if a true value is passed 1002 * to the $filter argument in wp_generate_tag_cloud(). 1003 * 1004 * @since 2.3.0 1005 * 1006 * @see wp_generate_tag_cloud() 1007 * 1008 * @param array|string $return String containing the generated HTML tag cloud output 1009 * or an array of tag links if the 'format' argument 1010 * equals 'array'. 1011 * @param WP_Term[] $tags An array of terms used in the tag cloud. 1012 * @param array $args An array of wp_generate_tag_cloud() arguments. 1013 */ 1014 return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args ); 1015 } else { 1016 return $return; 1017 } 1018 } 1019 1020 /** 1021 * Serves as a callback for comparing objects based on name. 1022 * 1023 * Used with `uasort()`. 1024 * 1025 * @since 3.1.0 1026 * @access private 1027 * 1028 * @param object $a The first object to compare. 1029 * @param object $b The second object to compare. 1030 * @return int Negative number if `$a->name` is less than `$b->name`, zero if they are equal, 1031 * or greater than zero if `$a->name` is greater than `$b->name`. 1032 */ 1033 function _wp_object_name_sort_cb( $a, $b ) { 1034 return strnatcasecmp( $a->name, $b->name ); 1035 } 1036 1037 /** 1038 * Serves as a callback for comparing objects based on count. 1039 * 1040 * Used with `uasort()`. 1041 * 1042 * @since 3.1.0 1043 * @access private 1044 * 1045 * @param object $a The first object to compare. 1046 * @param object $b The second object to compare. 1047 * @return bool Whether the count value for `$a` is greater than the count value for `$b`. 1048 */ 1049 function _wp_object_count_sort_cb( $a, $b ) { 1050 return ( $a->count > $b->count ); 1051 } 1052 1053 // 1054 // Helper functions 1055 // 1056 1057 /** 1058 * Retrieve HTML list content for category list. 1059 * 1060 * @uses Walker_Category to create HTML list content. 1061 * @since 2.1.0 1062 * @see Walker_Category::walk() for parameters and return description. 1063 * @return string 1064 */ 1065 function walk_category_tree() { 1066 $args = func_get_args(); 1067 // the user's options are the third parameter 1068 if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) { 1069 $walker = new Walker_Category; 1070 } else { 1071 $walker = $args[2]['walker']; 1072 } 1073 return call_user_func_array( array( $walker, 'walk' ), $args ); 1074 } 1075 1076 /** 1077 * Retrieve HTML dropdown (select) content for category list. 1078 * 1079 * @uses Walker_CategoryDropdown to create HTML dropdown content. 1080 * @since 2.1.0 1081 * @see Walker_CategoryDropdown::walk() for parameters and return description. 1082 * @return string 1083 */ 1084 function walk_category_dropdown_tree() { 1085 $args = func_get_args(); 1086 // the user's options are the third parameter 1087 if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) { 1088 $walker = new Walker_CategoryDropdown; 1089 } else { 1090 $walker = $args[2]['walker']; 1091 } 1092 return call_user_func_array( array( $walker, 'walk' ), $args ); 1093 } 1094 1095 // 1096 // Tags 1097 // 1098 1099 /** 1100 * Retrieve the link to the tag. 1101 * 1102 * @since 2.3.0 1103 * @see get_term_link() 1104 * 1105 * @param int|object $tag Tag ID or object. 1106 * @return string Link on success, empty string if tag does not exist. 1107 */ 1108 function get_tag_link( $tag ) { 1109 return get_category_link( $tag ); 1110 } 1111 1112 /** 1113 * Retrieve the tags for a post. 1114 * 1115 * @since 2.3.0 1116 * 1117 * @param int $id Post ID. 1118 * @return array|false|WP_Error Array of tag objects on success, false on failure. 1119 */ 1120 function get_the_tags( $id = 0 ) { 1121 1122 /** 1123 * Filters the array of tags for the given post. 1124 * 1125 * @since 2.3.0 1126 * 1127 * @see get_the_terms() 1128 * 1129 * @param WP_Term[] $terms An array of tags for the given post. 1130 */ 1131 return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) ); 1132 } 1133 1134 /** 1135 * Retrieve the tags for a post formatted as a string. 1136 * 1137 * @since 2.3.0 1138 * 1139 * @param string $before Optional. Before tags. 1140 * @param string $sep Optional. Between tags. 1141 * @param string $after Optional. After tags. 1142 * @param int $id Optional. Post ID. Defaults to the current post. 1143 * @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure. 1144 */ 1145 function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) { 1146 1147 /** 1148 * Filters the tags list for a given post. 1149 * 1150 * @since 2.3.0 1151 * 1152 * @param string $tag_list List of tags. 1153 * @param string $before String to use before tags. 1154 * @param string $sep String to use between the tags. 1155 * @param string $after String to use after tags. 1156 * @param int $id Post ID. 1157 */ 1158 return apply_filters( 'the_tags', get_the_term_list( $id, 'post_tag', $before, $sep, $after ), $before, $sep, $after, $id ); 1159 } 1160 1161 /** 1162 * Retrieve the tags for a post. 1163 * 1164 * @since 2.3.0 1165 * 1166 * @param string $before Optional. Before list. 1167 * @param string $sep Optional. Separate items using this. 1168 * @param string $after Optional. After list. 1169 */ 1170 function the_tags( $before = null, $sep = ', ', $after = '' ) { 1171 if ( null === $before ) { 1172 $before = __( 'Tags: ' ); 1173 } 1174 1175 $the_tags = get_the_tag_list( $before, $sep, $after ); 1176 1177 if ( ! is_wp_error( $the_tags ) ) { 1178 echo $the_tags; 1179 } 1180 } 1181 1182 /** 1183 * Retrieve tag description. 1184 * 1185 * @since 2.8.0 1186 * 1187 * @param int $tag Optional. Tag ID. Will use global tag ID by default. 1188 * @return string Tag description, available. 1189 */ 1190 function tag_description( $tag = 0 ) { 1191 return term_description( $tag ); 1192 } 1193 1194 /** 1195 * Retrieve term description. 1196 * 1197 * @since 2.8.0 1198 * @since 4.9.2 The `$taxonomy` parameter was deprecated. 1199 * 1200 * @param int $term Optional. Term ID. Will use global term ID by default. 1201 * @param null $deprecated Deprecated argument. 1202 * @return string Term description, available. 1203 */ 1204 function term_description( $term = 0, $deprecated = null ) { 1205 if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) { 1206 $term = get_queried_object(); 1207 if ( $term ) { 1208 $term = $term->term_id; 1209 } 1210 } 1211 $description = get_term_field( 'description', $term ); 1212 return is_wp_error( $description ) ? '' : $description; 1213 } 1214 1215 /** 1216 * Retrieve the terms of the taxonomy that are attached to the post. 1217 * 1218 * @since 2.5.0 1219 * 1220 * @param int|WP_Post $post Post ID or object. 1221 * @param string $taxonomy Taxonomy name. 1222 * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms 1223 * or the post does not exist, WP_Error on failure. 1224 */ 1225 function get_the_terms( $post, $taxonomy ) { 1226 if ( ! $post = get_post( $post ) ) { 1227 return false; 1228 } 1229 1230 $terms = get_object_term_cache( $post->ID, $taxonomy ); 1231 if ( false === $terms ) { 1232 $terms = wp_get_object_terms( $post->ID, $taxonomy ); 1233 if ( ! is_wp_error( $terms ) ) { 1234 $term_ids = wp_list_pluck( $terms, 'term_id' ); 1235 wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' ); 1236 } 1237 } 1238 1239 /** 1240 * Filters the list of terms attached to the given post. 1241 * 1242 * @since 3.1.0 1243 * 1244 * @param WP_Term[]|WP_Error $terms Array of attached terms, or WP_Error on failure. 1245 * @param int $post_id Post ID. 1246 * @param string $taxonomy Name of the taxonomy. 1247 */ 1248 $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy ); 1249 1250 if ( empty( $terms ) ) { 1251 return false; 1252 } 1253 1254 return $terms; 1255 } 1256 1257 /** 1258 * Retrieve a post's terms as a list with specified format. 1259 * 1260 * @since 2.5.0 1261 * 1262 * @param int $id Post ID. 1263 * @param string $taxonomy Taxonomy name. 1264 * @param string $before Optional. Before list. 1265 * @param string $sep Optional. Separate items using this. 1266 * @param string $after Optional. After list. 1267 * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure. 1268 */ 1269 function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = '' ) { 1270 $terms = get_the_terms( $id, $taxonomy ); 1271 1272 if ( is_wp_error( $terms ) ) { 1273 return $terms; 1274 } 1275 1276 if ( empty( $terms ) ) { 1277 return false; 1278 } 1279 1280 $links = array(); 1281 1282 foreach ( $terms as $term ) { 1283 $link = get_term_link( $term, $taxonomy ); 1284 if ( is_wp_error( $link ) ) { 1285 return $link; 1286 } 1287 $links[] = '<a href="' . esc_url( $link ) . '" rel="tag">' . $term->name . '</a>'; 1288 } 1289 1290 /** 1291 * Filters the term links for a given taxonomy. 1292 * 1293 * The dynamic portion of the filter name, `$taxonomy`, refers 1294 * to the taxonomy slug. 1295 * 1296 * @since 2.5.0 1297 * 1298 * @param string[] $links An array of term links. 1299 */ 1300 $term_links = apply_filters( "term_links-{$taxonomy}", $links ); 1301 1302 return $before . join( $sep, $term_links ) . $after; 1303 } 1304 1305 /** 1306 * Retrieve term parents with separator. 1307 * 1308 * @since 4.8.0 1309 * 1310 * @param int $term_id Term ID. 1311 * @param string $taxonomy Taxonomy name. 1312 * @param string|array $args { 1313 * Array of optional arguments. 1314 * 1315 * @type string $format Use term names or slugs for display. Accepts 'name' or 'slug'. 1316 * Default 'name'. 1317 * @type string $separator Separator for between the terms. Default '/'. 1318 * @type bool $link Whether to format as a link. Default true. 1319 * @type bool $inclusive Include the term to get the parents for. Default true. 1320 * } 1321 * @return string|WP_Error A list of term parents on success, WP_Error or empty string on failure. 1322 */ 1323 function get_term_parents_list( $term_id, $taxonomy, $args = array() ) { 1324 $list = ''; 1325 $term = get_term( $term_id, $taxonomy ); 1326 1327 if ( is_wp_error( $term ) ) { 1328 return $term; 1329 } 1330 1331 if ( ! $term ) { 1332 return $list; 1333 } 1334 1335 $term_id = $term->term_id; 1336 1337 $defaults = array( 1338 'format' => 'name', 1339 'separator' => '/', 1340 'link' => true, 1341 'inclusive' => true, 1342 ); 1343 1344 $args = wp_parse_args( $args, $defaults ); 1345 1346 foreach ( array( 'link', 'inclusive' ) as $bool ) { 1347 $args[ $bool ] = wp_validate_boolean( $args[ $bool ] ); 1348 } 1349 1350 $parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' ); 1351 1352 if ( $args['inclusive'] ) { 1353 array_unshift( $parents, $term_id ); 1354 } 1355 1356 foreach ( array_reverse( $parents ) as $term_id ) { 1357 $parent = get_term( $term_id, $taxonomy ); 1358 $name = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name; 1359 1360 if ( $args['link'] ) { 1361 $list .= '<a href="' . esc_url( get_term_link( $parent->term_id, $taxonomy ) ) . '">' . $name . '</a>' . $args['separator']; 1362 } else { 1363 $list .= $name . $args['separator']; 1364 } 1365 } 1366 1367 return $list; 1368 } 1369 1370 /** 1371 * Display the terms in a list. 1372 * 1373 * @since 2.5.0 1374 * 1375 * @param int $id Post ID. 1376 * @param string $taxonomy Taxonomy name. 1377 * @param string $before Optional. Before list. 1378 * @param string $sep Optional. Separate items using this. 1379 * @param string $after Optional. After list. 1380 * @return false|void False on WordPress error. 1381 */ 1382 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) { 1383 $term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after ); 1384 1385 if ( is_wp_error( $term_list ) ) { 1386 return false; 1387 } 1388 1389 /** 1390 * Filters the list of terms to display. 1391 * 1392 * @since 2.9.0 1393 * 1394 * @param string $term_list List of terms to display. 1395 * @param string $taxonomy The taxonomy name. 1396 * @param string $before String to use before the terms. 1397 * @param string $sep String to use between the terms. 1398 * @param string $after String to use after the terms. 1399 */ 1400 echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after ); 1401 } 1402 1403 /** 1404 * Check if the current post has any of given category. 1405 * 1406 * @since 3.1.0 1407 * 1408 * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for. 1409 * @param int|object $post Optional. Post to check instead of the current post. 1410 * @return bool True if the current post has any of the given categories (or any category, if no category specified). 1411 */ 1412 function has_category( $category = '', $post = null ) { 1413 return has_term( $category, 'category', $post ); 1414 } 1415 1416 /** 1417 * Checks if the current post has any of given tags. 1418 * 1419 * The given tags are checked against the post's tags' term_ids, names and slugs. 1420 * Tags given as integers will only be checked against the post's tags' term_ids. 1421 * If no tags are given, determines if post has any tags. 1422 * 1423 * 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) 1424 * Prior to v2.7, this function could only be used in the WordPress Loop. 1425 * As of 2.7, the function can be used anywhere if it is provided a post ID or post object. 1426 * 1427 * For more information on this and similar theme functions, check out 1428 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 1429 * Conditional Tags} article in the Theme Developer Handbook. 1430 * 1431 * @since 2.6.0 1432 * 1433 * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for. 1434 * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0) 1435 * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). 1436 */ 1437 function has_tag( $tag = '', $post = null ) { 1438 return has_term( $tag, 'post_tag', $post ); 1439 } 1440 1441 /** 1442 * Check if the current post has any of given terms. 1443 * 1444 * The given terms are checked against the post's terms' term_ids, names and slugs. 1445 * Terms given as integers will only be checked against the post's terms' term_ids. 1446 * If no terms are given, determines if post has any terms. 1447 * 1448 * @since 3.1.0 1449 * 1450 * @param string|int|array $term Optional. The term name/term_id/slug or array of them to check for. 1451 * @param string $taxonomy Taxonomy name 1452 * @param int|object $post Optional. Post to check instead of the current post. 1453 * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). 1454 */ 1455 function has_term( $term = '', $taxonomy = '', $post = null ) { 1456 $post = get_post( $post ); 1457 1458 if ( ! $post ) { 1459 return false; 1460 } 1461 1462 $r = is_object_in_term( $post->ID, $taxonomy, $term ); 1463 if ( is_wp_error( $r ) ) { 1464 return false; 1465 } 1466 1467 return $r; 1468 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Mon Jun 17 08:20:02 2019 | Cross-referenced by PHPXref 0.7 |