SEO Маяк

Всем привет! Сегодня на seo-mayak.com мы будем разбирать функцию wp_list_categories(), которая отвечает за вывод рубрик на WordPress.

Рубрики есть на большинстве сайтах, будь то коммерческие проекты или личные блоги и поэтому данная статья будет полезна многим веб-мастерам.

Известно, что рубрики или категории, как угодно, разбивают сайт на разделы. Заголовки данных разделов выводятся в виде меню на боковой панели сайта (сайдбаре) или в шапке, а в некоторых темах рубрики можно найти даже в подвале. Как они там оказываются?

Конечно в админке есть интерфейс виджетов, с помощью которых можно вывести меню на экран. Но я спрашивал не об этом!

Как там оказываются заголовки разделов и ссылки на них? Ведь мы же их там не прописывали. Вот об этом мы и будем сегодня с Вами говорить.

В WordPress заложено несколько функций, которые так или иначе, касаются вывода рубрик, но самая используемая из них — это wp_list_categories().

Функция имеет массу настроек и уверен, что каждому, даже самому зеленому вебмастеру, не лишнем будет знать, как работает данная функция. Поехали!

Функция wp_list_categories()

Для начала я хочу сказать несколько слов об иерархической цепочке функций WordPress по работе с рубриками, где wp_list_categories() занимает не самое первое место.

Функция wp_list_categories() — это, так сказать, дочерняя функция, т.е. она работает на основе другой функции, а именно get_categories(), которая в свою очередь тоже имеет своего родителя — функцию get_terms().

В данной статье я не стану описывать всю анатомию взаимодействия вышеупомянутых функций, оставлю данную тему будущих постов, так что подписывайтесь на обновления блога, будет интересно!

Достаточно будет просто иметь представление о том, что процесс вывода рубрик — это сложное, многоступенчатое программное действо, которое в долю секунды осуществляется благодаря совместной работе нескольких php функций.

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

Теперь, для наглядного примера, возьмем стандартный виджет «Текст» и вставим в него функцию wp_list_categories(). Должно получится так:

Сохраняем и идем смотреть результат:

Вот так функция wp_list_categories() формирует вывод рубрик по умолчанию. Даже заголовок есть!

А теперь давайте разберемся, какие аргументы может принимать функция.

Все аргументы функции wp_list_categories()

В данном шаблоне приведены все аргументы которые может принимать функция.

Это шаблон! Не надо его никуда вставлять!

<?php 
    $args = array(
	'show_option_all'    => '',
	'orderby'            => 'name',
	'order'              => 'ASC',
    'separator'          => '<br />',
	'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'       => 1,
	'title_li'           => __( 'Categories' ),
	'show_option_none'   => __( '' ),
	'number'             => null,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => null
    );
    wp_list_categories( $args ); 
?>

Итак, давайте пройдемся по всем аргументам и рассмотрим их на конкретных примерах. Приступим.

show_option_all (строка)

Значением данного аргумента может быть любой текст, который будет выведен первым пунктом в общем списке рубрик в качестве ссылки на главную страницу. Например:

<ul>
<?php wp_list_categories('show_option_all=Все записи'); ?>
</ul>

По умолчанию: нет.

orderby (строка)

C помощью аргумента orderby можно сортировать вывод рубрик, в зависимости от его значений. Вот список значений:

ID — Сортировка будет осуществляться по ID родительских рубрик, начиная с 1 и по возрастанию;
name — Сортировка будет осуществляться по названию родительских рубрик, согласно алфавиту;
slug — Сортировка будет осуществляться по ярлыкам родительских рубрик, согласно алфавиту;
count — Сортировка будет осуществляться по количеству записей;
term_group — Сортировка по группе.

Давайте рассмотрим пример сортировки по количеству записей в рубриках, дополнительно используя аргумент show_count:

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

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

order (строка)

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

ASC — сортировка в обычном порядке (от меньшего к большему);
DESC — сортировка в обратном порядке (от большего к меньшему);

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

<ul>
<?php wp_list_categories('order=DESC&orderby=count&show_count=1');?>
</ul>

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

separator (строка)

С помощью этого аргумента можно задавать разделитель между ссылками. Действует только если значение аргумента: 'style' установлено 'none'.

<ul>
<?php wp_list_categories('separator=<br />&style=none&orderby=count&show_count=1');?>
</ul>

По умолчанию: <br />.

style (строка)

С помощью этого аргумента можно задавать html структуру для меню рубрик.

list — Структура html для рубрик будет формироваться с использованием тегов <ul> и <li>;
none — Список рубрик будет выведен в виде обычных ссылок. Если не изменено значение аргумента: 'separator', то перенос строк будет осуществляться с помощью тега <br/> (вложенность подрубрик будет соблюдена).

<ul>
<?php wp_list_categories('style=none&orderby=count&show_count=1');?>
</ul>

По умолчанию: list.

show_count (логическое/число)

Определяет показывать или не показывать количество записей в рубриках.

1 — Будет выводится количество записей в каждой рубрике;
0 — Количество записей выводится не будет.

По умолчанию: 0.

hide_empty (логическое/число)

Определяет включать или не включать в меню пустые рубрики.

1 — Пустые рубрики будут скрыты;
0 — Пустые рубрики будут включены в список.

<ul>
<?php wp_list_categories('hide_empty=0&show_count=1');?>
</ul>

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

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

Для каждой рубрики можно сделать описание (description). Если такое описание существует, то с помощью данного аргумента его можно встроить в html код.

1 — Описание (если оно есть) будет встроено в html код;
0 — Описание встраиваться не будет.

<ul>
<?php wp_list_categories('use_desc_for_title=1&show_count=1');?>
</ul>

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

child_of (число)

В качестве значения для аргумента child_of служит ID родительской рубрики, из которой надо вывести все дочерние категории. Допускается указывать только один ID.

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

По умолчанию: 0.

feed (строка)

Добавляет к названию каждой рубрики ссылку на rss-канал. В качестве значения задается текст, который и будет отображаться.

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

Не знаю использовал ли кто-нибудь данный аргумент, по мне, так он лишний.

По умолчанию: нет.

feed_type (строка)

Указывает на тип фида.

По умолчанию: rss-2.

feed_image (строка)

В качестве значения этого аргумента задается ссылка на изображение, которое будет выводится рядом с названием каждой рубрики, при этом аргумент feed перестает действовать.

<ul>
<?php wp_list_categories('feed_image=/wp-content/themes/wp-themes-blogger/images/feed_32x32.png&feed=RSS&show_count=1');?>
</ul>

По умолчанию: нет.

exclude (массив/строка)

Аргумент exclude позволяет исключать одну или несколько рубрик из списка по их ID, при этом действие аргумента child_of (если он указан) будет отменено.

Если исключить родительские рубрики, например с ID 10 и 14:

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

В этом случаи будут исключены все дочерние рубрики, относящиеся к родителям с вышеупомянутыми ID.

Чтобы этого не произошло, в значении аргумента hierarchical надо установить 0, при этом дерево рубрик будет отключено.

Если hierarchical равен 0, то для исключения всей ветки используется аргумент exclude_tree.

По умолчанию: нет.

exclude_tree (массив/строка)

C помощью данного аргумента можно исключить из списка дерево одной или нескольких рубрик. В значении указывается ID одной или нескольких рубрик через запятую.

<ul>
<?php wp_list_categories('exclude_tree=10,14&show_count=1');?>
</ul>

Если значение аргумента hierarchical равно 0, то используется аргумент exclude, вместо exclude_tree.

По умолчанию: нет.

include (строка)

Аргумент include позволяет вывести в меню только указанные рубрики. ID рубрик перечисляется через запятую.

<ul>
<?php wp_list_categories('include=10,14&show_count=1');?>
</ul>

Рубрики выводятся в точно соответствии с ID , т.е. если указать ID родительских рубрик, дочерние рубрики выведены не будут.

По умолчанию: нет.

hierarchical (логическое)

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

1 — выведет древовидный список рубрик.
0 — выведет рубрики сплошным типом, при этом родительские рубрики будут исключены.

<ul>
<?php wp_list_categories('hierarchical=0&show_count=1');?>
</ul>

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

title_li (строка)

Устанавливает заголовок для списка рубрик. В качестве значения указывается текст.

<ul>
<?php wp_list_categories('title_li=Все разделы&show_count=1');?>
</ul>

По умолчанию: Рубрики.

show_option_none (строка)

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

<ul>
<?php wp_list_categories('include=99,100&show_option_none=Рубрик не найдено');?>
</ul>

По умолчанию: Нет рубрик.

number (число)

В данной аргументе можно установить лимит на отображение рубрик. Например:

<ul>
<?php wp_list_categories('number=5&show_count=1');?>
</ul>

Будет выведено 5 рубрик.

По умолчанию: нет.

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

Применения данного аргумента позволяет возвращать html код списка рубрик или выводить его на экран.

0 — Возвращать данные для дальнейшей обработки;
1 — Выводить список рубрик на экран.

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

depth (число)

Определяет глубину вложенности рубрик.

0 — Будут выведены все уровни рубрик без ограничений;
-1 — Будут выведены все уровни, но без дерева (сплошным типом). Отменяет аргумент hierarchical;
1 — Будут выведены рубрики только первого уровня. Все дочерние категории исключаются.
n — Произвольное числовое значение глубины вложенности рубрик для вывода на экран.

По умолчанию: 0.

current_category (число/массив)

Интересный аргумент, позволяющий добавлять css класс current-cat к определенной рубрике. В обычном режиме такой класс добавляется к текущей рубрики и в основном применяется для подсветки. Также данный класс используется в php скриптах для удаления циклических ссылок.

В качестве значения указывается ID рубрики или нескольких рубрик через запятую.

<ul>
<?php wp_list_categories('current_category=8,51&show_count=1'); ?>
</ul>

По умолчанию: текущая рубрика.

pad_counts (логическое)

Суммирует количество записей в дочерних рубриках и выводит результат в родительскую рубрику.

1 — выводит количество записей в родительскую рубрику;
0 — количество записей не выводится.

<ul>
<?php wp_list_categories('pad_counts=0&show_count=1'); ?>
</ul>

Значение 1 устанавливается автоматически при использовании show_count=1 и hierarchical=1.

По умолчанию: 0.

hide_title_if_empty (логическое)

Определяет выводить или не выводить заголовок списка рубрик если нет ни одной записи.

0 — выводить заголовок;
1 — не выводить заголовок.

По умолчанию: 0.

taxonomy (строка)

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

<?php
$args = array(
  'taxonomy'     => 'product', // Название произвольной таксономии
  'orderby'      => 'name',  // Сортируем по названия, согласно алфавиту 
  'show_count'   => 1,       // Выводим количество записей
  'exclude'   => 10,22,       // Исключаем рубрики с ID 10 и 14
  'hierarchical' => 1,       // Включаем древовидный список
  'title_li'     => '',    // Убираем заголовок списка
  'use_desc_for_title' => 1   // Выводим описание рубрик
);
?>
// Код для вставки в виджет или другое место на сайте
<ul>
<?php wp_list_categories( $args ); ?>
</ul>

По умолчанию: category.

walker (объект)

Аргумент принимает расширение объекта (класса), который предназначен для создание списка категорий. Передаваемый аргументу объект — это расширение для класса Walker_Category или Walker.

По умолчанию: Walker_Category.

Функция возвращает: HTML-контент, только если аргумент «echo» равен 0.

Встроенные CSS классы для тегов li и ul

li.categories { ... }  /* общий селектор */
li.cat-item { ... }    /* для всех рубрик в отдельности */
ul.children { ... }  /* селектор для родительских рубрик */
li.cat-item-7 { ... }  /* селектор для рубрики с ID 7 */
li.current-cat { ... }  /* селектор для текущей рубрики */
li.current-cat-parent { ... } /* селектор для родительской рубрики текущей подрубрики */

Хуки функции

В работу функции можно вмешаться с помощью одноименного хука-фильтра wp_list_categories:

function filter_wp_list_categories(){
	/* Какой-то сценарий */
}
add_filter('wp_list_categories', 'filter_wp_list_categories');

Живой пример использования хука можно посмотреть в статье Сквозные ссылки.

Таблица изменений

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;
	}
}

До встречи!

С уважением, Виталий Кириллов

Статьи по теме:

Title, description, keywords и h1 для категорий (рубрик) WordPress
Редактор для категорий (рубрик), меток и произвольных таксономий
Категории WordPress — термы и таксономии
Шаблоны для категорий — как сделать каталог из рубрики