wp_tag_cloud с версии 2.3

Описание

Выводит список меток называемый "облаком меток".

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

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

wp_tag_cloud() работает на базе wp_generate_tag_cloud().

Функция выводит на экран или возвращает html код списка.

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

<?php wp_tag_cloud( $args ); ?>

Параметры по умолчанию

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

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 - хаотичный порядок (перемешать).

По умолчанию: '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

echo (логический)

1 - Выводить на экран, 0 - возвращать результат для дальнейшей обработки.
По умолчанию: 1 (true)

Примеры

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

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

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
  $args = array(
    'taxonomy'  => array('post_tag','category'),
   ); 

  wp_tag_cloud($args);
?>

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
*/ ?>
<div>
<?php get_header(); ?>
<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 стили и возможна некоторая несовместимость с шаблоном.

На заметку

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

wp_tag_cloud()

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', 'echo' => true
	);
	$args = wp_parse_args( $args, $defaults );

	$tags = get_terms( $args['taxonomy'], 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_tag_link( $tag->term_id, $tag->taxonomy );
		else
			$link = get_term_link( intval($tag->term_id), $tag->taxonomy );
		if ( is_wp_error( $link ) )
			return false;

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

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

	$return = apply_filters( 'wp_tag_cloud', $return, $args );

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

	echo $return;
}

Связанные Функции

Ещё из раздела

Смотрите также: Функции WordPress и Теги Шаблона.