Summery Summery
Generates a tag cloud (heatmap) from provided data.
Syntax Syntax
Parameters Parameters
- $tags
-
(Required) Array of WP_Term objects to generate the tag cloud for.
- $args
-
(Optional) Array or string of arguments for generating a tag cloud.
- 'smallest'
(int) Smallest font size used to display tags. Paired with the value of$unit
, to determine CSS text size unit. Default 8 (pt). - 'largest'
(int) Largest font size used to display tags. Paired with the value of$unit
, to determine CSS text size unit. Default 22 (pt). - 'unit'
(string) CSS text size unit to use with the$smallest
and$largest
values. Accepts any valid CSS text size unit. Default 'pt'. - 'number'
(int) The number of tags to return. Accepts any positive integer or zero to return all. Default 0. - 'format'
(string) 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). Default 'flat'. - 'separator'
(string) HTML or text to separate the tags. Default "n" (newline). - 'orderby'
(string) Value to order tags by. Accepts 'name' or 'count'. Default 'name'. The 'tag_cloud_sort' filter can also affect how tags are sorted. - 'order'
(string) How to order the tags. Accepts 'ASC' (ascending), 'DESC' (descending), or 'RAND' (random). Default 'ASC'. - 'filter'
(int|bool) Whether to enable filtering of the final output via 'wp_generate_tag_cloud'. Default 1|true. - 'topic_count_text'
(string) Nooped plural text from _n_noop() to supply to tag counts. Default null. - 'topic_count_text_callback'
(callable) Callback used to generate nooped plural text for tag counts based on the count. Default null. - 'topic_count_scale_callback'
(callable) Callback used to determine the tag count scaling value. Default default_topic_count_scale(). - 'show_count'
(bool|int) Whether to display the tag counts. Default 0. Accepts 0, 1, or their bool equivalents.
Default value: ''
- 'smallest'
Return Return
(string|array) Tag cloud as a string or an array, depending on 'format' argument.
Source Source
File: wp-includes/category-template.php
* in an unordered list), or 'array' (returns an array). * Default 'flat'. * @type string $separator HTML or text to separate the tags. Default "\n" (newline). * @type string $orderby Value to order tags by. Accepts 'name' or 'count'. * Default 'name'. The {@see 'tag_cloud_sort'} filter * can also affect how tags are sorted. * @type string $order How to order the tags. Accepts 'ASC' (ascending), * 'DESC' (descending), or 'RAND' (random). Default 'ASC'. * @type int|bool $filter Whether to enable filtering of the final output * via {@see 'wp_generate_tag_cloud'}. Default 1|true. * @type string $topic_count_text Nooped plural text from _n_noop() to supply to * tag counts. Default null. * @type callable $topic_count_text_callback Callback used to generate nooped plural text for * tag counts based on the count. Default null. * @type callable $topic_count_scale_callback Callback used to determine the tag count scaling * value. Default default_topic_count_scale(). * @type bool|int $show_count Whether to display the tag counts. Default 0. Accepts * 0, 1, or their bool equivalents. * } * @return string|array Tag cloud as a string or an array, depending on 'format' argument. */ function wp_generate_tag_cloud( $tags, $args = '' ) { $defaults = array( 'smallest' => 8, 'largest' => 22, 'unit' => 'pt', 'number' => 0, 'format' => 'flat', 'separator' => "\n", 'orderby' => 'name', 'order' => 'ASC', 'topic_count_text' => null, 'topic_count_text_callback' => null, 'topic_count_scale_callback' => 'default_topic_count_scale', 'filter' => 1, 'show_count' => 0, ); $args = wp_parse_args( $args, $defaults ); $return = ( 'array' === $args['format'] ) ? array() : ''; if ( empty( $tags ) ) { return $return; } // Juggle topic counts. if ( isset( $args['topic_count_text'] ) ) { // First look for nooped plural support via topic_count_text. $translate_nooped_plural = $args['topic_count_text']; } elseif ( ! empty( $args['topic_count_text_callback'] ) ) { // Look for the alternative callback style. Ignore the previous default. if ( 'default_topic_count_text' === $args['topic_count_text_callback'] ) { /* translators: %s: Number of items (tags). */ $translate_nooped_plural = _n_noop( '%s item', '%s items' ); } else { $translate_nooped_plural = false; } } elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) { // If no callback exists, look for the old-style single_text and multiple_text arguments. // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingle,WordPress.WP.I18n.NonSingularStringLiteralPlural $translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] ); } else { // This is the default for when no callback, plural, or argument is passed in. /* translators: %s: Number of items (tags). */ $translate_nooped_plural = _n_noop( '%s item', '%s items' ); } /** * Filters how the items in a tag cloud are sorted. * * @since 2.8.0 * * @param WP_Term[] $tags Ordered array of terms. * @param array $args An array of tag cloud arguments. */ $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args ); if ( empty( $tags_sorted ) ) { return $return; } if ( $tags_sorted !== $tags ) { $tags = $tags_sorted; unset( $tags_sorted ); } else { if ( 'RAND' === $args['order'] ) { shuffle( $tags ); } else { // SQL cannot save you; this is a second (potentially different) sort on a subset of data. if ( 'name' === $args['orderby'] ) { uasort( $tags, '_wp_object_name_sort_cb' ); } else { uasort( $tags, '_wp_object_count_sort_cb' ); } if ( 'DESC' === $args['order'] ) { $tags = array_reverse( $tags, true ); } } } if ( $args['number'] > 0 ) { $tags = array_slice( $tags, 0, $args['number'] ); } $counts = array(); $real_counts = array(); // For the alt tag. foreach ( (array) $tags as $key => $tag ) { $real_counts[ $key ] = $tag->count; $counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count ); } $min_count = min( $counts ); $spread = max( $counts ) - $min_count; if ( $spread <= 0 ) { $spread = 1; } $font_spread = $args['largest'] - $args['smallest']; if ( $font_spread < 0 ) { $font_spread = 1; } $font_step = $font_spread / $spread; $aria_label = false; /* * Determine whether to output an 'aria-label' attribute with the tag name and count. * When tags have a different font size, they visually convey an important information * that should be available to assistive technologies too. On the other hand, sometimes * themes set up the Tag Cloud to display all tags with the same font size (setting * the 'smallest' and 'largest' arguments to the same value). * In order to always serve the same content to all users, the 'aria-label' gets printed out: * - when tags have a different size * - when the tag count is displayed (for example when users check the checkbox in the * Tag Cloud widget), regardless of the tags font size */ if ( $args['show_count'] || 0 !== $font_spread ) { $aria_label = true; } // Assemble the data that will be used to generate the tag cloud markup. $tags_data = array(); foreach ( $tags as $key => $tag ) { $tag_id = isset( $tag->id ) ? $tag->id : $key; $count = $counts[ $key ]; $real_count = $real_counts[ $key ]; if ( $translate_nooped_plural ) { $formatted_count = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) ); } else { $formatted_count = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args ); } $tags_data[] = array( 'id' => $tag_id, 'url' => ( '#' !== $tag->link ) ? $tag->link : '#', 'role' => ( '#' !== $tag->link ) ? '' : ' role="button"', 'name' => $tag->name, 'formatted_count' => $formatted_count, 'slug' => $tag->slug, 'real_count' => $real_count, 'class' => 'tag-cloud-link tag-link-' . $tag_id, 'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step, 'aria_label' => $aria_label ? sprintf( ' aria-label="%1$s (%2$s)"', esc_attr( $tag->name ), esc_attr( $formatted_count ) ) : '', 'show_count' => $args['show_count'] ? '<span class="tag-link-count"> (' . $real_count . ')</span>' : '', ); } /** * Filters the data used to generate the tag cloud. * * @since 4.3.0 * * @param array $tags_data An array of term data for term used to generate the tag cloud. */ $tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data ); $a = array(); // Generate the output links array. foreach ( $tags_data as $key => $tag_data ) { $class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 ); $a[] = sprintf( '<a href="%1$s"%2$s class="%3$s" style="font-size: %4$s;"%5$s>%6$s%7$s</a>', esc_url( $tag_data['url'] ), $tag_data['role'], esc_attr( $class ), esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ), $tag_data['aria_label'], esc_html( $tag_data['name'] ), $tag_data['show_count'] ); } switch ( $args['format'] ) { case 'array': $return =& $a; break; case 'list': /* * Force role="list", as some browsers (sic: Safari 10) don't expose to assistive * technologies the default role when the list is styled with `list-style: none`. * Note: this is redundant but doesn't harm. */ $return = "<ul class='wp-tag-cloud' role='list'>\n\t<li>"; $return .= join( "</li>\n\t<li>", $a ); $return .= "</li>\n</ul>\n"; break; default: $return = join( $args['separator'], $a ); break; }
Advertisement
Changelog Changelog
Version | Description |
---|---|
4.8.0 | Added the show_count argument. |
2.3.0 | Introduced. |