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