Тег шаблона: wp_list_categories

11.02.2010
Описание

Данный тег шаблона выводит список рубрик в виде ссылок. Начиная с версии 2.1, этот тег заменил устаревшие и не рекомендуемые к использованию функции list_cats() и wp_list_cats().

Использование
<?php wp_list_categories( $args ); ?>
По умолчанию
<?php $args = array(
    'show_option_all'    => ,
    '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'            => ,
    'current_category'   => 0,
    'hierarchical'       => true,
    'title_li'           => __( 'Categories' ),
    'number'             => NULL,
    'echo'               => 1,
    'depth'              => 0
); ?>

Функция по умолчанию:

  • не выводит ссылку на записи из всех рубрик
  • сортирует рубрики по их названиям по возрастанию
  • не выводит дату публикации последней записи в рубриках
  • выводит список рубрик в list формате (в тегах <li> и </li>)
  • не выводит число записей в рубриках
  • скрывает пустые (без опубликованных записей) рубрики
  • использует описания рубрик для указания title атрибута в ссылках на рубрики
  • не выводит список из подрубрик одной только указанной главной рубрики
  • не выводит картинку или ссылку на RSS ленту рубрик
  • включает в список все рубрики и не исключает ни одну из них
  • выделяет текущую рубрику стилем "current-cat"
  • выводит список рубрик в иерархической структуре
  • выводит заголовок "Рубрики"
  • не ограничивает количество рубрик в списке
  • выводит результаты
  • не ограничивает список по глубине вложенности рубрик
Параметры

show_option_all

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

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

orderby

(строка) (необязательный) - выбор сортировки для вывода рубрик.

  • ID - сортировка по ID рубрик
  • name - алфавитная сортировка по названиям рубрик (по умолчанию)
  • slug - алфавитная сортировка по ярлыкам рубрик
  • count - сортировка по числу записей в рубрике
  • term_group - сортировка по "группам терминов" (?)

order

(строка) (необязательный) - выбор направления сортировки. направление может быть возрастающим или убывающим (начиная с нижнего элемента списка).

  • ASC - по умолчанию
  • DESC

show_last_update

(boolean) (необязательный) - вывод даты публикации последней записи в рубриках. на момент публикации этой статьи (версия WordPress 2.9.1) данный параметр работает некорректно, выводя или неправильную дату (1970-01-01) или не выводя ее вообще. это официально признанный баг и разработчики планируют его исправить в следующих версиях движка.

  • 1 (true)
  • 0 (false) - по умолчанию

style

(строка) (необязательный) - стиль отображения списка рубрик. list формат выведет рубрики в тегах <li> и </li>, а формат none разделит рубрики тегами переноса строки <br />.

  • list - по умолчанию
  • none

show_count

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

  • 1 (true)
  • 0 (false) - по умолчанию

hide_empty

(boolean) (необязательный) - скрытие рубрик без опубликованных записей.

  • 1 (true) - по умолчанию
  • 0 (false)

use_desc_for_title

(boolean) (необязательный) - использование описания рубрики для формирования титла ссылки на нее (атрибут title). при выключенном параметре use_desc_for_title или при отсутствии описания рубрики title атрибут будет сформирован из стандартной фразы "Просмотреть все записи в рубрике 'Название рубрики'".

  • 1 (true) - по умолчанию
  • 0 (false)

child_of

(число) (необязательный) - вывод списка из подрубрик только одной указанной главной рубрики (в значении надо указать ID главной рубрики).

feed

(строка) (необязательный) - текст для ссылки на RSS ленту рубрики. если текст не указан, то и ссылка не будет показана.

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

feed_type

(boolean) (необязательный) - тип формируемой RSS ленты. значение параметра игнорируется, если не указаны параметры feed или feed_image.

  • atom
  • rdf
  • rss
  • rss2 - по умолчанию

feed_image

(строка) (необязательный) - урл картинки для ссылки на RSS ленту рубрики. при заданном параметре feed_image параметр feed будет игнорироваться.

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

exclude

(строка) (необязательный) - исключение одной или нескольких рубрик из списка. для исключения рубрик надо указывать их ID через запятую.

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

exclude_tree

(строка) (необязательный) - исключение рубрики и всех ее подрубрик из списка. используется только при выключенном параметре hierarchical, в других случаях рубрику и ее подрубрики можно исключить параметром exclude.

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

include

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

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

hierarchical

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

  • 1 (true) - по умолчанию
  • 0 (false)

title_li

(строка) (необязательный) - определение заголовка и стиля для этого заголовка. по умолчанию значение заголовка равно "_Categories" (в русской локализации выводится "Рубрики"). если параметр указан, но не задан, то заголовок выведен не будет.

number

(число) (необязательный) - число выводимых рубрик.

По умолчанию без ограничений.

echo

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

  • 1 (true) - по умолчанию
  • 0 (false)

depth

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

  • 0 - вывод всех рубрик и всех подрубрик (по умолчанию)
  • -1 - все рубрики и подрубрики будут выведены одним списком (без вложенности). параметр hierarchical при этом будет игнорироваться
  • 1 - вывод только родительских рубрик
  • n - вывод рубрик и подрубрик до указанной (n - число) глубины

current_category

(число) (необязательный) - добавление стиля "current-cat" к указанной рубрике. по умолчанию, функция wp_list_categories добавляет стиль "current-cat" только при просмотре архива рубрики, ручное же задание параметра current_category позволит "раскрасить" средствами css указанную рубрику при просмотре другого содержимого (например, при просмотре записи можно выделить рубрику, к которой эта запись принадлежит).

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

Примеры

1. Включение или исключение рубрик

Данный код выведет список рубрик только с указанными ID в алфавитном порядке.

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

Здесь будут выведены все рубрики в алфавитном порядке, за исключением рубрики с ID 10. У каждой рубрики будет выведено число записей в ней.

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

2. Вывод или скрытие заголовка списка рубрик

Этот пример выведет все рубрики за исключением рубрик с ID 4 и 7. Заголовок списка рубрик показан не будет.

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

В данном примере список рубрик будет состоять из рубрик с ID 5, 9 и 23. При этом заголовок списка будет выведен в тегах <h2> и </h2>.

<ul>
<?php
wp_list_categories('include=5,9,23&title_li=<h2>Все рубрики</h2>');
?> 
</ul>

3. Вывод только подрубрик

Данный код выведет только подрубрики родительской рубрики с ID 8. Будет показано число записей в этих подрубриках, а описание рубрик не будет использоваться при формировании title атрибута у ссылок.

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

4. Удаление скобок у числа записей в рубриках

По умолчанию WordPress выводит число записей в рубриках в круглых скобках. Данный код вырезает эти скобки. Параметр echo=0 позволяет получить результат работы функции в качестве переменной и соответственно эту переменную можно обработать.

<?php
$variable = wp_list_categories('echo=0&show_count=1&title_li=');
$variable = str_replace(array('(',')'), '', $variable);
echo $variable;
?>

5. Вывод списка рубрик вместе с ссылками на RSS ленту

Данный код выведет список рубрик по алфавиту, покажет число записей у рубрик и выведет ссылки на RSS ленты каждой рубрики.

<ul>
<?php wp_list_categories('orderby=name&show_count=1&feed=RSS лента'); ?>
</ul>

Для замены текста ссылки "RSS лента" на картинку используйте код:

<ul>
<?php 
wp_list_categories('show_count=1&feed_image=/images/rss.gif');
?>
</ul>
Оформление списка через CSS

По умолчанию функция wp_list_categories() оформляет список рубрик этими стилями (при значении list у параметра style):

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

Функция добавлена в версии 2.1.0
Параметр echo был добавлен в версии 2.3.0
Параметр depth был добавлен в версии 2.5.0
Параметр current_category был добавлен в версии 2.6.0
Параметр exclude_tree был добавлен в версии 2.7.1

Исходный файл

Функция wp_list_categories() находится в wp-includes/category-template.php

Связанные теги|функции
Рубрики: Теги шаблоновФункции WordPressУсловные теги

Понравился пост? Подпишись на обновления по Обновления блога по RSSRSS или Обновления блога на TwitterTwitter !

Комментарии (всего 50 комментариев)
Написать комментарий

(обязательно)

(обязательно, не публикуется)

Для вставки кода используйте кнопку "Код", по умолчанию используется синтаксис подсветки языка "php", вы можете поменять его на любой другой поддерживаемый GeSHi язык, например "javascript", "css", "html4strict", "sql" и тд. Используйте предпросмотр!
 


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