[Summary view] [Print] [Text view]

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