Функция category_description() в WordPress используется для получения описания определённой категории, которое можно указать в админ-панели на странице редактирования категории (в разделе «Записи > Рубрики»). Она возвращает строку с описанием категории и используется в шаблонах для отображения этой информации пользователю.
category_description( int $category ): string
Параметры
$category(int) — ID категории, описание которой нужно получить. Этот параметр опционален. Если параметр не указан и функция вызывается на странице категории, то будет возвращено описание текущей категории.
Возвращаемое значение
- Строка — описание категории. Если описание отсутствует, функция возвращает пустую строку.
Важные замечания
- Если эта функция используется на страницах архивов, отличных от страницы категории (
category.php), перед её использованием следует убедиться, что это действительно страница категории с помощью условного тегаis_category(). В противном случае это может привести к ошибкам. - Функция
category_description()работает на основе функцииterm_description()и не имеет связанных хуков.
Пример 1: Обычный вывод описания категории по её ID
В этом примере мы выводим описание категории с ID 7 с помощью оператора echo. Поскольку функция возвращает строку с описанием, для отображения информации на странице нужно использовать echo.
<?php echo category_description(7); ?>
Пример 2: Условный вывод описания категории
Здесь мы проверяем, есть ли описание у текущей категории, прежде чем вывести его на экран. Если описания нет, выведем сообщение о его отсутствии.
<?php
if ( $cat_desc = category_description() ) {
echo '<div class="cat__desc">' . $cat_desc . '</div>';
} else {
echo '<div class="no__cat__desc">Описание отсутствует!</div>';
}
?>
Результат:
- Если у категории есть описание, оно будет выведено в блоке с классом
cat__desc. - Если описание отсутствует, будет выведено сообщение «Описание отсутствует!».
Пример 3: Получение описания категории через слаг (slug)
Для получения описания категории не по её ID, а по слагу, можно использовать функцию get_category_by_slug().
<?php echo category_description( get_category_by_slug( 'category-slug' )->term_id ); ?>
Этот пример полезен, если слаг категории известен, а ID нет.
Пример 4: Альтернативный способ получения описания категории через слаг
Для более простой и оптимизированной версии того же примера можно напрямую использовать свойство description объекта категории:
<?php echo get_category_by_slug( 'category-slug' )->description; ?>
Это сокращает шаги и избавляет от необходимости получения ID категории через отдельную функцию.
Пример 5: Очистка описания категории от ненужных шорткодов с помощью фильтра term_description
Иногда в описании категории могут использоваться шорткоды, которые не должны отображаться при выводе описания. Чтобы очистить описание от шорткодов, например, [image], можно воспользоваться фильтром:
add_filter('term_description', 'clear_term_description_image_shortcode');
function clear_term_description_image_shortcode($value) {
return preg_replace('@\[image=[^\]]*\]@', '', $value);
}Этот код удаляет все шорткоды вида [image=...] из описания категории.
Использование с заголовком категории
Часто описание категории отображается вместе с её заголовком. Для этого можно использовать функцию single_cat_title():
<div>
<strong><?php single_cat_title( __( 'Currently browsing', 'textdomain' ) ); ?></strong>:
<?php echo category_description(); ?>
</div>
Результат:
<strong>Currently browsing WordPress</strong>: WordPress is a favorite blogging tool of mine and I share tips and tricks for using WordPress here.
В этом примере сначала выводится заголовок категории с текстом «Currently browsing» перед ним, а затем — описание категории.
Заключение
Функция category_description() — удобный инструмент для вывода описания категорий в WordPress. Используя различные примеры из этого руководства, можно гибко управлять тем, как описание выводится на сайте, включая использование условных тегов, фильтров и других вспомогательных функций, таких как get_category_by_slug() и single_cat_title().