wp_tag_cloud() WP 2.3

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

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

Возвращает

null. Выводит на экран html код списка.

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

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

wp_tag_cloud( array(
	'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

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 Базовое использование

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

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

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

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

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

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

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

<?php $tag = wp_tag_cloud('format=array' );?>

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

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

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

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

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

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

#4 Изменение текста атрибута 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 ) );
}
?>

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

Как один из вариантов использования меток, предлагаю создать архивные страницы меток. При клике на определенную метку, мы попадаем на страницу с постами связанными с этой меткой. Как выглядет такая страница, определяется файлом шаблона 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()) : ?>
		<?php while (have_posts()) : the_post(); ?>
		<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2>
	<div class="entry">
	<?php the_content('Read the rest of this entry »'); ?>
	</div>

	<?php endwhile; ?>
	<?php endif; ?>
</div>

<?php get_footer(); ?>

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

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

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

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

	return $args;
});

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

Заметки

• В версии 3.1 добавлен возможность передавать массивы в параметр taxonomy;
• В версии 2.9 добавлен параметр separator;
• В версии 2.8 добавлены параметры taxonomy и echo;
• В версии 2.7 добавлен параметр link;

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

Код wp tag cloud: wp-includes/category-template.php ^{WP 5.4.2}

<?php
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->term_id, $tag->taxonomy, $args['post_type'] );
		} else {
			$link = get_term_link( intval( $tag->term_id ), $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|array $return Tag cloud as a string or an array, depending on 'format' argument.
	 * @param array        $args   An array of tag cloud arguments.
	 */
	$return = apply_filters( 'wp_tag_cloud', $return, $args );

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

	echo $return;
}

Cвязанные функции

Из метки: Список (wp_list списки)

Еще из раздела: Метки

Еще из тегов шаблона: Таксономии: рубрики, метки, ...