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         $r['include_last_update_time'] = $r['show_last_update'];
 348         extract( $r );
 349
 350         $tab_index_attribute = '';
 351         if ( (int) $tab_index > 0 )
 352                 $tab_index_attribute = " tabindex=\"$tab_index\"";
 353
 354         $categories = get_categories( $r );
 355         $name = esc_attr($name);
 356         $class = esc_attr($class);
 357
 358         $output = '';
 359         if ( ! empty( $categories ) ) {
 360                 $output = "<select name='$name' id='$name' class='$class' $tab_index_attribute>\n";
 361
 362                 if ( $show_option_all ) {
 363                         $show_option_all = apply_filters( 'list_cats', $show_option_all );
 364                         $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
 365                         $output .= "\t<option value='0'$selected>$show_option_all</option>\n";
 366                 }
 367
 368                 if ( $show_option_none ) {
 369                         $show_option_none = apply_filters( 'list_cats', $show_option_none );
 370                         $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
 371                         $output .= "\t<option value='-1'$selected>$show_option_none</option>\n";
 372                 }
 373
 374                 if ( $hierarchical )
 375                         $depth = $r['depth'];  // Walk the full depth.
 376                 else
 377                         $depth = -1; // Flat.
 378
 379                 $output .= walk_category_dropdown_tree( $categories, $depth, $r );
 380                 $output .= "</select>\n";
 381         }
 382
 383         $output = apply_filters( 'wp_dropdown_cats', $output );
 384
 385         if ( $echo )
 386                 echo $output;
 387
 388         return $output;
 389 }
 390
 391 /**
 392  * Display or retrieve the HTML list of categories.
 393  *
 394  * The list of arguments is below:
 395  *     'show_option_all' (string) - Text to display for showing all categories.
 396  *     'orderby' (string) default is 'ID' - What column to use for ordering the
 397  * categories.
 398  *     'order' (string) default is 'ASC' - What direction to order categories.
 399  *     'show_last_update' (bool|int) default is 0 - See {@link
 400  * walk_category_dropdown_tree()}
 401  *     'show_count' (bool|int) default is 0 - Whether to show how many posts are
 402  * in the category.
 403  *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that
 404  * don't have any posts attached to them.
 405  *     'use_desc_for_title' (bool|int) default is 1 - Whether to use the
 406  * description instead of the category title.
 407  *     'feed' - See {@link get_categories()}.
 408  *     'feed_type' - See {@link get_categories()}.
 409  *     'feed_image' - See {@link get_categories()}.
 410  *     'child_of' (int) default is 0 - See {@link get_categories()}.
 411  *     'exclude' (string) - See {@link get_categories()}.
 412  *     'exclude_tree' (string) - See {@link get_categories()}.
 413  *     'echo' (bool|int) default is 1 - Whether to display or retrieve content.
 414  *     'current_category' (int) - See {@link get_categories()}.
 415  *     'hierarchical' (bool) - See {@link get_categories()}.
 416  *     'title_li' (string) - See {@link get_categories()}.
 417  *     'depth' (int) - The max depth.
 418  *
 419  * @since 2.1.0
 420  *
 421  * @param string|array $args Optional. Override default arguments.
 422  * @return string HTML content only if 'echo' argument is 0.
 423  */
 424 function wp_list_categories( $args = '' ) {
 425         $defaults = array(
 426                 'show_option_all' => '', 'orderby' => 'name',
 427                 'order' => 'ASC', 'show_last_update' => 0,
 428                 'style' => 'list', 'show_count' => 0,
 429                 'hide_empty' => 1, 'use_desc_for_title' => 1,
 430                 'child_of' => 0, 'feed' => '', 'feed_type' => '',
 431                 'feed_image' => '', 'exclude' => '', 'exclude_tree' => '', 'current_category' => 0,
 432                 'hierarchical' => true, 'title_li' => __( 'Categories' ),
 433                 'echo' => 1, 'depth' => 0
 434         );
 435
 436         $r = wp_parse_args( $args, $defaults );
 437
 438         if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
 439                 $r['pad_counts'] = true;
 440         }
 441
 442         if ( isset( $r['show_date'] ) ) {
 443                 $r['include_last_update_time'] = $r['show_date'];
 444         }
 445
 446         if ( true == $r['hierarchical'] ) {
 447                 $r['exclude_tree'] = $r['exclude'];
 448                 $r['exclude'] = '';
 449         }
 450
 451         extract( $r );
 452
 453         $categories = get_categories( $r );
 454
 455         $output = '';
 456         if ( $title_li && 'list' == $style )
 457                         $output = '<li class="categories">' . $r['title_li'] . '<ul>';
 458
 459         if ( empty( $categories ) ) {
 460                 if ( 'list' == $style )
 461                         $output .= '<li>' . __( "No categories" ) . '</li>';
 462                 else
 463                         $output .= __( "No categories" );
 464         } else {
 465                 global $wp_query;
 466
 467                 if( !empty( $show_option_all ) )
 468                         if ( 'list' == $style )
 469                                 $output .= '<li><a href="' .  get_bloginfo( 'url' )  . '">' . $show_option_all . '</a></li>';
 470                         else
 471                                 $output .= '<a href="' .  get_bloginfo( 'url' )  . '">' . $show_option_all . '</a>';
 472
 473                 if ( empty( $r['current_category'] ) && is_category() )
 474                         $r['current_category'] = $wp_query->get_queried_object_id();
 475
 476                 if ( $hierarchical )
 477                         $depth = $r['depth'];
 478                 else
 479                         $depth = -1; // Flat.
 480
 481                 $output .= walk_category_tree( $categories, $depth, $r );
 482         }
 483
 484         if ( $title_li && 'list' == $style )
 485                 $output .= '</ul></li>';
 486
 487         $output = apply_filters( 'wp_list_categories', $output );
 488
 489         if ( $echo )
 490                 echo $output;
 491         else
 492                 return $output;
 493 }
 494
 495 /**
 496  * Display tag cloud.
 497  *
 498  * The text size is set by the 'smallest' and 'largest' arguments, which will
 499  * use the 'unit' argument value for the CSS text size unit. The 'format'
 500  * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
 501  * 'format' argument will separate tags with spaces. The list value for the
 502  * 'format' argument will format the tags in a UL HTML list. The array value for
 503  * the 'format' argument will return in PHP array type format.
 504  *
 505  * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
 506  * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
 507  *
 508  * The 'number' argument is how many tags to return. By default, the limit will
 509  * be to return the top 45 tags in the tag cloud list.
 510  *
 511  * The 'topic_count_text_callback' argument is a function, which, given the count
 512  * of the posts  with that tag, returns a text for the tooltip of the tag link.
 513  *
 514  * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
 515  * function. Only one should be used, because only one will be used and the
 516  * other ignored, if they are both set.
 517  *
 518  * @since 2.3.0
 519  *
 520  * @param array|string $args Optional. Override default arguments.
 521  * @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
 522  */
 523 function wp_tag_cloud( $args = '' ) {
 524         $defaults = array(
 525                 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
 526                 'format' => 'flat', 'orderby' => 'name', 'order' => 'ASC',
 527                 'exclude' => '', 'include' => '', 'link' => 'view', 'taxonomy' => 'post_tag', 'echo' => true
 528         );
 529         $args = wp_parse_args( $args, $defaults );
 530
 531         $tags = get_terms( $args['taxonomy'], array_merge( $args, array( 'orderby' => 'count', 'order' => 'DESC' ) ) ); // Always query top tags
 532
 533         if ( empty( $tags ) )
 534                 return;
 535
 536         foreach ( $tags as $key => $tag ) {
 537                 if ( 'edit' == $args['link'] )
 538                         $link = get_edit_tag_link( $tag->term_id, $args['taxonomy'] );
 539                 else
 540                         $link = get_term_link( intval($tag->term_id), $args['taxonomy'] );
 541                 if ( is_wp_error( $link ) )
 542                         return false;
 543
 544                 $tags[ $key ]->link = $link;
 545                 $tags[ $key ]->id = $tag->term_id;
 546         }
 547
 548         $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
 549
 550         $return = apply_filters( 'wp_tag_cloud', $return, $args );
 551
 552         if ( 'array' == $args['format'] || empty($args['echo']) )
 553                 return $return;
 554
 555         echo $return;
 556 }
 557
 558 /**
 559  * Default text for tooltip for tag links
 560  *
 561  * @param integer $count number of posts with that tag
 562  * @return string text for the tooltip of a tag link.
 563  */
 564 function default_topic_count_text( $count ) {
 565         return sprintf( _n('%s topic', '%s topics', $count), number_format_i18n( $count ) );
 566 }
 567
 568 /**
 569  * Generates a tag cloud (heatmap) from provided data.
 570  *
 571  * The text size is set by the 'smallest' and 'largest' arguments, which will
 572  * use the 'unit' argument value for the CSS text size unit. The 'format'
 573  * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
 574  * 'format' argument will separate tags with spaces. The list value for the
 575  * 'format' argument will format the tags in a UL HTML list. The array value for
 576  * the 'format' argument will return in PHP array type format.
 577  *
 578  * The 'tag_cloud_sort' filter allows you to override the sorting done
 579  * by the 'orderby' argument; passed to the filter: $tags array and $args array.
 580  *
 581  * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
 582  * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or
 583  * 'RAND'.
 584  *
 585  * The 'number' argument is how many tags to return. By default, the limit will
 586  * be to return the entire tag cloud list.
 587  *
 588  * The 'topic_count_text_callback' argument is a function, which given the count
 589  * of the posts  with that tag returns a text for the tooltip of the tag link.
 590  *
 591  * @todo Complete functionality.
 592  * @since 2.3.0
 593  *
 594  * @param array $tags List of tags.
 595  * @param string|array $args Optional, override default arguments.
 596  * @return string
 597  */
 598 function wp_generate_tag_cloud( $tags, $args = '' ) {
 599         global $wp_rewrite;
 600         $defaults = array(
 601                 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0,
 602                 'format' => 'flat', 'orderby' => 'name', 'order' => 'ASC',
 603                 'topic_count_text_callback' => 'default_topic_count_text',
 604                 'filter' => 1,
 605         );
 606
 607         if ( !isset( $args['topic_count_text_callback'] ) && isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
 608                 $body = 'return sprintf (
 609                         _n('.var_export($args['single_text'], true).', '.var_export($args['multiple_text'], true).', $count),
 610                         number_format_i18n( $count ));';
 611                 $args['topic_count_text_callback'] = create_function('$count', $body);
 612         }
 613
 614         $args = wp_parse_args( $args, $defaults );
 615
 616         extract( $args );
 617
 618         if ( empty( $tags ) )
 619                 return;
 620
 621         // SQL cannot save you; this is a second (potentially different) sort on a subset of data.
 622         if ( 'name' == $orderby )
 623                 uasort( $tags, create_function('$a, $b', 'return strnatcasecmp($a->name, $b->name);') );
 624         else
 625                 uasort( $tags, create_function('$a, $b', 'return ($a->count > $b->count);') );
 626
 627         $tags = apply_filters( 'tag_cloud_sort', $tags, $args );
 628
 629         if ( 'DESC' == $order )
 630                 $tags = array_reverse( $tags, true );
 631         elseif ( 'RAND' == $order ) {
 632                 $keys = (array) array_rand( $tags, count( $tags ) );
 633                 $temp = array();
 634                 foreach ( $keys as $key )
 635                         $temp[$key] = $tags[$key];
 636
 637                 $tags = $temp;
 638                 $temp = null;
 639                 unset( $temp );
 640         }
 641
 642         if ( $number > 0 )
 643                 $tags = array_slice($tags, 0, $number);
 644
 645         $counts = array();
 646         foreach ( (array) $tags as $key => $tag )
 647                 $counts[ $key ] = $tag->count;
 648
 649         $min_count = min( $counts );
 650         $spread = max( $counts ) - $min_count;
 651         if ( $spread <= 0 )
 652                 $spread = 1;
 653         $font_spread = $largest - $smallest;
 654         if ( $font_spread < 0 )
 655                 $font_spread = 1;
 656         $font_step = $font_spread / $spread;
 657
 658         $a = array();
 659
 660         $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? ' rel="tag"' : '';
 661
 662         foreach ( $tags as $key => $tag ) {
 663                 $count = $counts[ $key ];
 664                 $tag_link = '#' != $tag->link ? esc_url( $tag->link ) : '#';
 665                 $tag_id = isset($tags[ $key ]->id) ? $tags[ $key ]->id : $key;
 666                 $tag_name = $tags[ $key ]->name;
 667                 $a[] = "<a href='$tag_link' class='tag-link-$tag_id' title='" . esc_attr( $topic_count_text_callback( $count ) ) . "'$rel style='font-size: " .
 668                         ( $smallest + ( ( $count - $min_count ) * $font_step ) )
 669                         . "$unit;'>$tag_name</a>";
 670         }
 671
 672         switch ( $format ) :
 673         case 'array' :
 674                 $return =& $a;
 675                 break;
 676         case 'list' :
 677                 $return = "<ul class='wp-tag-cloud'>\n\t<li>";
 678                 $return .= join( "</li>\n\t<li>", $a );
 679                 $return .= "</li>\n</ul>\n";
 680                 break;
 681         default :
 682                 $return = join( "\n", $a );
 683                 break;
 684         endswitch;
 685
 686     if ( $filter )
 687                 return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
 688     else
 689                 return $return;
 690 }
 691
 692 //
 693 // Helper functions
 694 //
 695
 696 /**
 697  * Retrieve HTML list content for category list.
 698  *
 699  * @uses Walker_Category to create HTML list content.
 700  * @since 2.1.0
 701  * @see Walker_Category::walk() for parameters and return description.
 702  */
 703 function walk_category_tree() {
 704         $args = func_get_args();
 705         // the user's options are the third parameter
 706         if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
 707                 $walker = new Walker_Category;
 708         else
 709                 $walker = $args[2]['walker'];
 710
 711         return call_user_func_array(array( &$walker, 'walk' ), $args );
 712 }
 713
 714 /**
 715  * Retrieve HTML dropdown (select) content for category list.
 716  *
 717  * @uses Walker_CategoryDropdown to create HTML dropdown content.
 718  * @since 2.1.0
 719  * @see Walker_CategoryDropdown::walk() for parameters and return description.
 720  */
 721 function walk_category_dropdown_tree() {
 722         $args = func_get_args();
 723         // the user's options are the third parameter
 724         if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
 725                 $walker = new Walker_CategoryDropdown;
 726         else
 727                 $walker = $args[2]['walker'];
 728
 729         return call_user_func_array(array( &$walker, 'walk' ), $args );
 730 }
 731
 732 //
 733 // Tags
 734 //
 735
 736 /**
 737  * Retrieve the link to the tag.
 738  *
 739  * @since 2.3.0
 740  * @uses apply_filters() Calls 'tag_link' with tag link and tag ID as parameters.
 741  *
 742  * @param int $tag_id Tag (term) ID.
 743  * @return string
 744  */
 745 function get_tag_link( $tag_id ) {
 746         global $wp_rewrite;
 747         $taglink = $wp_rewrite->get_tag_permastruct();
 748
 749         $tag = &get_term( $tag_id, 'post_tag' );
 750         if ( is_wp_error( $tag ) )
 751                 return $tag;
 752         $slug = $tag->slug;
 753
 754         if ( empty( $taglink ) ) {
 755                 $file = get_option( 'home' ) . '/';
 756                 $taglink = $file . '?tag=' . $slug;
 757         } else {
 758                 $taglink = str_replace( '%tag%', $slug, $taglink );
 759                 $taglink = get_option( 'home' ) . user_trailingslashit( $taglink, 'category' );
 760         }
 761         return apply_filters( 'tag_link', $taglink, $tag_id );
 762 }
 763
 764 /**
 765  * Retrieve the tags for a post.
 766  *
 767  * @since 2.3.0
 768  * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
 769  *
 770  * @param int $id Post ID.
 771  * @return array
 772  */
 773 function get_the_tags( $id = 0 ) {
 774         return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
 775 }
 776
 777 /**
 778  * Retrieve the tags for a post formatted as a string.
 779  *
 780  * @since 2.3.0
 781  * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
 782  *
 783  * @param string $before Optional. Before tags.
 784  * @param string $sep Optional. Between tags.
 785  * @param string $after Optional. After tags.
 786  * @return string
 787  */
 788 function get_the_tag_list( $before = '', $sep = '', $after = '' ) {
 789         return apply_filters( 'the_tags', get_the_term_list( 0, 'post_tag', $before, $sep, $after ), $before, $sep, $after);
 790 }
 791
 792 /**
 793  * Retrieve the tags for a post.
 794  *
 795  * @since 2.3.0
 796  *
 797  * @param string $before Optional. Before list.
 798  * @param string $sep Optional. Separate items using this.
 799  * @param string $after Optional. After list.
 800  * @return string
 801  */
 802 function the_tags( $before = null, $sep = ', ', $after = '' ) {
 803         if ( null === $before )
 804                 $before = __('Tags: ');
 805         echo get_the_tag_list($before, $sep, $after);
 806 }
 807
 808 /**
 809  * Retrieve tag description.
 810  *
 811  * @since 2.8
 812  *
 813  * @param int $tag Optional. Tag ID. Will use global tag ID by default.
 814  * @return string Tag description, available.
 815  */
 816 function tag_description( $tag = 0 ) {
 817         return term_description( $tag );
 818 }
 819
 820 /**
 821  * Retrieve term description.
 822  *
 823  * @since 2.8
 824  *
 825  * @param int $term Optional. Term ID. Will use global term ID by default.
 826  * @return string Term description, available.
 827  */
 828 function term_description( $term = 0, $taxonomy = 'post_tag' ) {
 829         if ( !$term && ( is_tax() || is_tag() || is_category() ) ) {
 830                 global $wp_query;
 831                 $term = $wp_query->get_queried_object();
 832                 $taxonomy = $term->taxonomy;
 833                 $term = $term->term_id;
 834         }
 835         return get_term_field( 'description', $term, $taxonomy );
 836 }
 837
 838 /**
 839  * Retrieve the terms of the taxonomy that are attached to the post.
 840  *
 841  * This function can only be used within the loop.
 842  *
 843  * @since 2.5.0
 844  *
 845  * @param int $id Post ID. Is not optional.
 846  * @param string $taxonomy Taxonomy name.
 847  * @return array|bool False on failure. Array of term objects on success.
 848  */
 849 function get_the_terms( $id = 0, $taxonomy ) {
 850         global $post;
 851
 852         $id = (int) $id;
 853
 854         if ( ! $id && ! in_the_loop() )
 855                 return false; // in-the-loop function
 856
 857         if ( !$id )
 858                 $id = (int) $post->ID;
 859
 860         $terms = get_object_term_cache( $id, $taxonomy );
 861         if ( false === $terms )
 862                 $terms = wp_get_object_terms( $id, $taxonomy );
 863
 864         if ( empty( $terms ) )
 865                 return false;
 866
 867         return $terms;
 868 }
 869
 870 /**
 871  * Retrieve terms as a list with specified format.
 872  *
 873  * @since 2.5.0
 874  *
 875  * @param int $id Term ID.
 876  * @param string $taxonomy Taxonomy name.
 877  * @param string $before Optional. Before list.
 878  * @param string $sep Optional. Separate items using this.
 879  * @param string $after Optional. After list.
 880  * @return string
 881  */
 882 function get_the_term_list( $id = 0, $taxonomy, $before = '', $sep = '', $after = '' ) {
 883         $terms = get_the_terms( $id, $taxonomy );
 884
 885         if ( is_wp_error( $terms ) )
 886                 return $terms;
 887
 888         if ( empty( $terms ) )
 889                 return false;
 890
 891         foreach ( $terms as $term ) {
 892                 $link = get_term_link( $term, $taxonomy );
 893                 if ( is_wp_error( $link ) )
 894                         return $link;
 895                 $term_links[] = '<a href="' . $link . '" rel="tag">' . $term->name . '</a>';
 896         }
 897
 898         $term_links = apply_filters( "term_links-$taxonomy", $term_links );
 899
 900         return $before . join( $sep, $term_links ) . $after;
 901 }
 902
 903 /**
 904  * Display the terms in a list.
 905  *
 906  * @since 2.5.0
 907  *
 908  * @param int $id Term ID.
 909  * @param string $taxonomy Taxonomy name.
 910  * @param string $before Optional. Before list.
 911  * @param string $sep Optional. Separate items using this.
 912  * @param string $after Optional. After list.
 913  * @return null|bool False on WordPress error. Returns null when displaying.
 914  */
 915 function the_terms( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
 916         $return = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
 917         if ( is_wp_error( $return ) )
 918                 return false;
 919         else
 920                 echo $return;
 921 }
 922
 923 /**
 924  * Check if the current post has any of given tags.
 925  *
 926  * The given tags are checked against the post's tags' term_ids, names and slugs.
 927  * Tags given as integers will only be checked against the post's tags' term_ids.
 928  * If no tags are given, determines if post has any tags.
 929  *
 930  * 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)
 931  * Prior to v2.7, this function could only be used in the WordPress Loop.
 932  * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
 933  *
 934  * @since 2.6.0
 935  *
 936  * @uses is_object_in_term()
 937  *
 938  * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for.
 939  * @param int|post object Optional.  Post to check instead of the current post. @since 2.7.0
 940  * @return bool True if the current post has any of the the given tags (or any tag, if no tag specified).
 941  */
 942 function has_tag( $tag = '', $_post = null ) {
 943         if ( $_post ) {
 944                 $_post = get_post( $_post );
 945         } else {
 946                 $_post =& $GLOBALS['post'];
 947         }
 948
 949         if ( !$_post )
 950                 return false;
 951
 952         $r = is_object_in_term( $_post->ID, 'post_tag', $tag );
 953         if ( is_wp_error( $r ) )
 954                 return false;
 955         return $r;
 956 }
 957
 958 ?>