PageRenderTime 48ms CodeModel.GetById 17ms RepoModel.GetById 1ms app.codeStats 0ms

/wp-includes/category-template.php

https://gitlab.com/geyson/geyson
PHP | 1517 lines | 632 code | 164 blank | 721 comment | 171 complexity | ac9229ff90cca16f11fef19dbd3f2f27 MD5 | raw file
Possible License(s): LGPL-2.1, GPL-2.0
  1. <?php
  2. /**
  3. * Category Template Tags and API.
  4. *
  5. * @package WordPress
  6. * @subpackage Template
  7. */
  8. /**
  9. * Retrieve category link URL.
  10. *
  11. * @since 1.0.0
  12. * @see get_term_link()
  13. *
  14. * @param int|object $category Category ID or object.
  15. * @return string Link on success, empty string if category does not exist.
  16. */
  17. function get_category_link( $category ) {
  18. if ( ! is_object( $category ) )
  19. $category = (int) $category;
  20. $category = get_term_link( $category, 'category' );
  21. if ( is_wp_error( $category ) )
  22. return '';
  23. return $category;
  24. }
  25. /**
  26. * Retrieve category parents with separator.
  27. *
  28. * @since 1.2.0
  29. *
  30. * @param int $id Category ID.
  31. * @param bool $link Optional, default is false. Whether to format with link.
  32. * @param string $separator Optional, default is '/'. How to separate categories.
  33. * @param bool $nicename Optional, default is false. Whether to use nice name for display.
  34. * @param array $visited Optional. Already linked to categories to prevent duplicates.
  35. * @return string|WP_Error A list of category parents on success, WP_Error on failure.
  36. */
  37. function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) {
  38. $chain = '';
  39. $parent = get_term( $id, 'category' );
  40. if ( is_wp_error( $parent ) )
  41. return $parent;
  42. if ( $nicename )
  43. $name = $parent->slug;
  44. else
  45. $name = $parent->name;
  46. if ( $parent->parent && ( $parent->parent != $parent->term_id ) && !in_array( $parent->parent, $visited ) ) {
  47. $visited[] = $parent->parent;
  48. $chain .= get_category_parents( $parent->parent, $link, $separator, $nicename, $visited );
  49. }
  50. if ( $link )
  51. $chain .= '<a href="' . esc_url( get_category_link( $parent->term_id ) ) . '">'.$name.'</a>' . $separator;
  52. else
  53. $chain .= $name.$separator;
  54. return $chain;
  55. }
  56. /**
  57. * Retrieve post categories.
  58. *
  59. * This tag may be used outside The Loop by passing a post id as the parameter.
  60. *
  61. * Note: This function only returns results from the default "category" taxonomy.
  62. * For custom taxonomies use get_the_terms().
  63. *
  64. * @since 0.71
  65. *
  66. * @param int $id Optional, default to current post ID. The post ID.
  67. * @return array Array of objects, one for each category assigned to the post.
  68. */
  69. function get_the_category( $id = false ) {
  70. $categories = get_the_terms( $id, 'category' );
  71. if ( ! $categories || is_wp_error( $categories ) )
  72. $categories = array();
  73. $categories = array_values( $categories );
  74. foreach ( array_keys( $categories ) as $key ) {
  75. _make_cat_compat( $categories[$key] );
  76. }
  77. /**
  78. * Filter the array of categories to return for a post.
  79. *
  80. * @since 3.1.0
  81. *
  82. * @param array $categories An array of categories to return for the post.
  83. */
  84. return apply_filters( 'get_the_categories', $categories );
  85. }
  86. /**
  87. * Sort categories by name.
  88. *
  89. * Used by usort() as a callback, should not be used directly. Can actually be
  90. * used to sort any term object.
  91. *
  92. * @since 2.3.0
  93. * @access private
  94. *
  95. * @param object $a
  96. * @param object $b
  97. * @return int
  98. */
  99. function _usort_terms_by_name( $a, $b ) {
  100. return strcmp( $a->name, $b->name );
  101. }
  102. /**
  103. * Sort categories by ID.
  104. *
  105. * Used by usort() as a callback, should not be used directly. Can actually be
  106. * used to sort any term object.
  107. *
  108. * @since 2.3.0
  109. * @access private
  110. *
  111. * @param object $a
  112. * @param object $b
  113. * @return int
  114. */
  115. function _usort_terms_by_ID( $a, $b ) {
  116. if ( $a->term_id > $b->term_id )
  117. return 1;
  118. elseif ( $a->term_id < $b->term_id )
  119. return -1;
  120. else
  121. return 0;
  122. }
  123. /**
  124. * Retrieve category name based on category ID.
  125. *
  126. * @since 0.71
  127. *
  128. * @param int $cat_ID Category ID.
  129. * @return string|WP_Error Category name on success, WP_Error on failure.
  130. */
  131. function get_the_category_by_ID( $cat_ID ) {
  132. $cat_ID = (int) $cat_ID;
  133. $category = get_term( $cat_ID, 'category' );
  134. if ( is_wp_error( $category ) )
  135. return $category;
  136. return ( $category ) ? $category->name : '';
  137. }
  138. /**
  139. * Retrieve category list in either HTML list or custom format.
  140. *
  141. * @since 1.5.1
  142. *
  143. * @global WP_Rewrite $wp_rewrite
  144. *
  145. * @param string $separator Optional, default is empty string. Separator for between the categories.
  146. * @param string $parents Optional. How to display the parents.
  147. * @param int $post_id Optional. Post ID to retrieve categories.
  148. * @return string
  149. */
  150. function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
  151. global $wp_rewrite;
  152. if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
  153. /** This filter is documented in wp-includes/category-template.php */
  154. return apply_filters( 'the_category', '', $separator, $parents );
  155. }
  156. $categories = get_the_category( $post_id );
  157. if ( empty( $categories ) ) {
  158. /** This filter is documented in wp-includes/category-template.php */
  159. return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
  160. }
  161. $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
  162. $thelist = '';
  163. if ( '' == $separator ) {
  164. $thelist .= '<ul class="post-categories">';
  165. foreach ( $categories as $category ) {
  166. $thelist .= "\n\t<li>";
  167. switch ( strtolower( $parents ) ) {
  168. case 'multiple':
  169. if ( $category->parent )
  170. $thelist .= get_category_parents( $category->parent, true, $separator );
  171. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a></li>';
  172. break;
  173. case 'single':
  174. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
  175. if ( $category->parent )
  176. $thelist .= get_category_parents( $category->parent, false, $separator );
  177. $thelist .= $category->name.'</a></li>';
  178. break;
  179. case '':
  180. default:
  181. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a></li>';
  182. }
  183. }
  184. $thelist .= '</ul>';
  185. } else {
  186. $i = 0;
  187. foreach ( $categories as $category ) {
  188. if ( 0 < $i )
  189. $thelist .= $separator;
  190. switch ( strtolower( $parents ) ) {
  191. case 'multiple':
  192. if ( $category->parent )
  193. $thelist .= get_category_parents( $category->parent, true, $separator );
  194. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a>';
  195. break;
  196. case 'single':
  197. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
  198. if ( $category->parent )
  199. $thelist .= get_category_parents( $category->parent, false, $separator );
  200. $thelist .= "$category->name</a>";
  201. break;
  202. case '':
  203. default:
  204. $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a>';
  205. }
  206. ++$i;
  207. }
  208. }
  209. /**
  210. * Filter the category or list of categories.
  211. *
  212. * @since 1.2.0
  213. *
  214. * @param array $thelist List of categories for the current post.
  215. * @param string $separator Separator used between the categories.
  216. * @param string $parents How to display the category parents. Accepts 'multiple',
  217. * 'single', or empty.
  218. */
  219. return apply_filters( 'the_category', $thelist, $separator, $parents );
  220. }
  221. /**
  222. * Check if the current post in within any of the given categories.
  223. *
  224. * The given categories are checked against the post's categories' term_ids, names and slugs.
  225. * Categories given as integers will only be checked against the post's categories' term_ids.
  226. *
  227. * Prior to v2.5 of WordPress, category names were not supported.
  228. * Prior to v2.7, category slugs were not supported.
  229. * Prior to v2.7, only one category could be compared: in_category( $single_category ).
  230. * Prior to v2.7, this function could only be used in the WordPress Loop.
  231. * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
  232. *
  233. * @since 1.2.0
  234. *
  235. * @param int|string|array $category Category ID, name or slug, or array of said.
  236. * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0)
  237. * @return bool True if the current post is in any of the given categories.
  238. */
  239. function in_category( $category, $post = null ) {
  240. if ( empty( $category ) )
  241. return false;
  242. return has_category( $category, $post );
  243. }
  244. /**
  245. * Display the category list for the post.
  246. *
  247. * @since 0.71
  248. *
  249. * @param string $separator Optional, default is empty string. Separator for between the categories.
  250. * @param string $parents Optional. How to display the parents.
  251. * @param int $post_id Optional. Post ID to retrieve categories.
  252. */
  253. function the_category( $separator = '', $parents='', $post_id = false ) {
  254. echo get_the_category_list( $separator, $parents, $post_id );
  255. }
  256. /**
  257. * Retrieve category description.
  258. *
  259. * @since 1.0.0
  260. *
  261. * @param int $category Optional. Category ID. Will use global category ID by default.
  262. * @return string Category description, available.
  263. */
  264. function category_description( $category = 0 ) {
  265. return term_description( $category, 'category' );
  266. }
  267. /**
  268. * Display or retrieve the HTML dropdown list of categories.
  269. *
  270. * The 'hierarchical' argument, which is disabled by default, will override the
  271. * depth argument, unless it is true. When the argument is false, it will
  272. * display all of the categories. When it is enabled it will use the value in
  273. * the 'depth' argument.
  274. *
  275. * @since 2.1.0
  276. * @since 4.2.0 Introduced the `value_field` argument.
  277. *
  278. * @param string|array $args {
  279. * Optional. Array or string of arguments to generate a categories drop-down element.
  280. *
  281. * @type string $show_option_all Text to display for showing all categories. Default empty.
  282. * @type string $show_option_none Text to display for showing no categories. Default empty.
  283. * @type string $option_none_value Value to use when no category is selected. Default empty.
  284. * @type string $orderby Which column to use for ordering categories. See get_terms() for a list
  285. * of accepted values. Default 'id' (term_id).
  286. * @type string $order Whether to order terms in ascending or descending order. Accepts 'ASC'
  287. * or 'DESC'. Default 'ASC'.
  288. * @type bool $pad_counts See get_terms() for an argument description. Default false.
  289. * @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents.
  290. * Default 0.
  291. * @type bool|int $hide_empty Whether to hide categories that don't have any posts. Accepts 0, 1, or
  292. * their bool equivalents. Default 1.
  293. * @type int $child_of Term ID to retrieve child terms of. See get_terms(). Default 0.
  294. * @type array|string $exclude Array or comma/space-separated string of term ids to exclude.
  295. * If `$include` is non-empty, `$exclude` is ignored. Default empty array.
  296. * @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
  297. * bool equivalents. Default 1.
  298. * @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool
  299. * equivalents. Default 0.
  300. * @type int $depth Maximum depth. Default 0.
  301. * @type int $tab_index Tab index for the select element. Default 0 (no tabindex).
  302. * @type string $name Value for the 'name' attribute of the select element. Default 'cat'.
  303. * @type string $id Value for the 'id' attribute of the select element. Defaults to the value
  304. * of `$name`.
  305. * @type string $class Value for the 'class' attribute of the select element. Default 'postform'.
  306. * @type int|string $selected Value of the option that should be selected. Default 0.
  307. * @type string $value_field Term field that should be used to populate the 'value' attribute
  308. * of the option elements. Accepts any valid term field: 'term_id', 'name',
  309. * 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description',
  310. * 'parent', 'count'. Default 'term_id'.
  311. * @type string $taxonomy Name of the category to retrieve. Default 'category'.
  312. * @type bool $hide_if_empty True to skip generating markup if no categories are found.
  313. * Default false (create select element even if no categories are found).
  314. * }
  315. * @return string HTML content only if 'echo' argument is 0.
  316. */
  317. function wp_dropdown_categories( $args = '' ) {
  318. $defaults = array(
  319. 'show_option_all' => '', 'show_option_none' => '',
  320. 'orderby' => 'id', 'order' => 'ASC',
  321. 'show_count' => 0,
  322. 'hide_empty' => 1, 'child_of' => 0,
  323. 'exclude' => '', 'echo' => 1,
  324. 'selected' => 0, 'hierarchical' => 0,
  325. 'name' => 'cat', 'id' => '',
  326. 'class' => 'postform', 'depth' => 0,
  327. 'tab_index' => 0, 'taxonomy' => 'category',
  328. 'hide_if_empty' => false, 'option_none_value' => -1,
  329. 'value_field' => 'term_id',
  330. );
  331. $defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
  332. // Back compat.
  333. if ( isset( $args['type'] ) && 'link' == $args['type'] ) {
  334. _deprecated_argument( __FUNCTION__, '3.0', '' );
  335. $args['taxonomy'] = 'link_category';
  336. }
  337. $r = wp_parse_args( $args, $defaults );
  338. $option_none_value = $r['option_none_value'];
  339. if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
  340. $r['pad_counts'] = true;
  341. }
  342. $tab_index = $r['tab_index'];
  343. $tab_index_attribute = '';
  344. if ( (int) $tab_index > 0 ) {
  345. $tab_index_attribute = " tabindex=\"$tab_index\"";
  346. }
  347. // Avoid clashes with the 'name' param of get_terms().
  348. $get_terms_args = $r;
  349. unset( $get_terms_args['name'] );
  350. $categories = get_terms( $r['taxonomy'], $get_terms_args );
  351. $name = esc_attr( $r['name'] );
  352. $class = esc_attr( $r['class'] );
  353. $id = $r['id'] ? esc_attr( $r['id'] ) : $name;
  354. if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) {
  355. $output = "<select name='$name' id='$id' class='$class' $tab_index_attribute>\n";
  356. } else {
  357. $output = '';
  358. }
  359. if ( empty( $categories ) && ! $r['hide_if_empty'] && ! empty( $r['show_option_none'] ) ) {
  360. /**
  361. * Filter a taxonomy drop-down display element.
  362. *
  363. * A variety of taxonomy drop-down display elements can be modified
  364. * just prior to display via this filter. Filterable arguments include
  365. * 'show_option_none', 'show_option_all', and various forms of the
  366. * term name.
  367. *
  368. * @since 1.2.0
  369. *
  370. * @see wp_dropdown_categories()
  371. *
  372. * @param string $element Taxonomy element to list.
  373. */
  374. $show_option_none = apply_filters( 'list_cats', $r['show_option_none'] );
  375. $output .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n";
  376. }
  377. if ( ! empty( $categories ) ) {
  378. if ( $r['show_option_all'] ) {
  379. /** This filter is documented in wp-includes/category-template.php */
  380. $show_option_all = apply_filters( 'list_cats', $r['show_option_all'] );
  381. $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
  382. $output .= "\t<option value='0'$selected>$show_option_all</option>\n";
  383. }
  384. if ( $r['show_option_none'] ) {
  385. /** This filter is documented in wp-includes/category-template.php */
  386. $show_option_none = apply_filters( 'list_cats', $r['show_option_none'] );
  387. $selected = selected( $option_none_value, $r['selected'], false );
  388. $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n";
  389. }
  390. if ( $r['hierarchical'] ) {
  391. $depth = $r['depth']; // Walk the full depth.
  392. } else {
  393. $depth = -1; // Flat.
  394. }
  395. $output .= walk_category_dropdown_tree( $categories, $depth, $r );
  396. }
  397. if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) {
  398. $output .= "</select>\n";
  399. }
  400. /**
  401. * Filter the taxonomy drop-down output.
  402. *
  403. * @since 2.1.0
  404. *
  405. * @param string $output HTML output.
  406. * @param array $r Arguments used to build the drop-down.
  407. */
  408. $output = apply_filters( 'wp_dropdown_cats', $output, $r );
  409. if ( $r['echo'] ) {
  410. echo $output;
  411. }
  412. return $output;
  413. }
  414. /**
  415. * Display or retrieve the HTML list of categories.
  416. *
  417. * The list of arguments is below:
  418. * 'show_option_all' (string) - Text to display for showing all categories.
  419. * 'orderby' (string) default is 'ID' - What column to use for ordering the
  420. * categories.
  421. * 'order' (string) default is 'ASC' - What direction to order categories.
  422. * 'show_count' (bool|int) default is 0 - Whether to show how many posts are
  423. * in the category.
  424. * 'hide_empty' (bool|int) default is 1 - Whether to hide categories that
  425. * don't have any posts attached to them.
  426. * 'use_desc_for_title' (bool|int) default is 1 - Whether to use the
  427. * category description as the title attribute.
  428. * 'feed' - See {@link get_categories()}.
  429. * 'feed_type' - See {@link get_categories()}.
  430. * 'feed_image' - See {@link get_categories()}.
  431. * 'child_of' (int) default is 0 - See {@link get_categories()}.
  432. * 'exclude' (string) - See {@link get_categories()}.
  433. * 'exclude_tree' (string) - See {@link get_categories()}.
  434. * 'echo' (bool|int) default is 1 - Whether to display or retrieve content.
  435. * 'current_category' (int) - See {@link get_categories()}.
  436. * 'hierarchical' (bool) - See {@link get_categories()}.
  437. * 'title_li' (string) - See {@link get_categories()}.
  438. * 'depth' (int) - The max depth.
  439. *
  440. * @since 2.1.0
  441. *
  442. * @param string|array $args Optional. Override default arguments.
  443. * @return false|string HTML content only if 'echo' argument is 0.
  444. */
  445. function wp_list_categories( $args = '' ) {
  446. $defaults = array(
  447. 'show_option_all' => '', 'show_option_none' => __('No categories'),
  448. 'orderby' => 'name', 'order' => 'ASC',
  449. 'style' => 'list',
  450. 'show_count' => 0, 'hide_empty' => 1,
  451. 'use_desc_for_title' => 1, 'child_of' => 0,
  452. 'feed' => '', 'feed_type' => '',
  453. 'feed_image' => '', 'exclude' => '',
  454. 'exclude_tree' => '', 'current_category' => 0,
  455. 'hierarchical' => true, 'title_li' => __( 'Categories' ),
  456. 'echo' => 1, 'depth' => 0,
  457. 'taxonomy' => 'category'
  458. );
  459. $r = wp_parse_args( $args, $defaults );
  460. if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] )
  461. $r['pad_counts'] = true;
  462. if ( true == $r['hierarchical'] ) {
  463. $r['exclude_tree'] = $r['exclude'];
  464. $r['exclude'] = '';
  465. }
  466. if ( ! isset( $r['class'] ) )
  467. $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];
  468. if ( ! taxonomy_exists( $r['taxonomy'] ) ) {
  469. return false;
  470. }
  471. $show_option_all = $r['show_option_all'];
  472. $show_option_none = $r['show_option_none'];
  473. $categories = get_categories( $r );
  474. $output = '';
  475. if ( $r['title_li'] && 'list' == $r['style'] ) {
  476. $output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>';
  477. }
  478. if ( empty( $categories ) ) {
  479. if ( ! empty( $show_option_none ) ) {
  480. if ( 'list' == $r['style'] ) {
  481. $output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
  482. } else {
  483. $output .= $show_option_none;
  484. }
  485. }
  486. } else {
  487. if ( ! empty( $show_option_all ) ) {
  488. $posts_page = '';
  489. // For taxonomies that belong only to custom post types, point to a valid archive.
  490. $taxonomy_object = get_taxonomy( $r['taxonomy'] );
  491. if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) {
  492. foreach ( $taxonomy_object->object_type as $object_type ) {
  493. $_object_type = get_post_type_object( $object_type );
  494. // Grab the first one.
  495. if ( ! empty( $_object_type->has_archive ) ) {
  496. $posts_page = get_post_type_archive_link( $object_type );
  497. break;
  498. }
  499. }
  500. }
  501. // Fallback for the 'All' link is the front page.
  502. if ( ! $posts_page ) {
  503. $posts_page = 'page' == get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ? get_permalink( get_option( 'page_for_posts' ) ) : home_url( '/' );
  504. }
  505. $posts_page = esc_url( $posts_page );
  506. if ( 'list' == $r['style'] ) {
  507. $output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>";
  508. } else {
  509. $output .= "<a href='$posts_page'>$show_option_all</a>";
  510. }
  511. }
  512. if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
  513. $current_term_object = get_queried_object();
  514. if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) {
  515. $r['current_category'] = get_queried_object_id();
  516. }
  517. }
  518. if ( $r['hierarchical'] ) {
  519. $depth = $r['depth'];
  520. } else {
  521. $depth = -1; // Flat.
  522. }
  523. $output .= walk_category_tree( $categories, $depth, $r );
  524. }
  525. if ( $r['title_li'] && 'list' == $r['style'] )
  526. $output .= '</ul></li>';
  527. /**
  528. * Filter the HTML output of a taxonomy list.
  529. *
  530. * @since 2.1.0
  531. *
  532. * @param string $output HTML output.
  533. * @param array $args An array of taxonomy-listing arguments.
  534. */
  535. $html = apply_filters( 'wp_list_categories', $output, $args );
  536. if ( $r['echo'] ) {
  537. echo $html;
  538. } else {
  539. return $html;
  540. }
  541. }
  542. /**
  543. * Display tag cloud.
  544. *
  545. * The text size is set by the 'smallest' and 'largest' arguments, which will
  546. * use the 'unit' argument value for the CSS text size unit. The 'format'
  547. * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
  548. * 'format' argument will separate tags with spaces. The list value for the
  549. * 'format' argument will format the tags in a UL HTML list. The array value for
  550. * the 'format' argument will return in PHP array type format.
  551. *
  552. * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
  553. * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
  554. *
  555. * The 'number' argument is how many tags to return. By default, the limit will
  556. * be to return the top 45 tags in the tag cloud list.
  557. *
  558. * The 'topic_count_text' argument is a nooped plural from _n_noop() to generate the
  559. * text for the tooltip of the tag link.
  560. *
  561. * The 'topic_count_text_callback' argument is a function, which given the count
  562. * of the posts with that tag returns a text for the tooltip of the tag link.
  563. *
  564. * The 'post_type' argument is used only when 'link' is set to 'edit'. It determines the post_type
  565. * passed to edit.php for the popular tags edit links.
  566. *
  567. * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
  568. * function. Only one should be used, because only one will be used and the
  569. * other ignored, if they are both set.
  570. *
  571. * @since 2.3.0
  572. *
  573. * @param array|string|null $args Optional. Override default arguments.
  574. * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
  575. * Otherwise, this function outputs the tag cloud.
  576. */
  577. function wp_tag_cloud( $args = '' ) {
  578. $defaults = array(
  579. 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 45,
  580. 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',
  581. 'exclude' => '', 'include' => '', 'link' => 'view', 'taxonomy' => 'post_tag', 'post_type' => '', 'echo' => true
  582. );
  583. $args = wp_parse_args( $args, $defaults );
  584. $tags = get_terms( $args['taxonomy'], array_merge( $args, array( 'orderby' => 'count', 'order' => 'DESC' ) ) ); // Always query top tags
  585. if ( empty( $tags ) || is_wp_error( $tags ) )
  586. return;
  587. foreach ( $tags as $key => $tag ) {
  588. if ( 'edit' == $args['link'] )
  589. $link = get_edit_term_link( $tag->term_id, $tag->taxonomy, $args['post_type'] );
  590. else
  591. $link = get_term_link( intval($tag->term_id), $tag->taxonomy );
  592. if ( is_wp_error( $link ) )
  593. return;
  594. $tags[ $key ]->link = $link;
  595. $tags[ $key ]->id = $tag->term_id;
  596. }
  597. $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
  598. /**
  599. * Filter the tag cloud output.
  600. *
  601. * @since 2.3.0
  602. *
  603. * @param string $return HTML output of the tag cloud.
  604. * @param array $args An array of tag cloud arguments.
  605. */
  606. $return = apply_filters( 'wp_tag_cloud', $return, $args );
  607. if ( 'array' == $args['format'] || empty($args['echo']) )
  608. return $return;
  609. echo $return;
  610. }
  611. /**
  612. * Default topic count scaling for tag links
  613. *
  614. * @param int $count number of posts with that tag
  615. * @return int scaled count
  616. */
  617. function default_topic_count_scale( $count ) {
  618. return round(log10($count + 1) * 100);
  619. }
  620. /**
  621. * Generates a tag cloud (heatmap) from provided data.
  622. *
  623. * The text size is set by the 'smallest' and 'largest' arguments, which will
  624. * use the 'unit' argument value for the CSS text size unit. The 'format'
  625. * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
  626. * 'format' argument will separate tags with spaces. The list value for the
  627. * 'format' argument will format the tags in a UL HTML list. The array value for
  628. * the 'format' argument will return in PHP array type format.
  629. *
  630. * The 'tag_cloud_sort' filter allows you to override the sorting.
  631. * Passed to the filter: $tags array and $args array, has to return the $tags array
  632. * after sorting it.
  633. *
  634. * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
  635. * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or
  636. * 'RAND'.
  637. *
  638. * The 'number' argument is how many tags to return. By default, the limit will
  639. * be to return the entire tag cloud list.
  640. *
  641. * The 'topic_count_text' argument is a nooped plural from _n_noop() to generate the
  642. * text for the tooltip of the tag link.
  643. *
  644. * The 'topic_count_text_callback' argument is a function, which given the count
  645. * of the posts with that tag returns a text for the tooltip of the tag link.
  646. *
  647. * @todo Complete functionality.
  648. * @since 2.3.0
  649. *
  650. * @param array $tags List of tags.
  651. * @param string|array $args Optional, override default arguments.
  652. * @return string|array Tag cloud as a string or an array, depending on 'format' argument.
  653. */
  654. function wp_generate_tag_cloud( $tags, $args = '' ) {
  655. $defaults = array(
  656. 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0,
  657. 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',
  658. 'topic_count_text' => null, 'topic_count_text_callback' => null,
  659. 'topic_count_scale_callback' => 'default_topic_count_scale', 'filter' => 1,
  660. );
  661. $args = wp_parse_args( $args, $defaults );
  662. $return = ( 'array' === $args['format'] ) ? array() : '';
  663. if ( empty( $tags ) ) {
  664. return $return;
  665. }
  666. // Juggle topic count tooltips:
  667. if ( isset( $args['topic_count_text'] ) ) {
  668. // First look for nooped plural support via topic_count_text.
  669. $translate_nooped_plural = $args['topic_count_text'];
  670. } elseif ( ! empty( $args['topic_count_text_callback'] ) ) {
  671. // Look for the alternative callback style. Ignore the previous default.
  672. if ( $args['topic_count_text_callback'] === 'default_topic_count_text' ) {
  673. $translate_nooped_plural = _n_noop( '%s topic', '%s topics' );
  674. } else {
  675. $translate_nooped_plural = false;
  676. }
  677. } elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
  678. // If no callback exists, look for the old-style single_text and multiple_text arguments.
  679. $translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] );
  680. } else {
  681. // This is the default for when no callback, plural, or argument is passed in.
  682. $translate_nooped_plural = _n_noop( '%s topic', '%s topics' );
  683. }
  684. /**
  685. * Filter how the items in a tag cloud are sorted.
  686. *
  687. * @since 2.8.0
  688. *
  689. * @param array $tags Ordered array of terms.
  690. * @param array $args An array of tag cloud arguments.
  691. */
  692. $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
  693. if ( empty( $tags_sorted ) ) {
  694. return $return;
  695. }
  696. if ( $tags_sorted !== $tags ) {
  697. $tags = $tags_sorted;
  698. unset( $tags_sorted );
  699. } else {
  700. if ( 'RAND' === $args['order'] ) {
  701. shuffle( $tags );
  702. } else {
  703. // SQL cannot save you; this is a second (potentially different) sort on a subset of data.
  704. if ( 'name' === $args['orderby'] ) {
  705. uasort( $tags, '_wp_object_name_sort_cb' );
  706. } else {
  707. uasort( $tags, '_wp_object_count_sort_cb' );
  708. }
  709. if ( 'DESC' === $args['order'] ) {
  710. $tags = array_reverse( $tags, true );
  711. }
  712. }
  713. }
  714. if ( $args['number'] > 0 )
  715. $tags = array_slice( $tags, 0, $args['number'] );
  716. $counts = array();
  717. $real_counts = array(); // For the alt tag
  718. foreach ( (array) $tags as $key => $tag ) {
  719. $real_counts[ $key ] = $tag->count;
  720. $counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count );
  721. }
  722. $min_count = min( $counts );
  723. $spread = max( $counts ) - $min_count;
  724. if ( $spread <= 0 )
  725. $spread = 1;
  726. $font_spread = $args['largest'] - $args['smallest'];
  727. if ( $font_spread < 0 )
  728. $font_spread = 1;
  729. $font_step = $font_spread / $spread;
  730. // Assemble the data that will be used to generate the tag cloud markup.
  731. $tags_data = array();
  732. foreach ( $tags as $key => $tag ) {
  733. $tag_id = isset( $tag->id ) ? $tag->id : $key;
  734. $count = $counts[ $key ];
  735. $real_count = $real_counts[ $key ];
  736. if ( $translate_nooped_plural ) {
  737. $title = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) );
  738. } else {
  739. $title = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args );
  740. }
  741. $tags_data[] = array(
  742. 'id' => $tag_id,
  743. 'url' => '#' != $tag->link ? $tag->link : '#',
  744. 'name' => $tag->name,
  745. 'title' => $title,
  746. 'slug' => $tag->slug,
  747. 'real_count' => $real_count,
  748. 'class' => 'tag-link-' . $tag_id,
  749. 'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step,
  750. );
  751. }
  752. /**
  753. * Filter the data used to generate the tag cloud.
  754. *
  755. * @since 4.3.0
  756. *
  757. * @param array $tags_data An array of term data for term used to generate the tag cloud.
  758. */
  759. $tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data );
  760. $a = array();
  761. // generate the output links array
  762. foreach ( $tags_data as $key => $tag_data ) {
  763. $a[] = "<a href='" . esc_url( $tag_data['url'] ) . "' class='" . esc_attr( $tag_data['class'] ) . "' title='" . esc_attr( $tag_data['title'] ) . "' style='font-size: " . esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ) . ";'>" . esc_html( $tag_data['name'] ) . "</a>";
  764. }
  765. switch ( $args['format'] ) {
  766. case 'array' :
  767. $return =& $a;
  768. break;
  769. case 'list' :
  770. $return = "<ul class='wp-tag-cloud'>\n\t<li>";
  771. $return .= join( "</li>\n\t<li>", $a );
  772. $return .= "</li>\n</ul>\n";
  773. break;
  774. default :
  775. $return = join( $args['separator'], $a );
  776. break;
  777. }
  778. if ( $args['filter'] ) {
  779. /**
  780. * Filter the generated output of a tag cloud.
  781. *
  782. * The filter is only evaluated if a true value is passed
  783. * to the $filter argument in wp_generate_tag_cloud().
  784. *
  785. * @since 2.3.0
  786. *
  787. * @see wp_generate_tag_cloud()
  788. *
  789. * @param array|string $return String containing the generated HTML tag cloud output
  790. * or an array of tag links if the 'format' argument
  791. * equals 'array'.
  792. * @param array $tags An array of terms used in the tag cloud.
  793. * @param array $args An array of wp_generate_tag_cloud() arguments.
  794. */
  795. return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
  796. }
  797. else
  798. return $return;
  799. }
  800. /**
  801. * Callback for comparing objects based on name
  802. *
  803. * @since 3.1.0
  804. * @access private
  805. * @return int
  806. */
  807. function _wp_object_name_sort_cb( $a, $b ) {
  808. return strnatcasecmp( $a->name, $b->name );
  809. }
  810. /**
  811. * Callback for comparing objects based on count
  812. *
  813. * @since 3.1.0
  814. * @access private
  815. * @return bool
  816. */
  817. function _wp_object_count_sort_cb( $a, $b ) {
  818. return ( $a->count > $b->count );
  819. }
  820. //
  821. // Helper functions
  822. //
  823. /**
  824. * Retrieve HTML list content for category list.
  825. *
  826. * @uses Walker_Category to create HTML list content.
  827. * @since 2.1.0
  828. * @see Walker_Category::walk() for parameters and return description.
  829. * @return string
  830. */
  831. function walk_category_tree() {
  832. $args = func_get_args();
  833. // the user's options are the third parameter
  834. if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
  835. $walker = new Walker_Category;
  836. } else {
  837. $walker = $args[2]['walker'];
  838. }
  839. return call_user_func_array( array( $walker, 'walk' ), $args );
  840. }
  841. /**
  842. * Retrieve HTML dropdown (select) content for category list.
  843. *
  844. * @uses Walker_CategoryDropdown to create HTML dropdown content.
  845. * @since 2.1.0
  846. * @see Walker_CategoryDropdown::walk() for parameters and return description.
  847. * @return string
  848. */
  849. function walk_category_dropdown_tree() {
  850. $args = func_get_args();
  851. // the user's options are the third parameter
  852. if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
  853. $walker = new Walker_CategoryDropdown;
  854. } else {
  855. $walker = $args[2]['walker'];
  856. }
  857. return call_user_func_array( array( $walker, 'walk' ), $args );
  858. }
  859. /**
  860. * Create HTML list of categories.
  861. *
  862. * @package WordPress
  863. * @since 2.1.0
  864. * @uses Walker
  865. */
  866. class Walker_Category extends Walker {
  867. /**
  868. * What the class handles.
  869. *
  870. * @see Walker::$tree_type
  871. * @since 2.1.0
  872. * @var string
  873. */
  874. public $tree_type = 'category';
  875. /**
  876. * Database fields to use.
  877. *
  878. * @see Walker::$db_fields
  879. * @since 2.1.0
  880. * @todo Decouple this
  881. * @var array
  882. */
  883. public $db_fields = array ('parent' => 'parent', 'id' => 'term_id');
  884. /**
  885. * Starts the list before the elements are added.
  886. *
  887. * @see Walker::start_lvl()
  888. *
  889. * @since 2.1.0
  890. *
  891. * @param string $output Passed by reference. Used to append additional content.
  892. * @param int $depth Depth of category. Used for tab indentation.
  893. * @param array $args An array of arguments. Will only append content if style argument value is 'list'.
  894. * @see wp_list_categories()
  895. */
  896. public function start_lvl( &$output, $depth = 0, $args = array() ) {
  897. if ( 'list' != $args['style'] )
  898. return;
  899. $indent = str_repeat("\t", $depth);
  900. $output .= "$indent<ul class='children'>\n";
  901. }
  902. /**
  903. * Ends the list of after the elements are added.
  904. *
  905. * @see Walker::end_lvl()
  906. *
  907. * @since 2.1.0
  908. *
  909. * @param string $output Passed by reference. Used to append additional content.
  910. * @param int $depth Depth of category. Used for tab indentation.
  911. * @param array $args An array of arguments. Will only append content if style argument value is 'list'.
  912. * @wsee wp_list_categories()
  913. */
  914. public function end_lvl( &$output, $depth = 0, $args = array() ) {
  915. if ( 'list' != $args['style'] )
  916. return;
  917. $indent = str_repeat("\t", $depth);
  918. $output .= "$indent</ul>\n";
  919. }
  920. /**
  921. * Start the element output.
  922. *
  923. * @see Walker::start_el()
  924. *
  925. * @since 2.1.0
  926. *
  927. * @param string $output Passed by reference. Used to append additional content.
  928. * @param object $category Category data object.
  929. * @param int $depth Depth of category in reference to parents. Default 0.
  930. * @param array $args An array of arguments. @see wp_list_categories()
  931. * @param int $id ID of the current category.
  932. */
  933. public function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
  934. /** This filter is documented in wp-includes/category-template.php */
  935. $cat_name = apply_filters(
  936. 'list_cats',
  937. esc_attr( $category->name ),
  938. $category
  939. );
  940. // Don't generate an element if the category name is empty.
  941. if ( ! $cat_name ) {
  942. return;
  943. }
  944. $link = '<a href="' . esc_url( get_term_link( $category ) ) . '" ';
  945. if ( $args['use_desc_for_title'] && ! empty( $category->description ) ) {
  946. /**
  947. * Filter the category description for display.
  948. *
  949. * @since 1.2.0
  950. *
  951. * @param string $description Category description.
  952. * @param object $category Category object.
  953. */
  954. $link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
  955. }
  956. $link .= '>';
  957. $link .= $cat_name . '</a>';
  958. if ( ! empty( $args['feed_image'] ) || ! empty( $args['feed'] ) ) {
  959. $link .= ' ';
  960. if ( empty( $args['feed_image'] ) ) {
  961. $link .= '(';
  962. }
  963. $link .= '<a href="' . esc_url( get_term_feed_link( $category->term_id, $category->taxonomy, $args['feed_type'] ) ) . '"';
  964. if ( empty( $args['feed'] ) ) {
  965. $alt = ' alt="' . sprintf(__( 'Feed for all posts filed under %s' ), $cat_name ) . '"';
  966. } else {
  967. $alt = ' alt="' . $args['feed'] . '"';
  968. $name = $args['feed'];
  969. $link .= empty( $args['title'] ) ? '' : $args['title'];
  970. }
  971. $link .= '>';
  972. if ( empty( $args['feed_image'] ) ) {
  973. $link .= $name;
  974. } else {
  975. $link .= "<img src='" . $args['feed_image'] . "'$alt" . ' />';
  976. }
  977. $link .= '</a>';
  978. if ( empty( $args['feed_image'] ) ) {
  979. $link .= ')';
  980. }
  981. }
  982. if ( ! empty( $args['show_count'] ) ) {
  983. $link .= ' (' . number_format_i18n( $category->count ) . ')';
  984. }
  985. if ( 'list' == $args['style'] ) {
  986. $output .= "\t<li";
  987. $css_classes = array(
  988. 'cat-item',
  989. 'cat-item-' . $category->term_id,
  990. );
  991. if ( ! empty( $args['current_category'] ) ) {
  992. $_current_category = get_term( $args['current_category'], $category->taxonomy );
  993. if ( $category->term_id == $args['current_category'] ) {
  994. $css_classes[] = 'current-cat';
  995. } elseif ( $category->term_id == $_current_category->parent ) {
  996. $css_classes[] = 'current-cat-parent';
  997. }
  998. }
  999. /**
  1000. * Filter the list of CSS classes to include with each category in the list.
  1001. *
  1002. * @since 4.2.0
  1003. *
  1004. * @see wp_list_categories()
  1005. *
  1006. * @param array $css_classes An array of CSS classes to be applied to each list item.
  1007. * @param object $category Category data object.
  1008. * @param int $depth Depth of page, used for padding.
  1009. * @param array $args An array of wp_list_categories() arguments.
  1010. */
  1011. $css_classes = implode( ' ', apply_filters( 'category_css_class', $css_classes, $category, $depth, $args ) );
  1012. $output .= ' class="' . $css_classes . '"';
  1013. $output .= ">$link\n";
  1014. } else {
  1015. $output .= "\t$link<br />\n";
  1016. }
  1017. }
  1018. /**
  1019. * Ends the element output, if needed.
  1020. *
  1021. * @see Walker::end_el()
  1022. *
  1023. * @since 2.1.0
  1024. *
  1025. * @param string $output Passed by reference. Used to append additional content.
  1026. * @param object $page Not used.
  1027. * @param int $depth Depth of category. Not used.
  1028. * @param array $args An array of arguments. Only uses 'list' for whether should append to output. @see wp_list_categories()
  1029. */
  1030. public function end_el( &$output, $page, $depth = 0, $args = array() ) {
  1031. if ( 'list' != $args['style'] )
  1032. return;
  1033. $output .= "</li>\n";
  1034. }
  1035. }
  1036. /**
  1037. * Create HTML dropdown list of Categories.
  1038. *
  1039. * @package WordPress
  1040. * @since 2.1.0
  1041. * @uses Walker
  1042. */
  1043. class Walker_CategoryDropdown extends Walker {
  1044. /**
  1045. * @see Walker::$tree_type
  1046. * @since 2.1.0
  1047. * @var string
  1048. */
  1049. public $tree_type = 'category';
  1050. /**
  1051. * @see Walker::$db_fields
  1052. * @since 2.1.0
  1053. * @todo Decouple this
  1054. * @var array
  1055. */
  1056. public $db_fields = array ('parent' => 'parent', 'id' => 'term_id');
  1057. /**
  1058. * Start the element output.
  1059. *
  1060. * @see Walker::start_el()
  1061. * @since 2.1.0
  1062. *
  1063. * @param string $output Passed by reference. Used to append additional content.
  1064. * @param object $category Category data object.
  1065. * @param int $depth Depth of category. Used for padding.
  1066. * @param array $args Uses 'selected', 'show_count', and 'value_field' keys, if they exist.
  1067. * See {@see wp_dropdown_categories()}.
  1068. */
  1069. public function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
  1070. $pad = str_repeat('&nbsp;', $depth * 3);
  1071. /** This filter is documented in wp-includes/category-template.php */
  1072. $cat_name = apply_filters( 'list_cats', $category->name, $category );
  1073. if ( isset( $args['value_field'] ) && isset( $category->{$args['value_field']} ) ) {
  1074. $value_field = $args['value_field'];
  1075. } else {
  1076. $value_field = 'term_id';
  1077. }
  1078. $output .= "\t<option class=\"level-$depth\" value=\"" . esc_attr( $category->{$value_field} ) . "\"";
  1079. // Type-juggling causes false matches, so we force everything to a string.
  1080. if ( (string) $category->{$value_field} === (string) $args['selected'] )
  1081. $output .= ' selected="selected"';
  1082. $output .= '>';
  1083. $output .= $pad.$cat_name;
  1084. if ( $args['show_count'] )
  1085. $output .= '&nbsp;&nbsp;('. number_format_i18n( $category->count ) .')';
  1086. $output .= "</option>\n";
  1087. }
  1088. }
  1089. //
  1090. // Tags
  1091. //
  1092. /**
  1093. * Retrieve the link to the tag.
  1094. *
  1095. * @since 2.3.0
  1096. * @see get_term_link()
  1097. *
  1098. * @param int|object $tag Tag ID or object.
  1099. * @return string Link on success, empty string if tag does not exist.
  1100. */
  1101. function get_tag_link( $tag ) {
  1102. if ( ! is_object( $tag ) )
  1103. $tag = (int) $tag;
  1104. $tag = get_term_link( $tag, 'post_tag' );
  1105. if ( is_wp_error( $tag ) )
  1106. return '';
  1107. return $tag;
  1108. }
  1109. /**
  1110. * Retrieve the tags for a post.
  1111. *
  1112. * @since 2.3.0
  1113. *
  1114. * @param int $id Post ID.
  1115. * @return array|false|WP_Error Array of tag objects on success, false on failure.
  1116. */
  1117. function get_the_tags( $id = 0 ) {
  1118. /**
  1119. * Filter the array of tags for the given post.
  1120. *
  1121. * @since 2.3.0
  1122. *
  1123. * @see get_the_terms()
  1124. *
  1125. * @param array $terms An array of tags for the given post.
  1126. */
  1127. return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
  1128. }
  1129. /**
  1130. * Retrieve the tags for a post formatted as a string.
  1131. *
  1132. * @since 2.3.0
  1133. *
  1134. * @param string $before Optional. Before tags.
  1135. * @param string $sep Optional. Between tags.
  1136. * @param string $after Optional. After tags.
  1137. * @param int $id Optional. Post ID. Defaults to the current post.
  1138. * @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure.
  1139. */
  1140. function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) {
  1141. /**
  1142. * Filter the tags list for a given post.
  1143. *
  1144. * @since 2.3.0
  1145. *
  1146. * @param string $tag_list List of tags.
  1147. * @param string $before String to use before tags.
  1148. * @param string $sep String to use between the tags.
  1149. * @param string $after String to use after tags.
  1150. * @param int $id Post ID.
  1151. */
  1152. return apply_filters( 'the_tags', get_the_term_list( $id, 'post_tag', $before, $sep, $after ), $before, $sep, $after, $id );
  1153. }
  1154. /**
  1155. * Retrieve the tags for a post.
  1156. *
  1157. * @since 2.3.0
  1158. *
  1159. * @param string $before Optional. Before list.
  1160. * @param string $sep Optional. Separate items using this.
  1161. * @param string $after Optional. After list.
  1162. */
  1163. function the_tags( $before = null, $sep = ', ', $after = '' ) {
  1164. if ( null === $before )
  1165. $before = __('Tags: ');
  1166. echo get_the_tag_list($before, $sep, $after);
  1167. }
  1168. /**
  1169. * Retrieve tag description.
  1170. *
  1171. * @since 2.8.0
  1172. *
  1173. * @param int $tag Optional. Tag ID. Will use global tag ID by default.
  1174. * @return string Tag description, available.
  1175. */
  1176. function tag_description( $tag = 0 ) {
  1177. return term_description( $tag );
  1178. }
  1179. /**
  1180. * Retrieve term description.
  1181. *
  1182. * @since 2.8.0
  1183. *
  1184. * @param int $term Optional. Term ID. Will use global term ID by default.
  1185. * @param string $taxonomy Optional taxonomy name. Defaults to 'post_tag'.
  1186. * @return string Term description, available.
  1187. */
  1188. function term_description( $term = 0, $taxonomy = 'post_tag' ) {
  1189. if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) {
  1190. $term = get_queried_object();
  1191. if ( $term ) {
  1192. $taxonomy = $term->taxonomy;
  1193. $term = $term->term_id;
  1194. }
  1195. }
  1196. $description = get_term_field( 'description', $term, $taxonomy );
  1197. return is_wp_error( $description ) ? '' : $description;
  1198. }
  1199. /**
  1200. * Retrieve the terms of the taxonomy that are attached to the post.
  1201. *
  1202. * @since 2.5.0
  1203. *
  1204. * @param int|object $post Post ID or object.
  1205. * @param string $taxonomy Taxonomy name.
  1206. * @return array|false|WP_Error Array of term objects on success, false if there are no terms
  1207. * or the post does not exist, WP_Error on failure.
  1208. */
  1209. function get_the_terms( $post, $taxonomy ) {
  1210. if ( ! $post = get_post( $post ) )
  1211. return false;
  1212. $terms = get_object_term_cache( $post->ID, $taxonomy );
  1213. if ( false === $terms ) {
  1214. $terms = wp_get_object_terms( $post->ID, $taxonomy );
  1215. wp_cache_add($post->ID, $terms, $taxonomy . '_relationships');
  1216. }
  1217. /**
  1218. * Filter the list of terms attached to the given post.
  1219. *
  1220. * @since 3.1.0
  1221. *
  1222. * @param array|WP_Error $terms List of attached terms, or WP_Error on failure.
  1223. * @param int $post_id Post ID.
  1224. * @param string $taxonomy Name of the taxonomy.
  1225. */
  1226. $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
  1227. if ( empty( $terms ) )
  1228. return false;
  1229. return $terms;
  1230. }
  1231. /**
  1232. * Retrieve a post's terms as a list with specified format.
  1233. *
  1234. * @since 2.5.0
  1235. *
  1236. * @param int $id Post ID.
  1237. * @param string $taxonomy Taxonomy name.
  1238. * @param string $before Optional. Before list.
  1239. * @param string $sep Optional. Separate items using this.
  1240. * @param string $after Optional. After list.
  1241. * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure.
  1242. */
  1243. function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
  1244. $terms = get_the_terms( $id, $taxonomy );
  1245. if ( is_wp_error( $terms ) )
  1246. return $terms;
  1247. if ( empty( $terms ) )
  1248. return false;
  1249. $links = array();
  1250. foreach ( $terms as $term ) {
  1251. $link = get_term_link( $term, $taxonomy );
  1252. if ( is_wp_error( $link ) ) {
  1253. return $link;
  1254. }
  1255. $links[] = '<a href="' . esc_url( $link ) . '" rel="tag">' . $term->name . '</a>';
  1256. }
  1257. /**
  1258. * Filter the term links for a given taxonomy.
  1259. *
  1260. * The dynamic portion of the filter name, `$taxonomy`, refers
  1261. * to the taxonomy slug.
  1262. *
  1263. * @since 2.5.0
  1264. *
  1265. * @param array $links An array of term links.
  1266. */
  1267. $term_links = apply_filters( "term_links-$taxonomy", $links );
  1268. return $before . join( $sep, $term_links ) . $after;
  1269. }
  1270. /**
  1271. * Display the terms in a list.
  1272. *
  1273. * @since 2.5.0
  1274. *
  1275. * @param int $id Post ID.
  1276. * @param string $taxonomy Taxonomy name.
  1277. * @param string $before Optional. Before list.
  1278. * @param string $sep Optional. Separate items using this.
  1279. * @param string $after Optional. After list.
  1280. * @return false|void False on WordPress error.
  1281. */
  1282. function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
  1283. $term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
  1284. if ( is_wp_error( $term_list ) )
  1285. return false;
  1286. /**
  1287. * Filter the list of terms to display.
  1288. *
  1289. * @since 2.9.0
  1290. *
  1291. * @param array $term_list List of terms to display.
  1292. * @param string $taxonomy The taxonomy name.
  1293. * @param string $before String to use before the terms.
  1294. * @param string $sep String to use between the terms.
  1295. * @param string $after String to use after the terms.
  1296. */
  1297. echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after );
  1298. }
  1299. /**
  1300. * Check if the current post has any of given category.
  1301. *
  1302. * @since 3.1.0
  1303. *
  1304. * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for.
  1305. * @param int|object $post Optional. Post to check instead of the current post.
  1306. * @return bool True if the current post has any of the given categories (or any category, if no category specified).
  1307. */
  1308. function has_category( $category = '', $post = null ) {
  1309. return has_term( $category, 'category', $post );
  1310. }
  1311. /**
  1312. * Check if the current post has any of given tags.
  1313. *
  1314. * The given tags are checked against the post's tags' term_ids, names and slugs.
  1315. * Tags given as integers will only be checked against the post's tags' term_ids.
  1316. * If no tags are given, determines if post has any tags.
  1317. *
  1318. * 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)
  1319. * Prior to v2.7, this function could only be used in the WordPress Loop.
  1320. * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
  1321. *
  1322. * @since 2.6.0
  1323. *
  1324. * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for.
  1325. * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0)
  1326. * @return bool True if the current post has any of the given tags (or any tag, if no tag specified).
  1327. */
  1328. function has_tag( $tag = '', $post = null ) {
  1329. return has_term( $tag, 'post_tag', $post );
  1330. }
  1331. /**
  1332. * Check if the current post has any of given terms.
  1333. *
  1334. * The given terms are checked against the post's terms' term_ids, names and slugs.
  1335. * Terms given as integers will only be checked against the post's terms' term_ids.
  1336. * If no terms are given, determines if post has any terms.
  1337. *
  1338. * @since 3.1.0
  1339. *
  1340. * @param string|int|array $term Optional. The term name/term_id/slug or array of them to check for.
  1341. * @param string $taxonomy Taxonomy name
  1342. * @param int|object $post Optional. Post to check instead of the current post.
  1343. * @return bool True if the current post has any of the given tags (or any tag, if no tag specified).
  1344. */
  1345. function has_term( $term = '', $taxonomy = '', $post = null ) {
  1346. $post = get_post($post);
  1347. if ( !$post )
  1348. return false;
  1349. $r = is_object_in_term( $post->ID, $taxonomy, $term );
  1350. if ( is_wp_error( $r ) )
  1351. return false;
  1352. return $r;
  1353. }