3 * Category Template Tags and API.
10 * Retrieve category children list separated before and after the term IDs.
14 * @param int $id Category ID to retrieve children.
15 * @param string $before Optional. Prepend before category term ID.
16 * @param string $after Optional, default is empty string. Append after category term ID.
17 * @param array $visited Optional. Category Term IDs that have already been added.
20 function get_category_children( $id, $before = '/', $after = '', $visited = array() ) {
25 /** TODO: consult hierarchy */
26 $cat_ids = get_all_category_ids();
27 foreach ( (array) $cat_ids as $cat_id ) {
31 $category = get_category( $cat_id );
32 if ( is_wp_error( $category ) )
34 if ( $category->parent == $id && !in_array( $category->term_id, $visited ) ) {
35 $visited[] = $category->term_id;
36 $chain .= $before.$category->term_id.$after;
37 $chain .= get_category_children( $category->term_id, $before, $after );
44 * Retrieve category link URL.
47 * @uses apply_filters() Calls 'category_link' filter on category link and category ID.
49 * @param int $category_id Category ID.
52 function get_category_link( $category_id ) {
54 $catlink = $wp_rewrite->get_category_permastruct();
56 if ( empty( $catlink ) ) {
57 $file = get_option( 'home' ) . '/';
58 $catlink = $file . '?cat=' . $category_id;
60 $category = &get_category( $category_id );
61 if ( is_wp_error( $category ) )
63 $category_nicename = $category->slug;
65 if ( $category->parent == $category_id ) // recursive recursion
66 $category->parent = 0;
67 elseif ($category->parent != 0 )
68 $category_nicename = get_category_parents( $category->parent, false, '/', true ) . $category_nicename;
70 $catlink = str_replace( '%category%', $category_nicename, $catlink );
71 $catlink = get_option( 'home' ) . user_trailingslashit( $catlink, 'category' );
73 return apply_filters( 'category_link', $catlink, $category_id );
77 * Retrieve category parents with separator.
81 * @param int $id Category ID.
82 * @param bool $link Optional, default is false. Whether to format with link.
83 * @param string $separator Optional, default is '/'. How to separate categories.
84 * @param bool $nicename Optional, default is false. Whether to use nice name for display.
85 * @param array $visited Optional. Already linked to categories to prevent duplicates.
88 function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) {
90 $parent = &get_category( $id );
91 if ( is_wp_error( $parent ) )
95 $name = $parent->slug;
97 $name = $parent->cat_name;
99 if ( $parent->parent && ( $parent->parent != $parent->term_id ) && !in_array( $parent->parent, $visited ) ) {
100 $visited[] = $parent->parent;
101 $chain .= get_category_parents( $parent->parent, $link, $separator, $nicename, $visited );
105 $chain .= '<a href="' . get_category_link( $parent->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $parent->cat_name ) . '">'.$name.'</a>' . $separator;
107 $chain .= $name.$separator;
112 * Retrieve post categories.
117 * @param int $id Optional, default to current post ID. The post ID.
120 function get_the_category( $id = false ) {
125 $id = (int) $post->ID;
127 $categories = get_object_term_cache( $id, 'category' );
128 if ( false === $categories ) {
129 $categories = wp_get_object_terms( $id, 'category' );
130 wp_cache_add($id, $categories, 'category_relationships');
133 if ( !empty( $categories ) )
134 usort( $categories, '_usort_terms_by_name' );
136 $categories = array();
138 foreach ( (array) array_keys( $categories ) as $key ) {
139 _make_cat_compat( $categories[$key] );
146 * Sort categories by name.
148 * Used by usort() as a callback, should not be used directly. Can actually be
149 * used to sort any term object.
158 function _usort_terms_by_name( $a, $b ) {
159 return strcmp( $a->name, $b->name );
163 * Sort categories by ID.
165 * Used by usort() as a callback, should not be used directly. Can actually be
166 * used to sort any term object.
175 function _usort_terms_by_ID( $a, $b ) {
176 if ( $a->term_id > $b->term_id )
178 elseif ( $a->term_id < $b->term_id )
185 * Retrieve category name based on category ID.
189 * @param int $cat_ID Category ID.
190 * @return string Category name.
192 function get_the_category_by_ID( $cat_ID ) {
193 $cat_ID = (int) $cat_ID;
194 $category = &get_category( $cat_ID );
195 if ( is_wp_error( $category ) )
197 return $category->name;
201 * Retrieve category list in either HTML list or custom format.
205 * @param string $separator Optional, default is empty string. Separator for between the categories.
206 * @param string $parents Optional. How to display the parents.
207 * @param int $post_id Optional. Post ID to retrieve categories.
210 function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
212 $categories = get_the_category( $post_id );
213 if ( empty( $categories ) )
214 return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
216 $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
219 if ( '' == $separator ) {
220 $thelist .= '<ul class="post-categories">';
221 foreach ( $categories as $category ) {
222 $thelist .= "\n\t<li>";
223 switch ( strtolower( $parents ) ) {
225 if ( $category->parent )
226 $thelist .= get_category_parents( $category->parent, true, $separator );
227 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->name.'</a></li>';
230 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>';
231 if ( $category->parent )
232 $thelist .= get_category_parents( $category->parent, false, $separator );
233 $thelist .= $category->name.'</a></li>';
237 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->cat_name.'</a></li>';
243 foreach ( $categories as $category ) {
245 $thelist .= $separator . ' ';
246 switch ( strtolower( $parents ) ) {
248 if ( $category->parent )
249 $thelist .= get_category_parents( $category->parent, true, $separator );
250 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->cat_name.'</a>';
253 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>';
254 if ( $category->parent )
255 $thelist .= get_category_parents( $category->parent, false, $separator );
256 $thelist .= "$category->cat_name</a>";
260 $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->name.'</a>';
265 return apply_filters( 'the_category', $thelist, $separator, $parents );
270 * Check if the current post in within any of the given categories.
272 * The given categories are checked against the post's categories' term_ids, names and slugs.
273 * Categories given as integers will only be checked against the post's categories' term_ids.
275 * Prior to v2.5 of WordPress, category names were not supported.
276 * Prior to v2.7, category slugs were not supported.
277 * Prior to v2.7, only one category could be compared: in_category( $single_category ).
278 * Prior to v2.7, this function could only be used in the WordPress Loop.
279 * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
283 * @uses is_object_in_term()
285 * @param int|string|array $category. Category ID, name or slug, or array of said.
286 * @param int|post object Optional. Post to check instead of the current post. @since 2.7.0
287 * @return bool True if the current post is in any of the given categories.
289 function in_category( $category, $_post = null ) {
290 if ( empty( $category ) )
294 $_post = get_post( $_post );
296 $_post =& $GLOBALS['post'];
302 $r = is_object_in_term( $_post->ID, 'category', $category );
303 if ( is_wp_error( $r ) )
309 * Display the category list for the post.
313 * @param string $separator Optional, default is empty string. Separator for between the categories.
314 * @param string $parents Optional. How to display the parents.
315 * @param int $post_id Optional. Post ID to retrieve categories.
317 function the_category( $separator = '', $parents='', $post_id = false ) {
318 echo get_the_category_list( $separator, $parents, $post_id );
322 * Retrieve category description.
326 * @param int $category Optional. Category ID. Will use global category ID by default.
327 * @return string Category description, available.
329 function category_description( $category = 0 ) {
334 return get_term_field( 'description', $category, 'category' );
338 * Display or retrieve the HTML dropdown list of categories.
340 * The list of arguments is below:
341 * 'show_option_all' (string) - Text to display for showing all categories.
342 * 'show_option_none' (string) - Text to display for showing no categories.
343 * 'orderby' (string) default is 'ID' - What column to use for ordering the
345 * 'order' (string) default is 'ASC' - What direction to order categories.
346 * 'show_last_update' (bool|int) default is 0 - See {@link get_categories()}
347 * 'show_count' (bool|int) default is 0 - Whether to show how many posts are
349 * 'hide_empty' (bool|int) default is 1 - Whether to hide categories that
350 * don't have any posts attached to them.
351 * 'child_of' (int) default is 0 - See {@link get_categories()}.
352 * 'exclude' (string) - See {@link get_categories()}.
353 * 'echo' (bool|int) default is 1 - Whether to display or retrieve content.
354 * 'depth' (int) - The max depth.
355 * 'tab_index' (int) - Tab index for select element.
356 * 'name' (string) - The name attribute value for selected element.
357 * 'class' (string) - The class attribute value for selected element.
358 * 'selected' (int) - Which category ID is selected.
360 * The 'hierarchical' argument, which is disabled by default, will override the
361 * depth argument, unless it is true. When the argument is false, it will
362 * display all of the categories. When it is enabled it will use the value in
363 * the 'depth' argument.
367 * @param string|array $args Optional. Override default arguments.
368 * @return string HTML content only if 'echo' argument is 0.
370 function wp_dropdown_categories( $args = '' ) {
372 'show_option_all' => '', 'show_option_none' => '',
373 'orderby' => 'ID', 'order' => 'ASC',
374 'show_last_update' => 0, 'show_count' => 0,
375 'hide_empty' => 1, 'child_of' => 0,
376 'exclude' => '', 'echo' => 1,
377 'selected' => 0, 'hierarchical' => 0,
378 'name' => 'cat', 'class' => 'postform',
379 'depth' => 0, 'tab_index' => 0
382 $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
384 $r = wp_parse_args( $args, $defaults );
385 $r['include_last_update_time'] = $r['show_last_update'];
388 $tab_index_attribute = '';
389 if ( (int) $tab_index > 0 )
390 $tab_index_attribute = " tabindex=\"$tab_index\"";
392 $categories = get_categories( $r );
395 if ( ! empty( $categories ) ) {
396 $output = "<select name='$name' id='$name' class='$class' $tab_index_attribute>\n";
398 if ( $show_option_all ) {
399 $show_option_all = apply_filters( 'list_cats', $show_option_all );
400 $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
401 $output .= "\t<option value='0'$selected>$show_option_all</option>\n";
404 if ( $show_option_none ) {
405 $show_option_none = apply_filters( 'list_cats', $show_option_none );
406 $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
407 $output .= "\t<option value='-1'$selected>$show_option_none</option>\n";
411 $depth = $r['depth']; // Walk the full depth.
413 $depth = -1; // Flat.
415 $output .= walk_category_dropdown_tree( $categories, $depth, $r );
416 $output .= "</select>\n";
419 $output = apply_filters( 'wp_dropdown_cats', $output );
428 * Display or retrieve the HTML list of categories.
430 * The list of arguments is below:
431 * 'show_option_all' (string) - Text to display for showing all categories.
432 * 'orderby' (string) default is 'ID' - What column to use for ordering the
434 * 'order' (string) default is 'ASC' - What direction to order categories.
435 * 'show_last_update' (bool|int) default is 0 - See {@link
436 * walk_category_dropdown_tree()}
437 * 'show_count' (bool|int) default is 0 - Whether to show how many posts are
439 * 'hide_empty' (bool|int) default is 1 - Whether to hide categories that
440 * don't have any posts attached to them.
441 * 'use_desc_for_title' (bool|int) default is 1 - Whether to use the
442 * description instead of the category title.
443 * 'feed' - See {@link get_categories()}.
444 * 'feed_type' - See {@link get_categories()}.
445 * 'feed_image' - See {@link get_categories()}.
446 * 'child_of' (int) default is 0 - See {@link get_categories()}.
447 * 'exclude' (string) - See {@link get_categories()}.
448 * 'exclude_tree' (string) - See {@link get_categories()}.
449 * 'echo' (bool|int) default is 1 - Whether to display or retrieve content.
450 * 'current_category' (int) - See {@link get_categories()}.
451 * 'hierarchical' (bool) - See {@link get_categories()}.
452 * 'title_li' (string) - See {@link get_categories()}.
453 * 'depth' (int) - The max depth.
457 * @param string|array $args Optional. Override default arguments.
458 * @return string HTML content only if 'echo' argument is 0.
460 function wp_list_categories( $args = '' ) {
462 'show_option_all' => '', 'orderby' => 'name',
463 'order' => 'ASC', 'show_last_update' => 0,
464 'style' => 'list', 'show_count' => 0,
465 'hide_empty' => 1, 'use_desc_for_title' => 1,
466 'child_of' => 0, 'feed' => '', 'feed_type' => '',
467 'feed_image' => '', 'exclude' => '', 'exclude_tree' => '', 'current_category' => 0,
468 'hierarchical' => true, 'title_li' => __( 'Categories' ),
469 'echo' => 1, 'depth' => 0
472 $r = wp_parse_args( $args, $defaults );
474 if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
475 $r['pad_counts'] = true;
478 if ( isset( $r['show_date'] ) ) {
479 $r['include_last_update_time'] = $r['show_date'];
482 if ( true == $r['hierarchical'] ) {
483 $r['exclude_tree'] = $r['exclude'];
489 $categories = get_categories( $r );
492 if ( $title_li && 'list' == $style )
493 $output = '<li class="categories">' . $r['title_li'] . '<ul>';
495 if ( empty( $categories ) ) {
496 if ( 'list' == $style )
497 $output .= '<li>' . __( "No categories" ) . '</li>';
499 $output .= __( "No categories" );
503 if( !empty( $show_option_all ) )
504 if ( 'list' == $style )
505 $output .= '<li><a href="' . get_bloginfo( 'url' ) . '">' . $show_option_all . '</a></li>';
507 $output .= '<a href="' . get_bloginfo( 'url' ) . '">' . $show_option_all . '</a>';
509 if ( empty( $r['current_category'] ) && is_category() )
510 $r['current_category'] = $wp_query->get_queried_object_id();
513 $depth = $r['depth'];
515 $depth = -1; // Flat.
517 $output .= walk_category_tree( $categories, $depth, $r );
520 if ( $title_li && 'list' == $style )
521 $output .= '</ul></li>';
523 $output = apply_filters( 'wp_list_categories', $output );
534 * The text size is set by the 'smallest' and 'largest' arguments, which will
535 * use the 'unit' argument value for the CSS text size unit. The 'format'
536 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
537 * 'format' argument will separate tags with spaces. The list value for the
538 * 'format' argument will format the tags in a UL HTML list. The array value for
539 * the 'format' argument will return in PHP array type format.
541 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
542 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
544 * The 'number' argument is how many tags to return. By default, the limit will
545 * be to return the top 45 tags in the tag cloud list.
547 * The 'topic_count_text_callback' argument is a function, which, given the count
548 * of the posts with that tag, returns a text for the tooltip of the tag link.
550 * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
551 * function. Only one should be used, because only one will be used and the
552 * other ignored, if they are both set.
556 * @param array|string $args Optional. Override default arguments.
557 * @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
559 function wp_tag_cloud( $args = '' ) {
561 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
562 'format' => 'flat', 'orderby' => 'name', 'order' => 'ASC',
563 'exclude' => '', 'include' => '', 'link' => 'view'
565 $args = wp_parse_args( $args, $defaults );
567 $tags = get_tags( array_merge( $args, array( 'orderby' => 'count', 'order' => 'DESC' ) ) ); // Always query top tags
569 if ( empty( $tags ) )
572 foreach ( $tags as $key => $tag ) {
573 if ( 'edit' == $args['link'] )
574 $link = get_edit_tag_link( $tag->term_id );
576 $link = get_tag_link( $tag->term_id );
577 if ( is_wp_error( $link ) )
580 $tags[ $key ]->link = $link;
581 $tags[ $key ]->id = $tag->term_id;
584 $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
586 $return = apply_filters( 'wp_tag_cloud', $return, $args );
588 if ( 'array' == $args['format'] )
595 * Default text for tooltip for tag links
597 * @param integer $count number of posts with that tag
598 * @return string text for the tooltip of a tag link.
600 function default_topic_count_text( $count ) {
601 return sprintf( __ngettext('%s topic', '%s topics', $count), number_format_i18n( $count ) );
605 * Generates a tag cloud (heatmap) from provided data.
607 * The text size is set by the 'smallest' and 'largest' arguments, which will
608 * use the 'unit' argument value for the CSS text size unit. The 'format'
609 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
610 * 'format' argument will separate tags with spaces. The list value for the
611 * 'format' argument will format the tags in a UL HTML list. The array value for
612 * the 'format' argument will return in PHP array type format.
614 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
615 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or
618 * The 'number' argument is how many tags to return. By default, the limit will
619 * be to return the entire tag cloud list.
621 * The 'topic_count_text_callback' argument is a function, which given the count
622 * of the posts with that tag returns a text for the tooltip of the tag link.
624 * @todo Complete functionality.
627 * @param array $tags List of tags.
628 * @param string|array $args Optional, override default arguments.
631 function wp_generate_tag_cloud( $tags, $args = '' ) {
634 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0,
635 'format' => 'flat', 'orderby' => 'name', 'order' => 'ASC',
636 'topic_count_text_callback' => 'default_topic_count_text',
639 if ( !isset( $args['topic_count_text_callback'] ) && isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
640 $body = 'return sprintf (
641 __ngettext('.var_export($args['single_text'], true).', '.var_export($args['multiple_text'], true).', $count),
642 number_format_i18n( $count ));';
643 $args['topic_count_text_callback'] = create_function('$count', $body);
646 $args = wp_parse_args( $args, $defaults );
650 if ( empty( $tags ) )
653 // SQL cannot save you; this is a second (potentially different) sort on a subset of data.
654 if ( 'name' == $orderby )
655 uasort( $tags, create_function('$a, $b', 'return strnatcasecmp($a->name, $b->name);') );
657 uasort( $tags, create_function('$a, $b', 'return ($a->count > $b->count);') );
659 if ( 'DESC' == $order )
660 $tags = array_reverse( $tags, true );
661 elseif ( 'RAND' == $order ) {
662 $keys = array_rand( $tags, count( $tags ) );
663 foreach ( $keys as $key )
664 $temp[$key] = $tags[$key];
670 $tags = array_slice($tags, 0, $number);
673 foreach ( (array) $tags as $key => $tag )
674 $counts[ $key ] = $tag->count;
676 $min_count = min( $counts );
677 $spread = max( $counts ) - $min_count;
680 $font_spread = $largest - $smallest;
681 if ( $font_spread < 0 )
683 $font_step = $font_spread / $spread;
687 $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? ' rel="tag"' : '';
689 foreach ( $tags as $key => $tag ) {
690 $count = $counts[ $key ];
691 $tag_link = '#' != $tag->link ? clean_url( $tag->link ) : '#';
692 $tag_id = isset($tags[ $key ]->id) ? $tags[ $key ]->id : $key;
693 $tag_name = $tags[ $key ]->name;
694 $a[] = "<a href='$tag_link' class='tag-link-$tag_id' title='" . attribute_escape( $topic_count_text_callback( $count ) ) . "'$rel style='font-size: " .
695 ( $smallest + ( ( $count - $min_count ) * $font_step ) )
696 . "$unit;'>$tag_name</a>";
704 $return = "<ul class='wp-tag-cloud'>\n\t<li>";
705 $return .= join( "</li>\n\t<li>", $a );
706 $return .= "</li>\n</ul>\n";
709 $return = join( "\n", $a );
713 return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
721 * Retrieve HTML list content for category list.
723 * @uses Walker_Category to create HTML list content.
725 * @see Walker_Category::walk() for parameters and return description.
727 function walk_category_tree() {
728 $args = func_get_args();
729 // the user's options are the third parameter
730 if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
731 $walker = new Walker_Category;
733 $walker = $args[2]['walker'];
735 return call_user_func_array(array( &$walker, 'walk' ), $args );
739 * Retrieve HTML dropdown (select) content for category list.
741 * @uses Walker_CategoryDropdown to create HTML dropdown content.
743 * @see Walker_CategoryDropdown::walk() for parameters and return description.
745 function walk_category_dropdown_tree() {
746 $args = func_get_args();
747 // the user's options are the third parameter
748 if ( empty($args[2]['walker']) || !is_a($args[2]['walker'], 'Walker') )
749 $walker = new Walker_CategoryDropdown;
751 $walker = $args[2]['walker'];
753 return call_user_func_array(array( &$walker, 'walk' ), $args );
761 * Retrieve the link to the tag.
764 * @uses apply_filters() Calls 'tag_link' with tag link and tag ID as parameters.
766 * @param int $tag_id Tag (term) ID.
769 function get_tag_link( $tag_id ) {
771 $taglink = $wp_rewrite->get_tag_permastruct();
773 $tag = &get_term( $tag_id, 'post_tag' );
774 if ( is_wp_error( $tag ) )
778 if ( empty( $taglink ) ) {
779 $file = get_option( 'home' ) . '/';
780 $taglink = $file . '?tag=' . $slug;
782 $taglink = str_replace( '%tag%', $slug, $taglink );
783 $taglink = get_option( 'home' ) . user_trailingslashit( $taglink, 'category' );
785 return apply_filters( 'tag_link', $taglink, $tag_id );
789 * Retrieve the tags for a post.
792 * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
794 * @param int $id Post ID.
797 function get_the_tags( $id = 0 ) {
798 return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
802 * Retrieve the tags for a post formatted as a string.
805 * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
807 * @param string $before Optional. Before tags.
808 * @param string $sep Optional. Between tags.
809 * @param string $after Optional. After tags.
812 function get_the_tag_list( $before = '', $sep = '', $after = '' ) {
813 return apply_filters( 'the_tags', get_the_term_list( 0, 'post_tag', $before, $sep, $after ) );
817 * Retrieve the tags for a post.
821 * @param string $before Optional. Before list.
822 * @param string $sep Optional. Separate items using this.
823 * @param string $after Optional. After list.
826 function the_tags( $before = 'Tags: ', $sep = ', ', $after = '' ) {
827 return the_terms( 0, 'post_tag', $before, $sep, $after );
831 * Retrieve the terms of the taxonomy that are attached to the post.
833 * This function can only be used within the loop.
837 * @param int $id Post ID. Is not optional.
838 * @param string $taxonomy Taxonomy name.
839 * @return array|bool False on failure. Array of term objects on success.
841 function get_the_terms( $id = 0, $taxonomy ) {
846 if ( ! $id && ! in_the_loop() )
847 return false; // in-the-loop function
850 $id = (int) $post->ID;
852 $terms = get_object_term_cache( $id, $taxonomy );
853 if ( false === $terms )
854 $terms = wp_get_object_terms( $id, $taxonomy );
856 if ( empty( $terms ) )
863 * Retrieve terms as a list with specified format.
867 * @param int $id Term ID.
868 * @param string $taxonomy Taxonomy name.
869 * @param string $before Optional. Before list.
870 * @param string $sep Optional. Separate items using this.
871 * @param string $after Optional. After list.
874 function get_the_term_list( $id = 0, $taxonomy, $before = '', $sep = '', $after = '' ) {
875 $terms = get_the_terms( $id, $taxonomy );
877 if ( is_wp_error( $terms ) )
880 if ( empty( $terms ) )
883 foreach ( $terms as $term ) {
884 $link = get_term_link( $term, $taxonomy );
885 if ( is_wp_error( $link ) )
887 $term_links[] = '<a href="' . $link . '" rel="tag">' . $term->name . '</a>';
890 $term_links = apply_filters( "term_links-$taxonomy", $term_links );
892 return $before . join( $sep, $term_links ) . $after;
896 * Display the terms in a list.
900 * @param int $id Term ID.
901 * @param string $taxonomy Taxonomy name.
902 * @param string $before Optional. Before list.
903 * @param string $sep Optional. Separate items using this.
904 * @param string $after Optional. After list.
905 * @return null|bool False on WordPress error. Returns null when displaying.
907 function the_terms( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
908 $return = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
909 if ( is_wp_error( $return ) )
916 * Check if the current post has any of given tags.
918 * The given tags are checked against the post's tags' term_ids, names and slugs.
919 * Tags given as integers will only be checked against the post's tags' term_ids.
920 * If no tags are given, determines if post has any tags.
922 * 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)
923 * Prior to v2.7, this function could only be used in the WordPress Loop.
924 * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
928 * @uses is_object_in_term()
930 * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for.
931 * @param int|post object Optional. Post to check instead of the current post. @since 2.7.0
932 * @return bool True if the current post has any of the the given tags (or any tag, if no tag specified).
934 function has_tag( $tag = '', $_post = null ) {
936 $_post = get_post( $_post );
938 $_post =& $GLOBALS['post'];
944 $r = is_object_in_term( $_post->ID, 'post_tag', $tag );
945 if ( is_wp_error( $r ) )