wp_generate_tag_cloud

Generates a tag cloud (heatmap) from provided data.

Description

(string|array) wp_generate_tag_cloud( (array) $tags, (string) $args = '' ); 

Returns (string|array)

Tag cloud as a string or an array, depending on 'format' argument.

Parameters (2)

0. $tags (array)
List of tags.
1. $args — Optional. (string) => ''
Array of string of arguments for generating a tag cloud.

Options

  • smallest (int) => 8 (pt)

    Smallest font size used to display tags. Paired with the value of $unit,, to determine CSS text size unit.

  • largest (int) => 22 (pt)

    Largest font size used to display tags. Paired with the value of $unit,, to determine CSS text size unit.

  • unit (string) => 'pt'

    CSS text size unit to use with the $smallest and $largest values. Accepts any valid CSS text size unit.

  • number (int) => 0

    The number of tags to return. Accepts any positive integer or zero to return all.

  • format (string) => 'flat'

    Format to display the tag cloud in. Accepts flat (tags separated with spaces), list (tags displayed in an unordered list), or array (returns an array).

  • separator (string) => "\n"

    HTML or text to separate the tags.

array(

    /**
     * Smallest font size used to display tags. Paired with the value of `$unit`, to determine CSS
     * text size unit.
     *
     * @type int
     * @default 8 (pt)
     */
    'smallest' => 8 (pt),

    /**
     * Largest font size used to display tags. Paired with the value of `$unit`, to determine CSS text
     * size unit.
     *
     * @type int
     * @default 22 (pt)
     */
    'largest' => 22 (pt),

    /**
     * CSS text size unit to use with the `$smallest` and `$largest` values. Accepts any valid CSS
     * text size unit.
     *
     * @type string
     * @default 'pt'
     */
    'unit' => 'pt',

    /**
     * The number of tags to return. Accepts any positive integer or zero to return all.
     *
     * @type int
     */
    'number' => 0,

    /**
     * Format to display the tag cloud in. Accepts 'flat' (tags separated with spaces), 'list' (tags
     * displayed in an unordered list), or 'array' (returns an array).
     *
     * @type string
     * @default 'flat'
     */
    'format' => 'flat',

    /**
     * HTML or text to separate the tags.
     *
     * @type string
     * @default "\n"
     */
    'separator' => "\n"
);        


Usage

  1. if ( !function_exists( 'wp_generate_tag_cloud' ) ) { 
  2. require_once ABSPATH . WPINC . '/category-template.php'; 
  3.  
  4. // List of tags. 
  5. $tags = array(); 
  6.  
  7. // Optional. Array of string of arguments for generating a tag cloud. 
  8. $args = array( 
  9. 'smallest' => 8 (pt), 
  10. 'largest' => 22 (pt), 
  11. 'unit' => 'pt', 
  12. 'number' => 0, 
  13. 'format' => 'flat', 
  14. 'separator' => "\n" 
  15. ); 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = wp_generate_tag_cloud($tags, $args); 
  19.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/category-template.php  
  1. function wp_generate_tag_cloud( $tags, $args = '' ) { 
  2. $defaults = array( 
  3. 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0,  
  4. 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC',  
  5. 'topic_count_text' => null, 'topic_count_text_callback' => null,  
  6. 'topic_count_scale_callback' => 'default_topic_count_scale', 'filter' => 1,  
  7. ); 
  8.  
  9. $args = wp_parse_args( $args, $defaults ); 
  10.  
  11. $return = ( 'array' === $args['format'] ) ? array() : ''; 
  12.  
  13. if ( empty( $tags ) ) { 
  14. return $return; 
  15.  
  16. // Juggle topic count tooltips: 
  17. if ( isset( $args['topic_count_text'] ) ) { 
  18. // First look for nooped plural support via topic_count_text. 
  19. $translate_nooped_plural = $args['topic_count_text']; 
  20. } elseif ( ! empty( $args['topic_count_text_callback'] ) ) { 
  21. // Look for the alternative callback style. Ignore the previous default. 
  22. if ( $args['topic_count_text_callback'] === 'default_topic_count_text' ) { 
  23. $translate_nooped_plural = _n_noop( '%s topic', '%s topics' ); 
  24. } else { 
  25. $translate_nooped_plural = false; 
  26. } elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) { 
  27. // If no callback exists, look for the old-style single_text and multiple_text arguments. 
  28. $translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] ); 
  29. } else { 
  30. // This is the default for when no callback, plural, or argument is passed in. 
  31. $translate_nooped_plural = _n_noop( '%s topic', '%s topics' ); 
  32.  
  33. /** 
  34. * Filters how the items in a tag cloud are sorted. 
  35. * @since 2.8.0 
  36. * @param array $tags Ordered array of terms. 
  37. * @param array $args An array of tag cloud arguments. 
  38. */ 
  39. $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args ); 
  40. if ( empty( $tags_sorted ) ) { 
  41. return $return; 
  42.  
  43. if ( $tags_sorted !== $tags ) { 
  44. $tags = $tags_sorted; 
  45. unset( $tags_sorted ); 
  46. } else { 
  47. if ( 'RAND' === $args['order'] ) { 
  48. shuffle( $tags ); 
  49. } else { 
  50. // SQL cannot save you; this is a second (potentially different) sort on a subset of data. 
  51. if ( 'name' === $args['orderby'] ) { 
  52. uasort( $tags, '_wp_object_name_sort_cb' ); 
  53. } else { 
  54. uasort( $tags, '_wp_object_count_sort_cb' ); 
  55.  
  56. if ( 'DESC' === $args['order'] ) { 
  57. $tags = array_reverse( $tags, true ); 
  58.  
  59. if ( $args['number'] > 0 ) 
  60. $tags = array_slice( $tags, 0, $args['number'] ); 
  61.  
  62. $counts = array(); 
  63. $real_counts = array(); // For the alt tag 
  64. foreach ( (array) $tags as $key => $tag ) { 
  65. $real_counts[ $key ] = $tag->count; 
  66. $counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count ); 
  67.  
  68. $min_count = min( $counts ); 
  69. $spread = max( $counts ) - $min_count; 
  70. if ( $spread <= 0 ) 
  71. $spread = 1; 
  72. $font_spread = $args['largest'] - $args['smallest']; 
  73. if ( $font_spread < 0 ) 
  74. $font_spread = 1; 
  75. $font_step = $font_spread / $spread; 
  76.  
  77. // Assemble the data that will be used to generate the tag cloud markup. 
  78. $tags_data = array(); 
  79. foreach ( $tags as $key => $tag ) { 
  80. $tag_id = isset( $tag->id ) ? $tag->id : $key; 
  81.  
  82. $count = $counts[ $key ]; 
  83. $real_count = $real_counts[ $key ]; 
  84.  
  85. if ( $translate_nooped_plural ) { 
  86. $title = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) ); 
  87. } else { 
  88. $title = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args ); 
  89.  
  90. $tags_data[] = array( 
  91. 'id' => $tag_id,  
  92. 'url' => '#' != $tag->link ? $tag->link : '#',  
  93. 'role' => '#' != $tag->link ? '' : ' role="button"',  
  94. 'name' => $tag->name,  
  95. 'title' => $title,  
  96. 'slug' => $tag->slug,  
  97. 'real_count' => $real_count,  
  98. 'class' => 'tag-link-' . $tag_id,  
  99. 'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step,  
  100. ); 
  101.  
  102. /** 
  103. * Filters the data used to generate the tag cloud. 
  104. * @since 4.3.0 
  105. * @param array $tags_data An array of term data for term used to generate the tag cloud. 
  106. */ 
  107. $tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data ); 
  108.  
  109. $a = array(); 
  110.  
  111. // generate the output links array 
  112. foreach ( $tags_data as $key => $tag_data ) { 
  113. $class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 ); 
  114. $a[] = "<a href='" . esc_url( $tag_data['url'] ) . "'" . $tag_data['role'] . " class='" . esc_attr( $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>"; 
  115.  
  116. switch ( $args['format'] ) { 
  117. case 'array' : 
  118. $return =& $a; 
  119. break; 
  120. case 'list' : 
  121. $return = "<ul class='wp-tag-cloud'>\n\t<li>"; 
  122. $return .= join( "</li>\n\t<li>", $a ); 
  123. $return .= "</li>\n</ul>\n"; 
  124. break; 
  125. default : 
  126. $return = join( $args['separator'], $a ); 
  127. break; 
  128.  
  129. if ( $args['filter'] ) { 
  130. /** 
  131. * Filters the generated output of a tag cloud. 
  132. * The filter is only evaluated if a true value is passed 
  133. * to the $filter argument in wp_generate_tag_cloud(). 
  134. * @since 2.3.0 
  135. * @see wp_generate_tag_cloud() 
  136. * @param array|string $return String containing the generated HTML tag cloud output 
  137. * or an array of tag links if the 'format' argument 
  138. * equals 'array'. 
  139. * @param array $tags An array of terms used in the tag cloud. 
  140. * @param array $args An array of wp_generate_tag_cloud() arguments. 
  141. */ 
  142. return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args ); 
  143.  
  144. else 
  145. return $return;