wp-includes/category-template.php

   1 <?php
   2 /**
   3  * Category Template Tags and API.
   4  *
   5  * @package WordPress
   6  * @subpackage Template
   7  */
   8
   9 /**
  10  * Retrieve category link URL.
  11  *
  12  * @since 1.0.0
  13  * @uses apply_filters() Calls 'category_link' filter on category link and category ID.
  14  *
  15  * @param int $category_id Category ID.
  16  * @return string
  17  */
  18 function get_category_link( $category_id ) {
  19         global $wp_rewrite;
  20         $catlink = $wp_rewrite->get_category_permastruct();
  21
  22         if ( empty( $catlink ) ) {
  23                 $file = get_option( 'home' ) . '/';
  24                 $catlink = $file . '?cat=' . $category_id;
  25         } else {
  26                 $category = &get_category( $category_id );
  27                 if ( is_wp_error( $category ) )
  28                         return $category;
  29                 $category_nicename = $category->slug;
  30
  31                 if ( $category->parent == $category_id ) // recursive recursion
  32                         $category->parent = 0;
  33                 elseif ($category->parent != 0 )
  34                         $category_nicename = get_category_parents( $category->parent, false, '/', true ) . $category_nicename;
  35
  36                 $catlink = str_replace( '%category%', $category_nicename, $catlink );
  37                 $catlink = get_option( 'home' ) . user_trailingslashit( $catlink, 'category' );
  38         }
  39         return apply_filters( 'category_link', $catlink, $category_id );
  40 }
  41
  42 /**
  43  * Retrieve category parents with separator.
  44  *
  45  * @since 1.2.0
  46  *
  47  * @param int $id Category ID.
  48  * @param bool $link Optional, default is false. Whether to format with link.
  49  * @param string $separator Optional, default is '/'. How to separate categories.
  50  * @param bool $nicename Optional, default is false. Whether to use nice name for display.
  51  * @param array $visited Optional. Already linked to categories to prevent duplicates.
  52  * @return string
  53  */
  54 function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) {
  55         $chain = '';
  56         $parent = &get_category( $id );
  57         if ( is_wp_error( $parent ) )
  58                 return $parent;
  59
  60         if ( $nicename )
  61                 $name = $parent->slug;
  62         else
  63                 $name = $parent->cat_name;
  64
  65         if ( $parent->parent && ( $parent->parent != $parent->term_id ) && !in_array( $parent->parent, $visited ) ) {
  66                 $visited[] = $parent->parent;
  67                 $chain .= get_category_parents( $parent->parent, $link, $separator, $nicename, $visited );
  68         }
  69
  70         if ( $link )
  71                 $chain .= '<a href="' . get_category_link( $parent->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $parent->cat_name ) ) . '">'.$name.'</a>' . $separator;
  72         else
  73                 $chain .= $name.$separator;
  74         return $chain;
  75 }
  76
  77 /**
  78  * Retrieve post categories.
  79  *
  80  * @since 0.71
  81  * @uses $post
  82  *
  83  * @param int $id Optional, default to current post ID. The post ID.
  84  * @return array
  85  */
  86 function get_the_category( $id = false ) {
  87         global $post;
  88
  89         $id = (int) $id;
  90         if ( !$id )
  91                 $id = (int) $post->ID;
  92
  93         $categories = get_object_term_cache( $id, 'category' );
  94         if ( false === $categories ) {
  95                 $categories = wp_get_object_terms( $id, 'category' );
  96                 wp_cache_add($id, $categories, 'category_relationships');
  97         }
  98
  99         if ( !empty( $categories ) )
 100                 usort( $categories, '_usort_terms_by_name' );
 101         else
 102                 $categories = array();
 103
 104         foreach ( (array) array_keys( $categories ) as $key ) {
 105                 _make_cat_compat( $categories[$key] );
 106         }
 107
 108         return $categories;
 109 }
 110
 111 /**
 112  * Sort categories by name.
 113  *
 114  * Used by usort() as a callback, should not be used directly. Can actually be
 115  * used to sort any term object.
 116  *
 117  * @since 2.3.0
 118  * @access private
 119  *
 120  * @param object $a
 121  * @param object $b
 122  * @return int
 123  */
 124 function _usort_terms_by_name( $a, $b ) {
 125         return strcmp( $a->name, $b->name );
 126 }
 127
 128 /**
 129  * Sort categories by ID.
 130  *
 131  * Used by usort() as a callback, should not be used directly. Can actually be
 132  * used to sort any term object.
 133  *
 134  * @since 2.3.0
 135  * @access private
 136  *
 137  * @param object $a
 138  * @param object $b
 139  * @return int
 140  */
 141 function _usort_terms_by_ID( $a, $b ) {
 142         if ( $a->term_id > $b->term_id )
 143                 return 1;
 144         elseif ( $a->term_id < $b->term_id )
 145                 return -1;
 146         else
 147                 return 0;
 148 }
 149
 150 /**
 151  * Retrieve category name based on category ID.
 152  *
 153  * @since 0.71
 154  *
 155  * @param int $cat_ID Category ID.
 156  * @return string Category name.
 157  */
 158 function get_the_category_by_ID( $cat_ID ) {
 159         $cat_ID = (int) $cat_ID;
 160         $category = &get_category( $cat_ID );
 161         if ( is_wp_error( $category ) )
 162                 return $category;
 163         return $category->name;
 164 }
 165
 166 /**
 167  * Retrieve category list in either HTML list or custom format.
 168  *
 169  * @since 1.5.1
 170  *
 171  * @param string $separator Optional, default is empty string. Separator for between the categories.
 172  * @param string $parents Optional. How to display the parents.
 173  * @param int $post_id Optional. Post ID to retrieve categories.
 174  * @return string
 175  */
 176 function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
 177         global $wp_rewrite;
 178         $categories = get_the_category( $post_id );
 179         if ( empty( $categories ) )
 180                 return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
 181
 182         $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
 183
 184         $thelist = '';
 185         if ( '' == $separator ) {
 186                 $thelist .= '<ul class="post-categories">';
 187                 foreach ( $categories as $category ) {
 188                         $thelist .= "\n\t<li>";
 189                         switch ( strtolower( $parents ) ) {
 190                                 case 'multiple':
 191                                         if ( $category->parent )
 192                                                 $thelist .= get_category_parents( $category->parent, true, $separator );
 193                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>' . $category->name.'</a></li>';
 194                                         break;
 195                                 case 'single':
 196                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>';
 197                                         if ( $category->parent )
 198                                                 $thelist .= get_category_parents( $category->parent, false, $separator );
 199                                         $thelist .= $category->name.'</a></li>';
 200                                         break;
 201                                 case '':
 202                                 default:
 203                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>' . $category->cat_name.'</a></li>';
 204                         }
 205                 }
 206                 $thelist .= '</ul>';
 207         } else {
 208                 $i = 0;
 209                 foreach ( $categories as $category ) {
 210                         if ( 0 < $i )
 211                                 $thelist .= $separator . ' ';
 212                         switch ( strtolower( $parents ) ) {
 213                                 case 'multiple':
 214                                         if ( $category->parent )
 215                                                 $thelist .= get_category_parents( $category->parent, true, $separator );
 216                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>' . $category->cat_name.'</a>';
 217                                         break;
 218                                 case 'single':
 219                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>';
 220                                         if ( $category->parent )
 221                                                 $thelist .= get_category_parents( $category->parent, false, $separator );
 222                                         $thelist .= "$category->cat_name</a>";
 223                                         break;
 224                                 case '':
 225                                 default:
 226                                         $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . esc_attr( sprintf( __( "View all posts in %s" ), $category->name ) ) . '" ' . $rel . '>' . $category->name.'</a>';
 227                         }
 228                         ++$i;
 229                 }
 230         }
 231         return apply_filters( 'the_category', $thelist, $separator, $parents );
 232 }
 233
 234
 235 /**
 236  * Check if the current post in within any of the given categories.
 237  *
 238  * The given categories are checked against the post's categories' term_ids, names and slugs.
 239  * Categories given as integers will only be checked against the post's categories' term_ids.
 240  *
 241  * Prior to v2.5 of WordPress, category names were not supported.
 242  * Prior to v2.7, category slugs were not supported.
 243  * Prior to v2.7, only one category could be compared: in_category( $single_category ).
 244  * Prior to v2.7, this function could only be used in the WordPress Loop.
 245  * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
 246  *
 247  * @since 1.2.0
 248  *
 249  * @uses is_object_in_term()
 250  *
 251  * @param int|string|array $category. Category ID, name or slug, or array of said.
 252  * @param int|post object Optional.  Post to check instead of the current post. @since 2.7.0
 253  * @return bool True if the current post is in any of the given categories.
 254  */
 255 function in_category( $category, $_post = null ) {
 256         if ( empty( $category ) )
 257                 return false;
 258
 259         if ( $_post ) {
 260                 $_post = get_post( $_post );
 261         } else {
 262                 $_post =& $GLOBALS['post'];
 263         }
 264
 265         if ( !$_post )
 266                 return false;
 267
 268         $r = is_object_in_term( $_post->ID, 'category', $category );
 269         if ( is_wp_error( $r ) )
 270                 return false;
 271         return $r;
 272 }
 273
 274 /**
 275  * Display the category list for the post.
 276  *
 277  * @since 0.71
 278  *
 279  * @param string $separator Optional, default is empty string. Separator for between the categories.
 280  * @param string $parents Optional. How to display the parents.
 281  * @param int $post_id Optional. Post ID to retrieve categories.
 282  */
 283 function the_category( $separator = '', $parents='', $post_id = false ) {
 284         echo get_the_category_list( $separator, $parents, $post_id );
 285 }
 286
 287 /**
 288  * Retrieve category description.
 289  *
 290  * @since 1.0.0
 291  *
 292  * @param int $category Optional. Category ID. Will use global category ID by default.
 293  * @return string Category description, available.
 294  */
 295 function category_description( $category = 0 ) {
 296         return term_description( $category, 'category' );
 297 }
 298
 299 /**
 300  * Display or retrieve the HTML dropdown list of categories.
 301  *
 302  * The list of arguments is below:
 303  *     'show_option_all' (string) - Text to display for showing all categories.
 304  *     'show_option_none' (string) - Text to display for showing no categories.
 305  *     'orderby' (string) default is 'ID' - What column to use for ordering the
 306  * categories.
 307  *     'order' (string) default is 'ASC' - What direction to order categories.
 308  *     'show_last_update' (bool|int) default is 0 - See {@link get_categories()}
 309  *     'show_count' (bool|int) default is 0 - Whether to show how many posts are
 310  * in the category.
 311  *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that
 312  * don't have any posts attached to them.
 313  *     'child_of' (int) default is 0 - See {@link get_categories()}.
 314  *     'exclude' (string) - See {@link get_categories()}.
 315  *     'echo' (bool|int) default is 1 - Whether to display or retrieve content.
 316  *     'depth' (int) - The max depth.
 317  *     'tab_index' (int) - Tab index for select element.
 318  *     'name' (string) - The name attribute value for selected element.
 319  *     'class' (string) - The class attribute value for selected element.
 320  *     'selected' (int) - Which category ID is selected.
 321  *
 322  * The 'hierarchical' argument, which is disabled by default, will override the
 323  * depth argument, unless it is true. When the argument is false, it will
 324  * display all of the categories. When it is enabled it will use the value in
 325  * the 'depth' argument.
 326  *
 327  * @since 2.1.0
 328  *
 329  * @param string|array $args Optional. Override default arguments.
 330  * @return string HTML content only if 'echo' argument is 0.
 331  */
 332 function wp_dropdown_categories( $args = '' ) {
 333         $defaults = array(
 334                 'show_option_all' => '', 'show_option_none' => '',
 335                 'orderby' => 'id', 'order' => 'ASC',
 336                 'show_last_update' => 0, 'show_count' => 0,
 337                 'hide_empty' => 1, 'child_of' => 0,
 338                 'exclude' => '', 'echo' => 1,
 339                 'selected' => 0, 'hierarchical' => 0,
 340                 'name' => 'cat', 'class' => 'postform',
 341                 'depth' => 0, 'tab_index' => 0
 342         );
 343
 344         $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
 345
 346         $r = wp_parse_args( $args, $defaults );
 347
 348         if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
 349                 $r['pad_counts'] = true;
 350         }
 351
 352         $r['include_last_update_time'] = $r['show_last_update'];
 353         extract( $r );
 354
 355         $tab_index_attribute = '';
 356         if ( (int) $tab_index > 0 )
 357                 $tab_index_attribute = " tabindex=\"$tab_index\"";
 358
 359         $categories = get_categories( $r );
 360         $name = esc_attr($name);
 361         $class = esc_attr($class);
 362
 363         $output = '';
 364         if ( ! empty( $categories ) ) {
 365                 $output = "<select name='$name' id='$name' class='$class' $tab_index_attribute>\n";
 366
 367                 if ( $show_option_all ) {
 368                         $show_option_all = apply_filters( 'list_cats', $show_option_all );
 369                         $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
 370                         $output .= "\t<option value='0'$selected>$show_option_all</option>\n";
 371                 }
 372
 373                 if ( $show_option_none ) {
 374                         $show_option_none = apply_filters( 'list_cats', $show_option_none );
 375                         $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
 376                         $output .= "\t<option value='-1'$selected>$show_option_none</option>\n";
 377                 }
 378
 379                 if ( $hierarchical )
 380                         $depth = $r['depth'];  // Walk the full depth.
 381                 else
 382                         $depth = -1; // Flat.
 383
 384                 $output .= walk_category_dropdown_tree( $categories, $depth, $r );
 385                 $output .= "</select>\n";
 386         }
 387
 388         $output = apply_filters( 'wp_dropdown_cats', $output );
 389
 390         if ( $echo )
 391                 echo $output;
 392
 393         return $output;
 394 }
 395
 396 /**
 397  * Display or retrieve the HTML list of categories.
 398  *
 399  * The list of arguments is below:
 400  *     'show_option_all' (string) - Text to display for showing all categories.
 401  *     'orderby' (string) default is 'ID' - What column to use for ordering the
 402  * categories.
 403  *     'order' (string) default is 'ASC' - What direction to order categories.
 404  *     'show_last_update' (bool|int) default is 0 - See {@link
 405  * walk_category_dropdown_tree()}
 406  *     'show_count' (bool|int) default is 0 - Whether to show how many posts are
 407  * in the category.
 408  *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that
 409  * don't have any posts attached to them.
 410  *     'use_desc_for_title' (bool|int) default is 1 - Whether to use the
 411  * description instead of the category title.
 412  *     'feed' - See {@link get_categories()}.
 413  *     'feed_type' - See {@link get_categories()}.
 414  *     'feed_image' - See {@link get_categories()}.
 415  *     'child_of' (int) default is 0 - See {@link get_categories()}.
 416  *     'exclude' (string) - See {@link get_categories()}.
 417  *     'exclude_tree' (string) - See {@link get_categories()}.
 418  *     'echo' (bool|int) default is 1 - Whether to display or retrieve content.
 419  *     'current_category' (int) - See {@link get_categories()}.
 420  *     'hierarchical' (bool) - See {@link get_categories()}.
 421  *     'title_li' (string) - See {@link get_categories()}.
 422  *     'depth' (int) - The max depth.
 423  *
 424  * @since 2.1.0
 425  *
 426  * @param string|array $args Optional. Override default arguments.
 427  * @return string HTML content only if 'echo' argument is 0.
 428  */
 429 function wp_list_categories( $args = '' ) {
 430         $defaults = array(
 431                 'show_option_all' => '', 'orderby' => 'name',
 432                 'order' => 'ASC', 'show_last_update' => 0,
 433                 'style' => 'list', 'show_count' => 0,
 434                 'hide_empty' => 1, 'use_desc_for_title' => 1,
 435                 'child_of' => 0, 'feed' => '', 'feed_type' => '',
 436                 'feed_image' => '', 'exclude' => '', 'exclude_tree' => '', 'current_category' => 0,
 437                 'hierarchical' => true, 'title_li' => __( 'Categories' ),
 438                 'echo' => 1, 'depth' => 0
 439         );
 440
 441         $r = wp_parse_args( $args, $defaults );
 442
 443         if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
 444                 $r['pad_counts'] = true;
 445         }
 446
 447         if ( isset( $r['show_date'] ) ) {
 448                 $r['include_last_update_time'] = $r['show_date'];
 449         }
 450
 451         if ( true == $r['hierarchical'] ) {
 452                 $r['exclude_tree'] = $r['exclude'];
 453                 $r['exclude'] = '';
 454         }
 455
 456         extract( $r );
 457
 458         $categories = get_categories( $r );
 459
 460         $output = '';
 461         if ( $title_li && 'list' == $style )
 462                         $output = '<li class="categories">' . $r['title_li'] . '<ul>';
 463
 464         if ( empty( $categories ) ) {
 465                 if ( 'list' == $style )
 466                         $output .= '<li>' . __( "No categories" ) . '</li>';
 467                 else
 468                         $output .= __( "No categories" );
 469         } else {
 470                 global $wp_query;
 471
 472                 if( !empty( $show_option_all ) )
 473                         if ( 'list' == $style )
 474                                 $output .= '<li><a href="' .  get_bloginfo( 'url' )  . '">' . $show_option_all . '</a></li>';
 475                         else
 476                                 $output .= '<a href="' .  get_bloginfo( 'url' )  . '">' . $show_option_all . '</a>';
 477
 478                 if ( empty( $r['current_category'] ) && is_category() )
 479                         $r['current_category'] = $wp_query->get_queried_object_id();
 480
 481                 if ( $hierarchical )
 482                         $depth = $r['depth'];
 483                 else
 484                         $depth = -1; // Flat.
 485
 486                 $output .= walk_category_tree( $categories, $depth, $r );
 487         }
 488
 489         if ( $title_li && 'list' == $style )
 490                 $output .= '</ul></li>';
 491
 492         $output = apply_filters( 'wp_list_categories', $output );
 493
 494         if ( $echo )
 495                 echo $output;
 496         else
 497                 return $output;
 498 }
 499
 500 /**
 501  * Display tag cloud.
 502  *
 503  * The text size is set by the 'smallest' and 'largest' arguments, which will
 504  * use the 'unit' argument value for the CSS text size unit. The 'format'
 505  * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
 506  * 'format' argument will separate tags with spaces. The list value for the
 507  * 'format' argument will format the tags in a UL HTML list. The array value for
 508  * the 'format' argument will return in PHP array type format.
 509  *
 510  * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
 511  * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
 512  *
 513  * The 'number' argument is how many tags to return. By default, the limit will
 514  * be to return the top 45 tags in the tag cloud list.
 515  *
 516  * The 'topic_count_text_callback' argument is a function, which, given the count
 517  * of the posts  with that tag, returns a text for the tooltip of the tag link.
 518  *
 519  * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
 520  * function. Only one should be used, because only one will be used and the
 521  * other ignored, if they are both set.
 522  *
 523  * @since 2.3.0
 524  *
 525  * @param array|string $args Optional. Override default arguments.
 526  * @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
 527  */
 528 function wp_tag_cloud( $args = '' ) {
 529         $defaults = array(
 530                 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
 531                 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',
 532                 'exclude' => '', 'include' => '', 'link' => 'view', 'taxonomy' => 'post_tag', 'echo' => true
 533         );
 534         $args = wp_parse_args( $args, $defaults );
 535
 536         $tags = get_terms( $args['taxonomy'], array_merge( $args, array( 'orderby' => 'count', 'order' => 'DESC' ) ) ); // Always query top tags
 537
 538         if ( empty( $tags ) )
 539                 return;
 540
 541         foreach ( $tags as $key => $tag ) {
 542                 if ( 'edit' == $args['link'] )
 543                         $link = get_edit_tag_link( $tag->term_id, $args['taxonomy'] );
 544                 else
 545                         $link = get_term_link( intval($tag->term_id), $args['taxonomy'] );
 546                 if ( is_wp_error( $link ) )
 547                         return false;
 548
 549                 $tags[ $key ]->link = $link;
 550                 $tags[ $key ]->id = $tag->term_id;
 551         }
 552
 553         $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
 554
 555         $return = apply_filters( 'wp_tag_cloud', $return, $args );
 556
 557         if ( 'array' == $args['format'] || empty($args['echo']) )
 558                 return $return;
 559
 560         echo $return;
 561 }
 562
 563 /**
 564  * Default text for tooltip for tag links
 565  *
 566  * @param integer $count number of posts with that tag
 567  * @return string text for the tooltip of a tag link.
 568  */
 569 function default_topic_count_text( $count ) {
 570         return sprintf( _n('%s topic', '%s topics', $count), number_format_i18n( $count ) );
 571 }
 572
 573 /**
 574  * Default topic count scaling for tag links
 575  *
 576  * @param integer $count number of posts with that tag
 577  * @return integer scaled count
 578  */
 579 function default_topic_count_scale( $count ) {
 580         return round(log10($count + 1) * 100);
 581 }
 582
 583
 584 /**
 585  * Generates a tag cloud (heatmap) from provided data.
 586  *
 587  * The text size is set by the 'smallest' and 'largest' arguments, which will
 588  * use the 'unit' argument value for the CSS text size unit. The 'format'
 589  * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
 590  * 'format' argument will separate tags with spaces. The list value for the
 591  * 'format' argument will format the tags in a UL HTML list. The array value for
 592  * the 'format' argument will return in PHP array type format.
 593  *
 594  * The 'tag_cloud_sort' filter allows you to override the sorting.
 595  * Passed to the filter: $tags array and $args array, has to return the $tags array
 596  * after sorting it.
 597  *
 598  * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
 599  * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or
 600  * 'RAND'.
 601  *
 602  * The 'number' argument is how many tags to return. By default, the limit will
 603  * be to return the entire tag cloud list.
 604  *
 605  * The 'topic_count_text_callback' argument is a function, which given the count
 606  * of the posts  with that tag returns a text for the tooltip of the tag link.
 607  *
 608  * @todo Complete functionality.
 609  * @since 2.3.0
 610  *
 611  * @param array $tags List of tags.
 612  * @param string|array $args Optional, override default arguments.
 613  * @return string
 614  */
 615 function wp_generate_tag_cloud( $tags, $args = '' ) {
 616         global $wp_rewrite;
 617         $defaults = array(
 618                 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0,
 619                 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',
 620                 'topic_count_text_callback' => 'default_topic_count_text',
 621                 'topic_count_scale_callback' => 'default_topic_count_scale', 'filter' => 1,
 622         );
 623
 624         if ( !isset( $args['topic_count_text_callback'] ) && isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
 625                 $body = 'return sprintf (
 626                         _n(' . var_export($args['single_text'], true) . ', ' . var_export($args['multiple_text'], true) . ', $count),
 627                         number_format_i18n( $count ));';
 628                 $args['topic_count_text_callback'] = create_function('$count', $body);
 629         }
 630
 631         $args = wp_parse_args( $args, $defaults );
 632         extract( $args );
 633
 634         if ( empty( $tags ) )
 635                 return;
 636
 637         $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
 638         if ( $tags_sorted != $tags  ) { // the tags have been sorted by a plugin
 639                 $tags = $tags_sorted;
 640                 unset($tags_sorted);
 641         } else {
 642                 if ( 'RAND' == $order ) {
 643                         shuffle($tags);
 644                 } else {
 645                         // SQL cannot save you; this is a second (potentially different) sort on a subset of data.
 646                         if ( 'name' == $orderby )
 647                                 uasort( $tags, create_function('$a, $b', 'return strnatcasecmp($a->name, $b->name);') );
 648                         else
 649                                 uasort( $tags, create_function('$a, $b', 'return ($a->count > $b->count);') );
 650
 651                         if ( 'DESC' == $order )
 652                                 $tags = array_reverse( $tags, true );
 653                 }
 654         }
 655
 656         if ( $number > 0 )
 657                 $tags = array_slice($tags, 0, $number);
 658
 659         $counts = array();
 660         $real_counts = array(); // For the alt tag
 661         foreach ( (array) $tags as $key => $tag ) {
 662                 $real_counts[ $key ] = $tag->count;
 663                 $counts[ $key ] = $topic_count_scale_callback($tag->count);
 664         }
 665
 666         $min_count = min( $counts );
 667         $spread = max( $counts ) - $min_count;
 668         if ( $spread <= 0 )
 669                 $spread = 1;
 670         $font_spread = $largest - $smallest;
 671         if ( $font_spread < 0 )
 672                 $font_spread = 1;
 673         $font_step = $font_spread / $spread;
 674
 675         $a = array();
 676
 677         foreach ( $tags as $key => $tag ) {
 678                 $count = $counts[ $key ];
 679                 $real_count = $real_counts[ $key ];
 680                 $tag_link = '#' != $tag->link ? esc_url( $tag->link ) : '#';
 681                 $tag_id = isset($tags[ $key ]->id) ? $tags[ $key ]->id : $key;
 682                 $tag_name = $tags[ $key ]->name;
 683                 $a[] = "<a href='$tag_link' class='tag-link-$tag_id' title='" . esc_attr( $topic_count_text_callback( $real_count ) ) . "' style='font-size: " .
 684                         ( $smallest + ( ( $count - $min_count ) * $font_step ) )
 685                         . "$unit;'>$tag_name</a>";
 686         }
 687
 688         switch ( $format ) :
 689         case 'array' :
 690                 $return =& $a;
 691                 break;
 692         case 'list' :
 693                 $return = "<ul class='wp-tag-cloud'>\n\t<li>";
 694                 $return .= join( "</li>\n\t<li>", $a );
 695                 $return .= "</li>\n</ul>\n";
 696                 break;
 697         default :
 698                 $return = join( $separator, $a );
 699                 break;
 700         endswitch;
 701
 702     if ( $filter )
 703                 return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
 704     else
 705                 return $return;
 706 }
 707
 708 //
 709 // Helper functions
 710 //
 711
 712 /**
 713  * Retrieve HTML list content for category list.
 714  *
 715  * @uses Walker_Category to create HTML list content.
 716  * @since 2.1.0
 717  * @see Walker_Category::walk() for parameters and return description.
 718  */
 719 function walk_category_tree() {
 720         $args = func_get_args();
 721         // the user's options are the third parameter
 722         if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
 723                 $walker = new Walker_Category;
 724         else
 725                 $walker = $args[2]['walker'];
 726
 727         return call_user_func_array(array( &$walker, 'walk' ), $args );
 728 }
 729
 730 /**
 731  * Retrieve HTML dropdown (select) content for category list.
 732  *
 733  * @uses Walker_CategoryDropdown to create HTML dropdown content.
 734  * @since 2.1.0
 735  * @see Walker_CategoryDropdown::walk() for parameters and return description.
 736  */
 737 function walk_category_dropdown_tree() {
 738         $args = func_get_args();
 739         // the user's options are the third parameter
 740         if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
 741                 $walker = new Walker_CategoryDropdown;
 742         else
 743                 $walker = $args[2]['walker'];
 744
 745         return call_user_func_array(array( &$walker, 'walk' ), $args );
 746 }
 747
 748 //
 749 // Tags
 750 //
 751
 752 /**
 753  * Retrieve the link to the tag.
 754  *
 755  * @since 2.3.0
 756  * @uses apply_filters() Calls 'tag_link' with tag link and tag ID as parameters.
 757  *
 758  * @param int $tag_id Tag (term) ID.
 759  * @return string
 760  */
 761 function get_tag_link( $tag_id ) {
 762         global $wp_rewrite;
 763         $taglink = $wp_rewrite->get_tag_permastruct();
 764
 765         $tag = &get_term( $tag_id, 'post_tag' );
 766         if ( is_wp_error( $tag ) )
 767                 return $tag;
 768         $slug = $tag->slug;
 769
 770         if ( empty( $taglink ) ) {
 771                 $file = get_option( 'home' ) . '/';
 772                 $taglink = $file . '?tag=' . $slug;
 773         } else {
 774                 $taglink = str_replace( '%tag%', $slug, $taglink );
 775                 $taglink = get_option( 'home' ) . user_trailingslashit( $taglink, 'category' );
 776         }
 777         return apply_filters( 'tag_link', $taglink, $tag_id );
 778 }
 779
 780 /**
 781  * Retrieve the tags for a post.
 782  *
 783  * @since 2.3.0
 784  * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
 785  *
 786  * @param int $id Post ID.
 787  * @return array
 788  */
 789 function get_the_tags( $id = 0 ) {
 790         return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
 791 }
 792
 793 /**
 794  * Retrieve the tags for a post formatted as a string.
 795  *
 796  * @since 2.3.0
 797  * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
 798  *
 799  * @param string $before Optional. Before tags.
 800  * @param string $sep Optional. Between tags.
 801  * @param string $after Optional. After tags.
 802  * @return string
 803  */
 804 function get_the_tag_list( $before = '', $sep = '', $after = '' ) {
 805         return apply_filters( 'the_tags', get_the_term_list( 0, 'post_tag', $before, $sep, $after ), $before, $sep, $after);
 806 }
 807
 808 /**
 809  * Retrieve the tags for a post.
 810  *
 811  * @since 2.3.0
 812  *
 813  * @param string $before Optional. Before list.
 814  * @param string $sep Optional. Separate items using this.
 815  * @param string $after Optional. After list.
 816  * @return string
 817  */
 818 function the_tags( $before = null, $sep = ', ', $after = '' ) {
 819         if ( null === $before )
 820                 $before = __('Tags: ');
 821         echo get_the_tag_list($before, $sep, $after);
 822 }
 823
 824 /**
 825  * Retrieve tag description.
 826  *
 827  * @since 2.8
 828  *
 829  * @param int $tag Optional. Tag ID. Will use global tag ID by default.
 830  * @return string Tag description, available.
 831  */
 832 function tag_description( $tag = 0 ) {
 833         return term_description( $tag );
 834 }
 835
 836 /**
 837  * Retrieve term description.
 838  *
 839  * @since 2.8
 840  *
 841  * @param int $term Optional. Term ID. Will use global term ID by default.
 842  * @return string Term description, available.
 843  */
 844 function term_description( $term = 0, $taxonomy = 'post_tag' ) {
 845         if ( !$term && ( is_tax() || is_tag() || is_category() ) ) {
 846                 global $wp_query;
 847                 $term = $wp_query->get_queried_object();
 848                 $taxonomy = $term->taxonomy;
 849                 $term = $term->term_id;
 850         }
 851         return get_term_field( 'description', $term, $taxonomy );
 852 }
 853
 854 /**
 855  * Retrieve the terms of the taxonomy that are attached to the post.
 856  *
 857  * This function can only be used within the loop.
 858  *
 859  * @since 2.5.0
 860  *
 861  * @param int $id Post ID. Is not optional.
 862  * @param string $taxonomy Taxonomy name.
 863  * @return array|bool False on failure. Array of term objects on success.
 864  */
 865 function get_the_terms( $id = 0, $taxonomy ) {
 866         global $post;
 867
 868         $id = (int) $id;
 869
 870         if ( !$id ) {
 871                 if ( !$post->ID )
 872                         return false;
 873                 else
 874                         $id = (int) $post->ID;
 875         }
 876
 877         $terms = get_object_term_cache( $id, $taxonomy );
 878         if ( false === $terms )
 879                 $terms = wp_get_object_terms( $id, $taxonomy );
 880
 881         if ( empty( $terms ) )
 882                 return false;
 883
 884         return $terms;
 885 }
 886
 887 /**
 888  * Retrieve a post's terms as a list with specified format.
 889  *
 890  * @since 2.5.0
 891  *
 892  * @param int $id Post ID.
 893  * @param string $taxonomy Taxonomy name.
 894  * @param string $before Optional. Before list.
 895  * @param string $sep Optional. Separate items using this.
 896  * @param string $after Optional. After list.
 897  * @return string
 898  */
 899 function get_the_term_list( $id = 0, $taxonomy, $before = '', $sep = '', $after = '' ) {
 900         $terms = get_the_terms( $id, $taxonomy );
 901
 902         if ( is_wp_error( $terms ) )
 903                 return $terms;
 904
 905         if ( empty( $terms ) )
 906                 return false;
 907
 908         foreach ( $terms as $term ) {
 909                 $link = get_term_link( $term, $taxonomy );
 910                 if ( is_wp_error( $link ) )
 911                         return $link;
 912                 $term_links[] = '<a href="' . $link . '" rel="tag">' . $term->name . '</a>';
 913         }
 914
 915         $term_links = apply_filters( "term_links-$taxonomy", $term_links );
 916
 917         return $before . join( $sep, $term_links ) . $after;
 918 }
 919
 920 /**
 921  * Display the terms in a list.
 922  *
 923  * @since 2.5.0
 924  *
 925  * @param int $id Term ID.
 926  * @param string $taxonomy Taxonomy name.
 927  * @param string $before Optional. Before list.
 928  * @param string $sep Optional. Separate items using this.
 929  * @param string $after Optional. After list.
 930  * @return null|bool False on WordPress error. Returns null when displaying.
 931  */
 932 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
 933         $term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
 934
 935         if ( is_wp_error( $term_list ) )
 936                 return false;
 937
 938         echo apply_filters('the_terms', $term_list, $taxonomy, $before, $sep, $after);
 939 }
 940
 941 /**
 942  * Check if the current post has any of given tags.
 943  *
 944  * The given tags are checked against the post's tags' term_ids, names and slugs.
 945  * Tags given as integers will only be checked against the post's tags' term_ids.
 946  * If no tags are given, determines if post has any tags.
 947  *
 948  * 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)
 949  * Prior to v2.7, this function could only be used in the WordPress Loop.
 950  * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
 951  *
 952  * @since 2.6.0
 953  *
 954  * @uses is_object_in_term()
 955  *
 956  * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for.
 957  * @param int|post object Optional.  Post to check instead of the current post. @since 2.7.0
 958  * @return bool True if the current post has any of the the given tags (or any tag, if no tag specified).
 959  */
 960 function has_tag( $tag = '', $_post = null ) {
 961         if ( $_post ) {
 962                 $_post = get_post( $_post );
 963         } else {
 964                 $_post =& $GLOBALS['post'];
 965         }
 966
 967         if ( !$_post )
 968                 return false;
 969
 970         $r = is_object_in_term( $_post->ID, 'post_tag', $tag );
 971         if ( is_wp_error( $r ) )
 972                 return false;
 973         return $r;
 974 }
 975
 976 ?>