WordPress как на ладони
rgbcode is looking for WordPress developers.

wp_list_pages()WP 1.5.0

Выводит список постоянных страниц в виде ссылок.

Обычно используется в файлах header.php (шапка сайта) или sidebar.php (боковая панель) для создания меню.

Смотрите также очень похожую функцию wp_page_menu().

Альтернативой для создания меню является функция wp_nav_menu(), добавлена с версии 3.0. Мануал читайте здесь.

Работает на основе: get_pages()
Основа для: wp_page_menu()
1 раз — 0.014449 сек (тормоз) | 50000 раз — 213.16 сек (тормоз) | PHP 7.1.2, WP 4.7.3
Хуки из функции

Возвращает

null|Строку.

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

wp_list_pages( [
	'authors'      => '',
	'child_of'     => 0,
	'date_format'  => get_option('date_format'),
	'depth'        => 0,
	'echo'         => 1,
	'exclude'      => '',
	'exclude_tree' => '',
	'include'      => '',
	'link_after'   => '',
	'link_before'  => '',
	'meta_key'     => '',
	'meta_value'   => '',
	'number'       => '',
	'offset'       => '',
	'post_type'    => 'page', // см. get_pages()
	'show_date'    => '',
	'sort_column'  => 'menu_order, post_title',
	'sort_order'   => 'ASC',
	'title_li'     => __('Pages'),
	'walker'       => '',
] );

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

<?php wp_list_pages( $args ); ?>
$args
Параметры по которым нужно получить список страниц.

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

Кроме параметров ниже, функция может принимать все те же параметры что и get_pages(), потому что она работает на её основе.

depth(число)

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

  • 0 (по умолчанию) Включать в список все уровни вложенных страницы и показывать их в древовидном виде.
  • -1 Включить в список все уровни вложенных страниц, но не показывать вложенность (древовидное отображение списка отключается, список будет показан как общий).
  • 1 Показать только первые вложенные страницы, т.е. дочерние страницы первого уровня.
  • 2, 3 и т.д. Включить в список дочерние страницы 2, 3 и т.д. уровня…

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

show_date(строка)

Показывает дату создания или изменения страницы, рядом со ссылкой. По умолчанию показ дат отключен.

  • '' - не показывать даты (по умолчанию).
  • modified - показывать дату изменения.
  • created - показывать дату создания страницы.

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

date_format(строка)
Контролирует в каком виде будет показана дата, если включен параметр show_date, например, d/m/Y выведет: 10/11/2011
По умолчанию: настройки даты в WordPress
child_of(число)
Показывать только дочерние страницы отдельной страницы, указанной в этом параметре. Указывать нужно ID страницы, подстраницы которой мы хотим вывести. По умолчанию 0 - показывать все страницы.
По умолчанию: 0
exclude(строка)
В этом параметре указываем через запятую ID тех страниц, которые мы не хотим, чтобы попали в список, например: exclude=3,7,31.
По умолчанию: ''
exclude_tree(строка)
Укажите через запятую ID родительский страниц, которые вы хотите исключить из списка. Так же будут исключены все вложенные (дочерние страницы) указанных ID. Т.е. этот параметр исключает из списка все дерево страниц.
Добавлен в версии 2.7.
По умолчанию: ''
include(строка/массив)

Показать в списке только указанные страницы. ID можно указать через запятую или пробел в виде строки: include=45 63 78 94 128 140.

Этот параметр отменяет параметры относящиеся к формированию списка, так как он создает список только из тех страниц которые указаны. Отменяются параметры: exclude, child_of, depth, meta_key, meta_value, authors.
По умолчанию: ''

title_li(строка)
Заголовок списка. По умолчанию: __('Pages') __('') нужно для локализации. Если обнулить этот параметр (''), то заголовок списка не будет показываться, так же будут удалены HTML теги обрамляющие список (<ul>, </ul>).
По умолчанию: __('Pages')
echo(логический)
Выводить результат на экран (true) или возвращать для обработки (false).
По умолчанию: true
authors(строка)
Показать страницы принадлежащие только указанным в этом параметре авторам. Указывать нужно ID авторов, через запятую.
По умолчанию: ''
sort_column(строка)

Сортировать список по указанным полям. По умолчанию список сортируется по заголовкам (post_title), в алфавитном порядке. Можно указывать несколько параметров через запятую, в соответствии с которыми потом будет отсортирован список.

  • post_title - сортировать по заголовку (в алфавитном порядке);
  • menu_order - сортировать по порядку, который указывается на админ-панели на странице редактирования "постоянной страницы";
  • post_date - сортировать по дате создания "постоянной страницы";
  • post_modified - сортировать по дате изменения страницы;
  • ID - сортировать по идентификатору записи в Базе Данных (по ID);
  • post_author - сортировать по ID авторов;
  • post_name - сортировать в алфавитом порядке по альтернативному имени поста (обычно транслитерация заголовка).

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

sort_order(строка)
Направление сортировки: 'ASC' - по порядку, 'DESC' - в обратном порядке.
По умолчанию: 'ASC'
link_before(строка)
Укажите здесь текст или HTML код, который будет вставлен перед текстом ссылки (внутри тега <a>). Добавлен в версии 2.7.
По умолчанию: ""
link_after(строка)
Укажите здесь текст или HTML код, который будет вставлен после текста ссылки (внутри тега <a>). Добавлен в версии 2.7.
По умолчанию: ""
meta_key(строка)
Выведет страницы, имеющие только указанные произвольные поля (работает только вместе с параметром meta_value).
По умолчанию: ''
meta_value(строка)
Выведет страницы, имеющие только указанные значения произвольных полей (ключ произвольного поля указывать обязательно в параметре meta_key).
По умолчанию: ''
number(число)
Ограничение количества ссылок в списке (SQL LIMIT). В некоторых случаях может не работать.
По умолчанию: 0
offset(число)
Верхний отступ списка. Например, если указать 5, то первые 5 ссылок, которые должны были бы быть показаны не будет показаны в списке.
Добавлен в версии 2.8.
По умолчанию: 0
item_spacing(строка)
Оставлять или нет переносы строк в HTML коде меню. Может быть: preserve или discard. C WP 4.7.
По умолчанию: 'preserve'
walker(строка)
php Класс, который обрабатывает построение списка.
По умолчанию: ''

Примеры

0

#1 Удалим заголовок списка, отменив параметр title_li.

Имейте ввиду, что теги ul так же будет удалены и их нужно указывать отдельно:

<ul>
	<?php wp_list_pages('title_li='); ?>
</ul>
0

#2 Изменим заголовок

Изменим заголовок на "Поэты", обвернем его в HTML тег <h2> и выведем в списке только постоянные страницы с ID 9, 5 и 23:

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

#3 Сортировка по порядковому номеру

Отсортируем список в соответствии с порядковыми номерами, указанными на странице редактирования "постоянных страниц":

<ul>
	<?php wp_list_pages('sort_column=menu_order'); ?>
</ul>
0

#4 Сортировка по дате создания

Выведем список отсортированный по дате создания "постоянной страницы" и покажем дату рядом с каждой ссылкой:

<ul>
	<?php wp_list_pages('sort_column=post_date&show_date=created'); ?>
</ul>
0

#5 Исключение страниц

Используя параметр exclude исключим страницы с ID 17,38:

<ul>
	<?php wp_list_pages('exclude=17,38' ); ?>
</ul>
0

#6 Список только из страниц с указанными ID

Используя параметр include, создадим список только из страниц с ID 35, 7, 26 и 13:

<ul>
	<?php wp_list_pages('include=7,13,26,35&title_li=<h2>' . __('Pages') . '</h2>' ); ?>
</ul>
0

#7 Выведем список дочерних страниц

Используя следующий пример, можно вывести в сайдбаре (или где-нибудь еще) список дочерних страниц (подстраниц), постоянной страницы на который вы сейчас находитесь. Для этого воспользуемся параметром child_of и проверкой существуют ли вообще дочерние страницы для текущей (попробуем получить дочерние страницы в переменную $children, если получится, выведем список):

<?php
$children = wp_list_pages( 'title_li=&child_of=' . $post->ID . '&echo=0' );

if( $children ){
	?>
	<ul>
		<?php echo $children; ?>
	</ul>
	<?php
}
?>
0

#8 Статичный список дочерних страниц

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

<?php
if( $post->post_parent ){
	$children = wp_list_pages( "title_li=&child_of=" . $post->post_parent . "&echo=0" );
}
else {
	$children = wp_list_pages( "title_li=&child_of=" . $post->ID . "&echo=0" );
}

if( $children ){
	?>
	<ul>
		<?php echo $children; ?>
	</ul>
	<?php
}
?>

Этот пример можно использовать в боковой панели (сайдбаре), однако нужно понимать, что он проверяет сначала наличие родительской страницы у текущей, если она существует, то выводится список одноуровневых страниц, если родительской страницы нет, то выводится список дочерних страниц. Таким образом, мы будет иметь на всех страницах замкнутый список для страниц верхнего уровня.

0

#9 Статичный список дочерних страниц (альтернативный вариант)

Альтернативный вариант предыдущего примера.

Этот пример также можно использовать в сайдбаре, он будет выводить:

  • когда вы находитесь на главной странице, будут показаны все "постоянные страницы" верхнего уровня;

  • когда вы находитесь на "постоянной странице" верхнего уровня, у которой нет дочерних страниц, будут показаны все те же "постоянные страницы" верхнего уровня;

  • когда вы находитесь на "постоянной странице" верхнего уровня, у которой есть дочерние страницы, будут показаны эти дочерние страницы и их дочерние страницы;

  • когда вы находитесь на дочерней странице "постоянной страницы" верхнего уровня (на странице второго уровня), будут показаны дочерние страницы "постоянной страницы" верхнего уровня (т.е. дочерние страницы родительской).
$output = wp_list_pages( 'echo=0&depth=1&title_li=<h2>Top level pages</h2>' );

if( is_page() ){
	$page = $post->ID;

	if( $post->post_parent ){
		$page = $post->post_parent;
	}

	$children = wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );

	if( $children ){
		$output = wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>' );
	}
}

echo $output;
0

#10 Список страниц, только если он есть

Список дочерних страниц, который будет показан, только если у "постоянной страницы" есть дочерние страницы. Дочерние страницы будут показаны как на родительской "постоянной странице" так и на самих дочерних страницах. Отличием от предыдущего примера, является наличие названия родительской "постоянной страницы" в заголовке списка:

<?php
if( $post->post_parent ){
	$children = wp_list_pages( "title_li=&child_of=" . $post->post_parent . "&echo=0" );
	$titlenamer = get_the_title( $post->post_parent );
}

else{
	$children = wp_list_pages( "title_li=&child_of=" . $post->ID . "&echo=0" );
	$titlenamer = get_the_title( $post->ID );
}

if( $children ){
	?>

	<h2> <?php echo $titlenamer; ?> </h2>
	<ul>
		<?php echo $children; ?>
	</ul>

	<?php
}
?>
0

#11 Дерево дочерних страниц указанной страницы

Так как нет возможности указать wp_list_pages выводить дерево (все уровни вложенности) страниц определенной страницы (например, страницы с ID 93), то для такого трюка мы можем воспользоваться функцией get_pages():

<?php
// Используем wp_list_pages, чтобы показать родительскую и все дочерние страницы
// (включая все вложенные в них)
$pages = get_pages( 'child_of=93' );
$parent = 25;
if( $pages ){
	$pageids = [];

	foreach( $pages as $page ){
		$pageids[] = $page->ID;
	}

	wp_list_pages( [
		'title_li' => 'Дерево родительской страницы: ' . $parent,
		'include'  => $parent . ',' . implode( ',', $pageids ),
	] );
}
?>
0

#12 Маркировка и Стилизация списков страниц

По умолчанию, wp_list_pages() создает список такой конструкции:

<li class="pagenav">Страницы
	<ul>
		<li class="page_item page-item-4"></li>
		<li class="page_item page-item-5"></li>
		...
	</ul>
</li>

Если мы уберем заголовок, поставив пустой параметр title_li=, то вид станет таким:

<li class="page_item page-item-4"></li>
<li class="page_item page-item-5"></li>
...

По-другому можно написать так:

<li class="pagenav">
Страницы [title_li]
  <ul>
	<!-- Список начинается от сюда, если параметр 'title_li' пустой -->
	<li class="page-item-2 page_item current_page_ancestor current_page_parent">
	  [родитель текущей страницы]
		  <ul>
			<li class="page-item-21 page_item current_page_item">[текущая страница]</li>
		  </ul>
	</li>
	<li class="page-item-3 page_item">[другие страницы]</li>
  </ul>
</li>

Все теги li создаваемые функцией wp_list_pages() помечены CSS классом page_item. Когда в списке появляется страница на который вы находитесь, к li элементу списка добавляется еще класс current_page_parent.

Таким образом, список можно "раскрашивать" следующими CSS селекторами:

.pagenav { … } /* главный класс ul тега, который оборачивает весь список */
.page-item-2 { … } /* элемент относящийся к странице с ID 2 */
.page_item { … } /* любой элемент списка */
.current_page_item { … } /* текущая страница */
.current_page_parent { … } /* родительская страница текущей */
.current_page_ancestor { … } /* любая страница как либо связанная с текущей (родитель или дочь.) */

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

.pagenav  ul ul,
.pagenav .current_page_item ul ul,
.pagenav .current_page_ancestor ul ul,
.pagenav .current_page_ancestor .current_page_item ul ul,
.pagenav .current_page_ancestor .current_page_ancestor ul ul {
	display: none;
}

.pagenav .current_page_item ul,
.pagenav .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_ancestor ul {
	display: block;
}
0

#13 Список родственных или дочерних страниц к текущей

<?php
// если это дочерняя страница
if( $post->post_parent ){

	// собираем родственные страницы
	$relations = get_post_ancestors( $post->ID );

	// получаем дочерние страницы (если есть)
	$result = $wpdb->get_results( "SELECT ID FROM wp_posts WHERE post_parent = $post->ID AND post_type='page'" );

	// если дочерние страницы этой страницы получилось
	// получить объединяем их с родственными
	foreach( $result as $page_id ){
		$relations[] = $page_id->ID;
	}

	// добавляем текущую страницу к родственным
	$relations[] = $post->ID;

	// делаем список ID разделенный запятыми из родственных, дочерних и текущей
	$relations_string = implode( ",", $relations );

	// получаем список с помощью параметра include
	$sidelinks = wp_list_pages( "title_li=&echo=0&include=" . $relations_string );
}
// если это не дочерняя страница
else {
	// показываем только дочерние страницы один уровень
	$sidelinks = wp_list_pages( "title_li=&echo=0&depth=1&child_of=" . $post->ID );
}

if( $sidelinks ){
	?>
	<h2><?php the_title(); ?></h2>
	<ul>
		<?php // выводим на экран ссылки в <li> тегах
		echo $sidelinks; ?>
	</ul>
	<?php
}
?>
0

#14 Использование произвольного типа записей (отличного от page)

Если на сайте создан произвольный тип записей с древовидной структурой, то wp_list_pages() можно использовать для вывода и таких записей.

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

Тип записи указывается в параметре post_type:

wp_list_pages( [
  'post_type'=>'portfolio',
  'title_li'=> __('Portfolio')
] );
-1

#15 Уберем у списка заголовок "Страницы":

<ul>
  <?php wp_list_pages('sort_column=menu_order&title_li='); ?>
</ul>
-1

#16 Все дочерние страницы на страницах любого уровня вложенности

Этот пример показывает как получить все дочерние страницы, на страницах любого уровня вложенности:

<?php
if( ! $post->post_parent ){
	// получим дочерние страницы, для "постоянной страницы" верхнего уровня
	$children = wp_list_pages( "title_li=&child_of=" . $post->ID . "&echo=0" );
}
else{
	// получим дочерние страницы, если мы находимся на дочерней странице первого уровня.
	//$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");

	if( $post->ancestors ){
		// теперь получим ID самой первой страницы (старшой)
		// wp собирает ID в обратном порядке, поэтому "первая" страницы будет последней
		$ancestors = end( $post->ancestors );
		$children = wp_list_pages( "title_li=&child_of=" . $ancestors . "&echo=0" );
		// все, теперь у нас всегда будет список из всех дочерних страниц,
		// на каком уровне вложенности мы бы не находились.
	}
}

if( $children ){
	?>
	<ul>
		<?php echo $children; ?>
	</ul>
	<?php
}
?>

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

Заметки

  • Смотрите: get_pages()
  • Global. WP_Query. $wp_query WordPress Query object.

Список изменений

С версии 1.5.0 Введена.
С версии 4.7.0 Added the item_spacing argument.

Код wp_list_pages() WP 6.4.3

function wp_list_pages( $args = '' ) {
	$defaults = array(
		'depth'        => 0,
		'show_date'    => '',
		'date_format'  => get_option( 'date_format' ),
		'child_of'     => 0,
		'exclude'      => '',
		'title_li'     => __( 'Pages' ),
		'echo'         => 1,
		'authors'      => '',
		'sort_column'  => 'menu_order, post_title',
		'link_before'  => '',
		'link_after'   => '',
		'item_spacing' => 'preserve',
		'walker'       => '',
	);

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

	if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// Invalid value, fall back to default.
		$parsed_args['item_spacing'] = $defaults['item_spacing'];
	}

	$output       = '';
	$current_page = 0;

	// Sanitize, mostly to keep spaces out.
	$parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] );

	// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array).
	$exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array();

	/**
	 * Filters the array of pages to exclude from the pages list.
	 *
	 * @since 2.1.0
	 *
	 * @param string[] $exclude_array An array of page IDs to exclude.
	 */
	$parsed_args['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );

	$parsed_args['hierarchical'] = 0;

	// Query pages.
	$pages = get_pages( $parsed_args );

	if ( ! empty( $pages ) ) {
		if ( $parsed_args['title_li'] ) {
			$output .= '<li class="pagenav">' . $parsed_args['title_li'] . '<ul>';
		}
		global $wp_query;
		if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {
			$current_page = get_queried_object_id();
		} elseif ( is_singular() ) {
			$queried_object = get_queried_object();
			if ( is_post_type_hierarchical( $queried_object->post_type ) ) {
				$current_page = $queried_object->ID;
			}
		}

		$output .= walk_page_tree( $pages, $parsed_args['depth'], $current_page, $parsed_args );

		if ( $parsed_args['title_li'] ) {
			$output .= '</ul></li>';
		}
	}

	/**
	 * Filters the HTML output of the pages to list.
	 *
	 * @since 1.5.1
	 * @since 4.4.0 `$pages` added as arguments.
	 *
	 * @see wp_list_pages()
	 *
	 * @param string    $output      HTML output of the pages list.
	 * @param array     $parsed_args An array of page-listing arguments. See wp_list_pages()
	 *                               for information on accepted arguments.
	 * @param WP_Post[] $pages       Array of the page objects.
	 */
	$html = apply_filters( 'wp_list_pages', $output, $parsed_args, $pages );

	if ( $parsed_args['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}
26 комментариев
    Войти