wp_tag_cloud()WP 2.3.0

Выводит или получает облако меток (список меток в виде облака). Можно указать произвольную таксономию.

Чтобы вывести элементы произвольной таксономии в виде облака, укажите название таксономии в параметре taxonomy.

"Облако меток" называется так, потому что размер текста каждой метки зависит от того, сколько записей связано с меткой. Чем больше записей, тем больше будет текст метки (в итоге получается нечто похожее на облако).

С версии 2.8 был добавлен параметр taxonomy, позволяющий создавать облако не только для стандартных меток, но и для категорий и произвольных таксономий.

Работает на основе: wp_generate_tag_cloud()
Хуки из функции

Возвращает

null|Строку|Строку[]. Выводит на экран html код списка.

  • Возвращает HTML, если параметр echo = false.
  • Вернет массив облака меток, если параметр format = array.
  • false, если не удалось получить метки.

Шаблон использования

wp_tag_cloud( [
	'smallest'  => 8,
	'largest'   => 22,
	'unit'      => 'pt',
	'number'    => 45,
	'format'    => 'flat',
	'separator' => "\n",
	'orderby'   => 'name',
	'order'     => 'ASC',
	'exclude'   => null,
	'include'   => null,
	'link'      => 'view',
	'taxonomy'  => 'post_tag',
	'echo'      => true,
	'topic_count_text_callback' => 'default_topic_count_text',
] );

Использование

<?php wp_tag_cloud( $args ); ?>
$args(строка/массив)
Аргументы, на основе которых будет построен список.
По умолчанию: базовые значения

Аргументы параметра $args

В $args можно также указать все параметры функции wp_generate_tag_cloud() и get_terms().

smallest(число)
Размер текста для меток с меньшим количеством записей (единицы измерения указываются в параметре unit).
По умолчанию: 8
largest(число)
Размер текста для меток с большим количеством записей (единицы измерения указываются в параметре unit).
По умолчанию:
unit(строка)
Единицы измерения параметров smallest и largest. Может быть любым CSS типом размера: pt, px, em, %.
По умолчанию: 'pt'
number(число)
Максимально количество меток, которое будет показано в списке. Если установить на 0, то будут показаны все метки без ограничения.
По умолчанию: 45
format(строка)

В каком формате выводить список. Может быть:

  • flat - метки будут разделены разделителем, указанным в параметре separator;
  • list - UL список с CSS классом 'wp-tag-cloud';
  • array - вернет облако меток в массиве для дальнейшей обработки в PHP.
    По умолчанию: 'flat'
separator(строка)
Текст между метками.
По умолчанию: "\n"
orderby(строка)
Сортировать метки по имени (name) или количеству записей (count). Не влияет на запрос к базе данных.
По умолчанию: 'name'
order(строка)

Порядок сортировки. Может быть:

  • ASC - по порядку (1,2,3);
  • DESC - в обратном порядке (3,2,1);
  • RAND - хаотичный порядок (перемешать).

order и orderby не влияют на запрос к базе данных. Метки сначала получаются из базы данных, затем сортируются. Эти параметры для получения из базы данных равны: orderby=count и order=DESC и их нельзя изменить.
По умолчанию: 'ASC'

exclude(строка)
Исключить указанные метки. Указывать нужно ID через запятую.
По умолчанию: null
include(строка)
Показать только указанные метки. Указывать нужно ID через запятую.
По умолчанию: null
topic_count_text_callback(строка/массив)
Функция, которая получает количество записей и возвращает текст для метки. Можно установить свою функцию, если нужно отображать какой-либо другой текст с количеством записей для каждой метки.
По умолчанию: default_topic_count_text
link(строка)

Куда будет вести ссылка метки.

  • view - по нажатию на метку, попадем на страницу метки;
  • edit - по нажатию на метку, попадем на страницу редактирования метки.
    По умолчанию: view
taxonomy(строка/массив)

Название таксономии или массив нескольких названий, из которых будет построено облако. Может быть:

  • post_tag;
  • category;
  • link_category;
  • Своя таксономия;
  • Массив названий таксономий - параметр введен в версии 3.1.
    По умолчанию: post_tag
show_count(логический)
Показывать ли число записей в метке. По умолчанию 0. Может быть: 0, 1 или true/false. С WP 4.8.
echo(логический)
1 - Выводить на экран, 0 - возвращать результат для дальнейшей обработки.
По умолчанию: 1 (true)

Примеры

1

#1 Базовое использование

Выведем облако меток с заголовком "Популярные метки":

if ( function_exists('wp_tag_cloud') ){
	echo '<h2>Популярные метки</h2>';
	wp_tag_cloud('smallest=8&largest=22');
}
0

#2 Что возвращает функция

wp_tag_cloud( 'smallest=8&largest=22' );

Выведет на экран:

<a href="https://example.com/tag/ajax"
   class="tag-cloud-link tag-link-134 tag-link-position-1"
   style="font-size: 13.283018867925pt;" aria-label="AJAX (4 elements)">AJAX</a>

<a href="https://example.com/tag/chrome"
   class="tag-cloud-link tag-link-1603 tag-link-position-2"
   style="font-size: 8pt;" aria-label="Chrome (1 element)">Chrome</a>

<a href="https://example.com/tag/css" class="tag-cloud-link tag-link-531 tag-link-position-3"
   style="font-size: 13.283018867925pt;" aria-label="CSS (4 elements)">CSS</a>
	...

Список:

wp_tag_cloud( [
	'format' => 'list',
] );

Выведет:

<ul class='wp-tag-cloud' role='list'>
	<li><a href="https://site.com/met/ajax" class="tag-cloud-link tag-link-134 tag-link-position-1" style="font-size: 13.283018867925pt;" aria-label="AJAX (4 elements)">AJAX</a></li>
	<li><a href="https://site.com/met/chrome" class="tag-cloud-link tag-link-1603 tag-link-position-2" style="font-size: 8pt;" aria-label="Chrome (1 elements)">Chrome</a></li>
	...
</ul>
0

#3 Еще одни пример демонстрирующий передачу разных параметров

Изменим размеры меток (smallest=15&largest=40), ограничим количество выводимых меток (number=50) и отсортируем их по количеству записей, а не по имени (orderby=count):

<?php wp_tag_cloud('smallest=15&largest=40&number=50&orderby=count'); ?>
0

#4 Получим список, не будем выводить его на экран

Запишем список в параметр $tag, чтобы потом использовать его в php для своих целей:

$tag = wp_tag_cloud( 'format=array' );

print_r( $tag );
0

#5 Облако категорий

Выведем облако категорий, вместо облака меток. Для этого изменим название таксономии:

<?php wp_tag_cloud( array( 'taxonomy' => 'category' ) ); ?>
0

#6 Облако меток и категорий одновременно

Можно слепить категории и метки в одно облако:

<?php
wp_tag_cloud( array(
	'taxonomy' => array('post_tag','category'),
) );
?>
0

#7 Изменение текста атрибута title у тега <a>

При наведении на ссылку, показывается количество записей метки. Чтобы изменить этот текст, можно использовать параметр topic_count_text_callback, в котором укажем свою функцию для создания текста:

<?php
wp_tag_cloud( array( 'topic_count_text_callback' => 'my_tag_text_callback' ) );

function my_tag_text_callback( $count ) {
	return sprintf( _n('%s картинка', '%s картинок', $count), number_format_i18n( $count ) );
}
?>
0

#8 Архив меток

Как один из вариантов использования меток, предлагаю создать архивные страницы меток. При клике на определенную метку, мы попадаем на страницу с постами связанными с этой меткой. Как выглядет такая страница, определяется файлом шаблона tag.php, если такого файла нет (обычно его ент), то формирование вывода отдается файлу archives.php.

Давайте сделаем страницу метки, на которой в самом начале будет показано облако меток, а после него записи относящиеся к выбранной метке. Для этого создадим (если нет) или изменим (если существует) файл tag.php. Создавать файл нужно в каталоге темы.

Содержимое файла tags.php:

<?php
/*
Template Name: Tag Archive
*/
?>

<?php get_header(); ?>

<div>

	<h2>Tag Archive</h2>

	<?php wp_tag_cloud( '' ); ?>
	<div class="navigation">
		<div class="alignleft"><?php next_posts_link( '« Older Entries' ) ?></div>
		<div class="alignright"><?php previous_posts_link( 'Newer Entries »' ) ?></div>
	</div>
	<?php
	if( have_posts() ) {
		while( have_posts() ) {
			the_post();
			?>
			<h2>
				<a href="<?php the_permalink() ?>" rel="bookmark"
				   title="Permanent Link to <?php esc_attr( get_the_title() ) ?>"><?php the_title() ?></a>
			</h2>
			<div class="entry">
				<?php the_content( 'Read the rest of this entry »' ); ?>
			</div>
			<?php
		}
	}
	?>
</div>

<?php get_footer(); ?>

В данном примере не учитываются CSS стили, поэтому возможна несовместимость с шаблоном.

0

#9 Изменение параметров по умолчанию для виджета облака меток через фильтр

Допустим, нам нужно уменьшить максимальный размер шрифта для виджета с облаком меток. Нужно поставить значение 16, а не 22 для параметра 'largest'. Для этого используем хук widget_tag_cloud_args

add_filter( 'widget_tag_cloud_args', function( $args ){
	$args['largest'] = 16;

	return $args;
} );

На этот пример меня подтолкнул этот комменатрий

0

#10 Получим OL список и добавим класс к LI элементам

Нужно чтобы, используя аргумент 'format', ссылки выводились не в UL, а OL списке. И также нужно добавить CSS класс к LI элементам.

$cloud = wp_tag_cloud( [
	'format' => 'list',
	'echo' => false,
] );

$cloud = str_replace( [ '<ul ','</ul>' ], [ '<ol ','</ol>' ], $cloud );

$cloud = str_replace( '<li>', '<li class="cloud-li-class">', $cloud );

echo $cloud;

Результат:

<ol class='wp-tag-cloud' role='list'>
	<li class="cloud-li-class"><a href="/met/ajax" class="tag-cloud-link tag-link-134 tag-link-position-1" style="font-size: 13.283018867925pt;" aria-label="AJAX (4 элемента)">AJAX</a></li>
	<li class="cloud-li-class"><a href="/met/chrome" class="tag-cloud-link tag-link-1603 tag-link-position-2" style="font-size: 8pt;" aria-label="Chrome (1 элемент)">Chrome</a></li>
	...
</ol>

Список изменений

С версии 2.3.0 Введена.
С версии 2.8.0 Added the taxonomy argument.
С версии 4.8.0 Added the show_count argument.

Код wp_tag_cloud() WP 6.1.1

function wp_tag_cloud( $args = '' ) {
	$defaults = array(
		'smallest'   => 8,
		'largest'    => 22,
		'unit'       => 'pt',
		'number'     => 45,
		'format'     => 'flat',
		'separator'  => "\n",
		'orderby'    => 'name',
		'order'      => 'ASC',
		'exclude'    => '',
		'include'    => '',
		'link'       => 'view',
		'taxonomy'   => 'post_tag',
		'post_type'  => '',
		'echo'       => true,
		'show_count' => 0,
	);

	$args = wp_parse_args( $args, $defaults );

	$tags = get_terms(
		array_merge(
			$args,
			array(
				'orderby' => 'count',
				'order'   => 'DESC',
			)
		)
	); // Always query top tags.

	if ( empty( $tags ) || is_wp_error( $tags ) ) {
		return;
	}

	foreach ( $tags as $key => $tag ) {
		if ( 'edit' === $args['link'] ) {
			$link = get_edit_term_link( $tag, $tag->taxonomy, $args['post_type'] );
		} else {
			$link = get_term_link( $tag, $tag->taxonomy );
		}

		if ( is_wp_error( $link ) ) {
			return;
		}

		$tags[ $key ]->link = $link;
		$tags[ $key ]->id   = $tag->term_id;
	}

	// Here's where those top tags get sorted according to $args.
	$return = wp_generate_tag_cloud( $tags, $args );

	/**
	 * Filters the tag cloud output.
	 *
	 * @since 2.3.0
	 *
	 * @param string|string[] $return Tag cloud as a string or an array, depending on 'format' argument.
	 * @param array           $args   An array of tag cloud arguments. See wp_tag_cloud()
	 *                                for information on accepted arguments.
	 */
	$return = apply_filters( 'wp_tag_cloud', $return, $args );

	if ( 'array' === $args['format'] || empty( $args['echo'] ) ) {
		return $return;
	}

	echo $return;
}