WordPress как на ладони
wordpress jino

wp_list_categories() WP 2.1

Выводит список категорий в виде ссылок. Если перейти по ссылке, то будут показаны все посты из категории.

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

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

<ul>
	<?php wp_list_categories( $args ); ?>
</ul>

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

$args = array(
	'show_option_all'    => '',
	'show_option_none'   => __('No categories'),
	'orderby'            => 'name',
	'order'              => 'ASC',
	'show_last_update'   => 0,
	'style'              => 'list',
	'show_count'         => 0,
	'hide_empty'         => 1,
	'use_desc_for_title' => 1,
	'child_of'           => 0,
	'feed'               => '',
	'feed_type'          => '',
	'feed_image'         => '',
	'exclude'            => '',
	'exclude_tree'       => '',
	'include'            => '',
	'hierarchical'       => true,
	'title_li'           => __( 'Categories' ),
	'number'             => NULL,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => 'Walker_Category',
	'hide_title_if_empty' => false,
	'separator'          => '<br />',
);

echo '<ul>';
	wp_list_categories( $args );
echo '</ul>';

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

show_option_all(строка)
Если передать не пустую строку, например 'Все категории', то будет добавлена ссылка на все категории (часто это ссылка на главную страницу блога). Текстом ссылки станет текст переданный параметру, в данном случае Все категории.
По умолчанию: ''
show_option_none(строка)
Если функция не нашла ни одной категории для показа, то будет показан этот текст.
По умолчанию: 'Нет рубрик'
orderby(строка)

Сортировка списка по определенным критериям. Например по количеству постов в каждой категории или по названию категорий. Доступны следующие критерии:

  • ID - сортировка по ID;
  • name - сортировка по названию (по умолчанию);
  • slug - сортировка по алт. имени (slug);
  • count - по количеству записей в категории;
  • term_group - по группе.

По умолчанию: 'name'

order(строка)

Направление сортировки:

  • ASC - по порядку, от меньшего к большему (1, 2, 3; a, b, c);
  • DESC - в обратном порядке, от большего к меньшему (3, 2, 1; c, b, a).

По умолчанию: 'ASC'

show_last_update(логический)
Показать последнее обновление категории 1 - да, 0 - нет (у меня при изменении параметра ничего не поменялось).
style(строка)
Стиль вывода списка. 'list' - означает, что нужно выводить списком в теге <li>, вложенность категорий будет соблюдена. Если указать 'none', то будут выведены только ссылки на категории (<a>) разделенные тегом <br>.
По умолчанию: 'list'
show_count(логический)

Показывать (1) или нет (0) количество записей в категории. Число записей будет показано после названия категории в скобках (например, Психология (16)).

  • 1 (true) - показывать количество записей;
  • 0 (false) - не показывать количество записей.
hide_empty(логический)

Скрывать ли категории в которых нет записей?

  • 0 (false) - показывать пустые (не скрывать);
  • 1 (true) - не показывать пустые категории (скрывать).

По умолчанию: 1

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

Вставлять ли описание категории в атрибут title у ссылки (<a title="Описание категории" href="...):

  • 1 (true) - да, вставлять описание в title, если оно есть;
  • 0 (false) - нет, не использовать описание (будет: Посмотреть все записи в рубрике "название категории").

По умолчанию: true

child_of(число)
Показать дочерние категории. В параметре указывается ID родительской категории (категория, вложенные категории которой нужно показать).
feed(логический)
Показать ли рядом с названием ссылку на RSS фид (rrs-2) категории. Текст переданный в этом параметре станет текстом ссылки.
По умолчанию: ''
feed_type(строка)
Тип фида
По умолчанию: 'rss-2'
feed_image(строка)
Показать ли рядом с названием ссылку-картинку на RSS фид (rrs-2) категории. В параметре нужно указать ссылку на картинку. Если этот параметр указан, параметр $feed будет отменен.
По умолчанию: ''
exclude(строка)

Исключить категории из списка. Нужно указывать ID категорий через запятую.

  • Если этот параметр указан, параметр child_of будет отменен.
  • Если параметр heiararchical равен true, то будет исключаться вся ветка. Если heiararchical равен false, то для исключения ветки используйте параметр exclude_tree.

По умолчанию: ''

exclude_tree(строка)
Исключить дерево категорий из списка. Указывайте ID категорий через запятую. Параметр include должен быть пустым. Если параметр heirarchical равен true, то используйте exclude вместо exclude_tree. С версии 2.7.1.
По умолчанию: ''
include(строка)
Вывести списком только указанные категории. Указывать нужно ID категорий через запятую.
По умолчанию: ''
hierarchical(логический)

Показывать категории как дерево. Показывать вложенные (дочерние категории), как вложенный список.

  • 1 (true) - да, древовидный тип отображения;
  • 0 (false) - нет, показать сплошным типом.

По умолчанию: true

title_li(строка)
Установить заголовок списка. Если изменить этот параметр на '' (title_li=), то заголовок не будет выводиться вовсе.
По умолчанию: 'Категории'
number(число)
Установить максимальное количество отображаемых категорий (SQL LIMIT). По умолчанию выводится без ограничений.
По умолчанию: ''
echo(логический)

Выводить на экран или возвращать для обработки.

  • 1 (true) - да, выводить на экран;
  • 0 (false) - нет, просто возвратить данные.

По умолчанию: true

depth(число)

Этот параметр контролирует глубину вложенности категорий, которые будут показаны. По умолчанию 0- показывать все уровни вложенности (все дочерние категорий). С версии 2.5.

  • 0 - все уровни вложенности (По умолчанию);
  • -1 - показать все дочерние категории, но без вложенности li списков. Отменяет параметр hierarchical;
  • 1 - показать только категории первого уровня (все виды вложенных категорий не будут показываться);
  • n - число - глубина вложенности которую нужно показывать. 2 - покажет категорий первого и второго уровня.
current_category(строка/массив)
ID категории или массив из ID. К которым нужно добавить класс current-cat (class="current-cat"). Это нужно, чтобы подсветить категорию через CSS стили. В нормальном режиме такой класс добавляется к текущей категории на странице категорий. Этот параметр нужен, чтобы, например, добавить этот класс на отдельных страницах, которые не относятся к текущей категории. Добавлен с версии 2.6.
С версии 4.4. в этот параметр можно передавать массив ID.
По умолчанию: ''
pad_counts(логический)
Считать общее количество постов во вложенных категориях и показывать это число рядом с родительской категорией. Параметр включается автоматически при включенных show_counts и hierarchical. Добавлен с версии 2.9.
По умолчанию: 0 (false)
hide_title_if_empty(логический)
Нужно ли прятать $title_li если в списке нет элементов. С версии 4.4.
По умолчанию: false (всегда будет показываться)
separator(строка)
Разделитель между элементами. С версии 4.4.
По умолчанию: '<br />'
taxonomy(строка)
Название таксономии, которую нужно обрабатывать.
По умолчанию: 'category'
walker(объект)
Расширение объекта (класса), который предназначен для создание списка категорий. Передаваемый параметру объект - это расширение для класса Walker_Category или Walker.
По умолчанию: 'Walker_Category'

Примеры

#1 Сортировка по алфавиту

Для того, чтобы отсортировать категории по алфавиту (orderby=name) и включить в список только категории с ID равными 16, 3, 9 и 5 (include=3,5,9,16), можно использовать следующий код:

<ul>
	<?php wp_list_categories('orderby=name&include=3,5,9,16'); ?>
</ul>

#2 Сортировка по названию

Следующий пример сортирует категории по названию (orderby=name), показывает количество записей в каждой категории (show_count=1) и исключает из списка категорию с ID 10 (exclude=10):

<ul>
	<?php wp_list_categories('orderby=name&show_count=1&exclude=10'); ?>
</ul>

#3 Уберем заголовок списка категорий

С помощью обнуления параметра title_li. По умолчанию этот параметр равен __('Categories'), если установить его в null или '', заголовок списка не будет показан вообще. Следующий пример исключает категории 4 и 7, и убирает заголовок списка категорий:

<ul>
	<?php wp_list_categories('exclude=4,7&title_li='); ?>
</ul>

#4 Выводим только указанные рубрики

Этот пример покажет список только из категорий с ID 9, 5 и 23, и изменит заголовок списка на Автомобили, который будет заключен в теги <h2>:

<ul>
	<?php wp_list_categories('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>' ); ?>
</ul>

#5 Выведем только дочерние категории

Для того, чтобы вывести только категории вложенные в категорию 8 (child_of=8) и отсортировать их по ID (orderby=id), так же показать количество записей в каждой категории (show_count=1) и убрать из атрибута title описание категорий (use_desc_for_title=0) используйте следующий вызов функции wp_list_categories:

<ul>
	  <?php wp_list_categories('orderby=id&show_count=1&use_desc_for_title=0&child_of=8'); ?>
</ul>

#6 Удалим скобки, в которые обрамляется количество записей в каждой категории

Для этого получим список категорий в переменную (echo=0) и пропустим её через php функцию str_replace(), которая удалит скобки:

<?php
$variable = wp_list_categories('echo=0&show_count=1&title_li=<h2>Категории</h2>');
$variable = str_replace(array('(',')'), '', $variable);
echo $variable;
?>

#7 Покажем список категорий со ссылкой на RSS-ленту

Для этого используем параметр feed=RSS, так же в этом примере список будет отсортирован по названию категорий (orderby=name) и у каждой категории будет показано количество записей (show_count=1):

<ul>
   <?php wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
</ul>

#7.1 Если нужно показать ссылку-картинку вместо текста ссылки RSS фида, то используем параметр feed_image:

<ul>
   <?php wp_list_categories('orderby=name&show_count=1&feed_image=/images/rss.gif'); ?>
</ul>

#8 Выводим список произвольной (пользовательской) таксономии

С версии 3.0 стало возможно выводить списки произвольных таксономий через параметр taxonomy. Так же в этом примере показывается как передавать параметры не строкой, а массивом:

<?php
// список разделов произвольной таксономии genre

$args = array(
  'taxonomy'     => 'genre', // название таксономии
  'orderby'      => 'name',  // сортируем по названиям
  'show_count'   => 0,       // не показываем количество записей
  'pad_counts'   => 0,       // не показываем количество записей у родителей
  'hierarchical' => 1,       // древовидное представление
  'title_li'     => ''       // список без заголовка
);
?>

<ul>
<?php wp_list_categories( $args ); ?>
</ul>

#9 CSS классы для стилизации li списка

Классы создается функцией wp_list_categories(). Начальное обрамление (в тег ul или li) задается произвольно, поэтому класс списку можно задать произвольный, а в остальном можно использовать следующие селекторы:

li.categories { ... }  /* общий селектор */
li.cat-item { ... }
li.cat-item-7 { ... }  /* Рубрика с ID #7 */
li.current-cat { ... }
li.current-cat-parent { ... }
ul.children { ... }

Заметки

Добавленные параметры в разных версиях:

  • 2.3.0 — echo
  • 2.5.0 — depth
  • 2.6.0 — current_category
  • 2.7.1 — exclude_tree
  • 2.9 — pad_counts
  • 3.0 — taxonomy
  • 4.4 — hide_title_if_empty и separator. current_category стал не обязательным

Код wp list categories: wp-includes/category-template.php WP 4.9

<?php
function wp_list_categories( $args = '' ) {
	$defaults = array(
		'child_of'            => 0,
		'current_category'    => 0,
		'depth'               => 0,
		'echo'                => 1,
		'exclude'             => '',
		'exclude_tree'        => '',
		'feed'                => '',
		'feed_image'          => '',
		'feed_type'           => '',
		'hide_empty'          => 1,
		'hide_title_if_empty' => false,
		'hierarchical'        => true,
		'order'               => 'ASC',
		'orderby'             => 'name',
		'separator'           => '<br />',
		'show_count'          => 0,
		'show_option_all'     => '',
		'show_option_none'    => __( 'No categories' ),
		'style'               => 'list',
		'taxonomy'            => 'category',
		'title_li'            => __( 'Categories' ),
		'use_desc_for_title'  => 1,
	);

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

	if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] )
		$r['pad_counts'] = true;

	// Descendants of exclusions should be excluded too.
	if ( true == $r['hierarchical'] ) {
		$exclude_tree = array();

		if ( $r['exclude_tree'] ) {
			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude_tree'] ) );
		}

		if ( $r['exclude'] ) {
			$exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude'] ) );
		}

		$r['exclude_tree'] = $exclude_tree;
		$r['exclude'] = '';
	}

	if ( ! isset( $r['class'] ) )
		$r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy'];

	if ( ! taxonomy_exists( $r['taxonomy'] ) ) {
		return false;
	}

	$show_option_all = $r['show_option_all'];
	$show_option_none = $r['show_option_none'];

	$categories = get_categories( $r );

	$output = '';
	if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) {
		$output = '<li class="' . esc_attr( $r['class'] ) . '">' . $r['title_li'] . '<ul>';
	}
	if ( empty( $categories ) ) {
		if ( ! empty( $show_option_none ) ) {
			if ( 'list' == $r['style'] ) {
				$output .= '<li class="cat-item-none">' . $show_option_none . '</li>';
			} else {
				$output .= $show_option_none;
			}
		}
	} else {
		if ( ! empty( $show_option_all ) ) {

			$posts_page = '';

			// For taxonomies that belong only to custom post types, point to a valid archive.
			$taxonomy_object = get_taxonomy( $r['taxonomy'] );
			if ( ! in_array( 'post', $taxonomy_object->object_type ) && ! in_array( 'page', $taxonomy_object->object_type ) ) {
				foreach ( $taxonomy_object->object_type as $object_type ) {
					$_object_type = get_post_type_object( $object_type );

					// Grab the first one.
					if ( ! empty( $_object_type->has_archive ) ) {
						$posts_page = get_post_type_archive_link( $object_type );
						break;
					}
				}
			}

			// Fallback for the 'All' link is the posts page.
			if ( ! $posts_page ) {
				if ( 'page' == get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) {
					$posts_page = get_permalink( get_option( 'page_for_posts' ) );
				} else {
					$posts_page = home_url( '/' );
				}
			}

			$posts_page = esc_url( $posts_page );
			if ( 'list' == $r['style'] ) {
				$output .= "<li class='cat-item-all'><a href='$posts_page'>$show_option_all</a></li>";
			} else {
				$output .= "<a href='$posts_page'>$show_option_all</a>";
			}
		}

		if ( empty( $r['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
			$current_term_object = get_queried_object();
			if ( $current_term_object && $r['taxonomy'] === $current_term_object->taxonomy ) {
				$r['current_category'] = get_queried_object_id();
			}
		}

		if ( $r['hierarchical'] ) {
			$depth = $r['depth'];
		} else {
			$depth = -1; // Flat.
		}
		$output .= walk_category_tree( $categories, $depth, $r );
	}

	if ( $r['title_li'] && 'list' == $r['style'] && ( ! empty( $categories ) || ! $r['hide_title_if_empty'] ) ) {
		$output .= '</ul></li>';
	}

	/**
	 * Filters the HTML output of a taxonomy list.
	 *
	 * @since 2.1.0
	 *
	 * @param string $output HTML output.
	 * @param array  $args   An array of taxonomy-listing arguments.
	 */
	$html = apply_filters( 'wp_list_categories', $output, $args );

	if ( $r['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

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

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

Еще из раздела: Рубрики

wp_list_categories 88 комментариев
Полезные 7 Вопросы 5 Все
  • Эдуард cайт: i-advocat.ru @

    Приветствую, тимур и все сочувствующие.
    okato - это иерархическая таксономия, которая содержит данные общероссийского классификатора административно-территориальных образований, т.е. это данные о населенных пунктах России на трех уровнях классификации, начиная с регионов на первом уровне и кончая мелкими деревеньками на самом последнем третьем уровне классификации.
    Итак, код, который я поместил в header.php выглядит следующим образом:

     'okato', // название таксономии
    'orderby'      => 'name',  // сортируем по названиям
    'show_count' => 0,       // не показываем количество записей
    'pad_counts'   => 0,       // не показываем количество записей у родителей
    'hierarchical' => 1,       // древовидное представление
    'title_li' => 'OKATO',
    'show_option_none' => 'Регионы отсутствуют',
    'order' => 'DESC', // Сортируем по убыванию
     'orderby' => 'count', // по количеству записей в регионе
    'depth' => 3,
    'show_count' => false, // Показывать количество записей в каждом регионе
    'hierarchical' => true,
    ' hide_title_if_empty' => true,
    'hide_empty' => false, // Не скрывать пустые регионы
    ); 
    if (is_tax('okato')) {
    $term = get_term_by('slug', get_query_var('okato'), 'okato', 'ARRAY_A');
    $args['include'] = $term['term_id'];
    $args['depth'] = 2;
    }
    ?>
    
    <ul>
    
    </ul>

    т.е. Если мы находимся на странице архива терма таксономии, выводится только архивный терм.
    Как мне сделать так, чтобы на странице архива выводились все его дочерние термы.
    При этом нужно иметь ввиду, что терм может быть и на первом уровне классификации, т.е. регион. В этом случае нужно выводить объекты второго уровня.
    На страничке архива кемеровской области нужно показывать список районов кемеровской области и городов областного подчинения.

  • Андрей

    Добрый день.. а как мне вывести вместо названии категории его описание ?

    class Walker_Category_Custom extends Walker_Category {
    function start_lvl(&$output, $depth=0, $args=array()) {
    $output .= "";
    }
    function end_lvl(&$output, $depth=0, $args=array()) {
    $output .= "";
    }
    function start_el(&$output, $item, $depth=0, $args=array(),$current_object_id = 0) {
    $output.= '<a href="'.home_url('catalog_tax/'.$item->slug).'">
    '.esc_attr($item->description);
    }
    function end_el(&$output, $item, $depth=0, $args=array()) {
    $output .= "</a><br />\n";
    }
    }

    придумал новый класс но при этом пропали (количество записей) после ссылки

  • Михаил @

    Добрый день. Возможно вывести список элементов таксономии своим шаблоном? Например так - http://prntscr.com/ekm1j7
    С дополнительными полями (Картинкой, описанием рубрики)

  • Василиса

    Скажите, а есть ли возможность встроить каким-то образом вывод taxonomy-images? Это было бы идеально.

  • Игор @

    <?php wp_list_categories('exclude=1&hide_empty=0&depth=1&show_count=1&title_li=<h2>Рубрики</h2>'); ?>

    Здравствуйте!
    Эта штука не работает почему-то, хотя должен убрать рубрику из виджета. WP последний

    Ответить4 месяца назад #
  • Азиз cайт: sngpoik.ru

    Здравствуйте вы не могли бы мне помочь в моём сайте когда Подаёшь объявление есть раздел категории в раздели категории когда выбираешь категорию появляются категории и дочерние.Я хочу чтобы по порядку всё появилось.
    Пример:Транспорт---->Машина---->Руль
    Что мне делать ?

    Ответить2 месяца назад #
  • Web-Blog21 cайт: web-blog.su

    У меня вопрос: "А можно как-то получить список ID или SLAG категорий?".

    Ответить2 месяца назад #
  • Андрей

    Доброго времени суток! Спасибо за прекрасную статью! Всё гуд, вывожу термы таксономии в сайдбар для всех страниц этой таксономии и для отдельной страницы кастомного шаблона, всё выводится корректно, НО! Когда я через js добавляю к непустым термам иконками + - для нажатия на них для появления/скрытия соответственно дочернего списка, результат работы скрипта виден только на отдельной странице шаблона. На страницах таксономии список не реагирует на скрипт вообще. Вы не могли бы помочь понять, что это за избирательность такая?)) Заранее огромное спасибо)

    Ответить26 дней назад #

Здравствуйте, !

Ваш комментарий