wp_list_categories() │ WP 2.1.0

Виводить список категорій як посилань. Якщо перейти за посиланням, будуть показані всі пости з категорії.

Працює на основі:
get_categories() ,
walk_category_tree()

Хуки з функції

wp_list_categories

Повертає

null|Строку|false. HTML код якщо echo=1 . Якщо echo=0 поверне HTML код змінну для подальшої обробки.

Шаблон використання

$ args = array (
	'show_option_all' => '',
	'show_option_none' => __('No categories'),
	'orderby' => 'name',
	'order' => 'ASC',
	'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>';

Використання

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

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

Крім наведених нижче параметрів може приймати параметри get_terms() .

child_of (число)

Показати дочірні категорії. У параметрі вказується ID батьківської категорії (категорія, вкладені категорії якої потрібно показати).

current_category (рядок/масив)

ID категорії або масив із ID. До яких слід додати клас current-cat(class=”current-cat”). Це потрібно, щоб підсвітити категорію через стилі CSS.

У нормальному режимі такий клас додається до поточної категорії на сторінці категорії. Цей параметр потрібний, щоб, наприклад, додати цей клас на окремі сторінки, які не належать до поточної категорії.

З версії 4.4. у цей параметр можна надсилати масив ID.
За замовчуванням: ”

depth (число)

Цей параметр контролює глибину вкладеності категорій, які будуть показані. За замовчуванням 0– показувати всі рівні вкладеності (всі дочірні категорії). З версії 2.5.

0– Усі рівні вкладеності (За замовчуванням);
-1– показати всі дочірні категорії, але без вкладеності списків. Скасує параметр hierarchical;
1– показати лише категорії першого рівня (всі види вкладених категорій не показуватимуться);
n– Число – глибина вкладеності яку потрібно показувати. 2– покаже категорій першого та другого рівня.

echo (логічний)

Виводити на екран або повертати для обробки.

1 (true)– так, виводити на екран;
0 (false)– Ні, просто повернути дані.

Типово: true

exclude (рядок)

Виключити категорії зі списку. Потрібно вказувати ID категорій через кому.

Якщо цей параметр вказано, параметр child_ofбуде скасовано.
Якщо параметр heiararchical=true, то виключатиметься вся гілка. Якщо heiararchical=false, то для виключення гілки використовуйте параметр exclude_tree.

За замовчуванням: ”

exclude_tree (рядок)

Виключити дерево категорій зі списку. Вказуйте ID категорій через кому. Параметр include має бути порожнім. Якщо параметр
heirarchical=true, використовуйте
exclude замість
exclude_tree .

За замовчуванням: ”

include (рядок / масив)

Вивести списком лише зазначені категорії. Список ID категорій проходить через
wp_parse_id_list , тому можна вказувати ID рядком через ком або масивом.

За замовчуванням: ”

hide_empty (логічний)

Чи приховувати категорії, у яких немає записів?

0 (false)– Показувати порожні (не приховувати);
1 (true)– Не показувати порожні категорії (приховувати).

За замовчуванням: 1

hide_title_if_empty (логічний)

Чи потрібно ховати
$title_li, якщо в списку немає елементів. З версії 4.4.

За замовчуванням: false (завжди показуватиметься)

hierarchical (логічний)

Показувати категорії як дерево. Показувати вкладені (дочірні категорії) як вкладений список.

1 (true)– так, деревоподібний тип відображення;
0 (false)– Ні, показати суцільним типом.

Типово: true

order (рядок)

Напрямок сортування:

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

За замовчуванням: ‘ASC’

orderby (рядок)

Сортування списку за певними критеріями. Наприклад, за кількістю постів у кожній категорії або за назвою категорій. Доступні такі критерії:

ID– Сортування за ID;
name– сортування за назвою (за умовчанням);
slug– Сортування по алт. імені (slug);
count– за кількістю записів у категорії;
term_group– по групі.

За замовчуванням: ‘name’

separator (рядок)

Розділювач між елементами. З версії 4.4.

За замовчуванням: ‘ <br /> ‘

show_count (логічний)

Показувати/немає кількість записів у категорії. Число записів буде показано після назви категорії у дужках (наприклад, Психологія (16)).

1 (true)– показувати кількість записів;
0 (false)– Не показувати кількість записів.

show_option_all (рядок)

Текст відображає всі категорії.

Якщо передати не порожній рядок, наприклад 'Все категории', то до списку буде додано посилання на всі категорії (часто це посилання на головну сторінку блогу). Текст посилання стане текст переданий параметру, в даному випадку Все категории.
За замовчуванням: ”

show_option_none (рядок)

Якщо функція не знайшла жодної категорії для показу, буде показано цей текст.

За замовчуванням: ‘Немає рубрик’

style (рядок)

Стиль виведення списку.

list– означає, що потрібно виводити списком у тезі <li>, вкладеність категорій буде дотримана.
none– будуть виведені лише посилання на категорії ( <a> ) розділені тегом <br>.

За замовчуванням: ‘list’

taxonomy (рядок)

Назву таксономії, яку потрібно обробляти.

Типово: ‘category’

title_li (рядок)

Встановіть заголовок списку. Якщо змінити цей параметр на
” (
title_li=), то заголовок зовсім не виводитися.

За замовчуванням: ‘Категорії’

use_desc_for_title (логічний)

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

1 (true)– так, вставляти опис у title, якщо він є;
0 (false)– ні, не використовувати опис (буде: Переглянути всі записи в рубриці “назва категорії”).

Типово: true

number (число)

Встановити максимальну кількість категорій, що відображаються (SQL LIMIT). За промовчанням виводиться без обмежень.

За замовчуванням: ”

pad_counts (логічний)

Вважати загальну кількість постів у вкладених категоріях і показувати це число поряд із батьківською категорією. Параметр увімкнеться автоматично при увімкнених
show_countі
hierarchical.

Типово: 0 (false)

feed (логічний)

Показати поруч із назвою посилання на RSS фід (rrs-2) категорії. Текст, переданий у цьому параметрі, стане текстом посилання.

За замовчуванням: ”

feed_type (рядок)

Тип фіду

Типово: ‘rss-2’

feed_image (рядок)

Показати поруч із назвою посилання-картинку на RSS фід (rrs-2) категорії. У параметрі потрібно вказати посилання на зображення. Якщо цей параметр вказано, параметр
$feedбуде скасовано.

За замовчуванням: ”

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
$cats = wp_list_categories('echo=0&show_count=1&title_li=<h2>Категорії</h2>');
$cats = str_replace( ['(',')'], '', $cats );
echo $cats;
?>

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

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

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

#8 Якщо потрібно показати посилання-картинку замість тексту посилання RSS-фіда, то використовуємо параметр `feed_image`:

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

#9 Виводимо список довільної (користувальної) таксономії

З версії 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>

#10 CSS класи для стилізації li списку

CSS Класи створюється автоматично функцією wp_list_categories(). Початкове обрамлення (тег ul) задається довільно, тому клас списку можна задати довільний. А для li-тегу використовуються наступні css класи:

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став не обов’язковим

список змін

З версії 2.1.0	Введено.
З версії 4.4.0	`Встановлено hide_title_if_empty` and separator `arguments` .
З версії 4.4.0	The `current_category` argument був змінений на optionally accept array of values.

wp list categories ^{WP 6.0.2}

wp-includes/category-template.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,
	);

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

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

	// Descendants of exclusions може бути excluded too.
	if ( true == $parsed_args['hierarchical'] ) {
		$exclude_tree = array();

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

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

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

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

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

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

	$categories = get_categories( $parsed_args );

	$output = '';

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

	if ( empty( $categories ) ) {
		if ( ! empty( $show_option_none ) ) {
			if ( 'list' === $parsed_args['style'] ) {
				$output .= '<li class="cat-item-none">' . $ show_option_none . '</li>';
			} else {
				$output .= $show_option_none;
			}
		}
	} else {
		if ( ! empty( $show_option_all ) ) {

			$posts_page = '';

			// Для taxonomies, що досить тільки до custom post types, point to a valid archive.
			$taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] );
			if ( ! in_array( 'post', $taxonomy_object->object_type, true ) && ! in_array( 'page', $taxonomy_object->object_type, true ) ) {
				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' === $parsed_args['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( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
			$current_term_object = get_queried_object();
			if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) {
				$parsed_args['current_category'] = get_queried_object_id();
			}
		}

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

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

	/**
	 * Filters HTML output of taxonomy list.
	 *
	 * @ Since 2.1.0
	 *
	 * @param string $output HTML output.
	 * @param array|string $args На array or query string of taxonomy-listing arguments. See
	 * wp_list_categories() for information on accepted arguments.
	 */
	$html = apply_filters( 'wp_list_categories', $output, $args );

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

wp_list_categories() │ WP 2.1.0

Хуки з функції

Повертає

Шаблон використання

Використання

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

Приклади

#1 Сортування за алфавітом

#2 Сортування за назвою

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

#4 Виводимо лише вказані рубрики

#5 Виведемо лише дочірні категорії

#6 Видалимо дужки, в які обрамляється кількість записів у кожній категорії

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

#8 Якщо потрібно показати посилання-картинку замість тексту посилання RSS-фіда, то використовуємо параметр feed_image:

#9 Виводимо список довільної (користувальної) таксономії

#10 CSS класи для стилізації li списку

нотатки

список змін

wp list categories WP 6.0.2

Зв’язані функції

Список (wp_list списки)

Рубрики

Таксономії: рубрики, мітки, …

Залишити відповідь Скасувати коментар

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

#8 Якщо потрібно показати посилання-картинку замість тексту посилання RSS-фіда, то використовуємо параметр `feed_image`:

wp list categories ^{WP 6.0.2}