W3cubDocs

/WordPress

wp_page_menu( array|string $args = array() )

Displays or retrieves a list of pages with an optional home link.

Description

The arguments are listed below and part of the arguments are for wp_list_pages() function. Check that function for more info on those arguments.

Parameters

$args

(array|string) (Optional) Array or string of arguments to generate a page menu. See wp_list_pages() for additional arguments.

'sort_column'
(string) How to sort the list of pages. Accepts post column names. Default 'menu_order, post_title'.
'menu_id'
(string) ID for the div containing the page list. Default is empty string.
'menu_class'
(string) Class to use for the element containing the page list. Default 'menu'.
'container'
(string) Element to use for the element containing the page list. Default 'div'.
'echo'
(bool) Whether to echo the list or return it. Accepts true (echo) or false (return). Default true.
'show_home'
(int|bool|string) Whether to display the link to the home page. Can just enter the text you'd like shown for the home link. 1|true defaults to 'Home'.
'link_before'
(string) The HTML or text to prepend to $show_home text.
'link_after'
(string) The HTML or text to append to $show_home text.
'before'
(string) The HTML or text to prepend to the menu. Default is <ul>.
'after'
(string) The HTML or text to append to the menu. Default is </ul>.
'item_spacing'
(string) Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. Default 'discard'.
'walker'
(Walker) Walker instance to use for listing pages. Default empty (Walker_Page).

Default value: array()

Return

(void|string) Void if 'echo' argument is true, HTML menu if 'echo' is false.

Source

File: wp-includes/post-template.php

function wp_page_menu( $args = array() ) {
	$defaults = array(
		'sort_column'  => 'menu_order, post_title',
		'menu_id'      => '',
		'menu_class'   => 'menu',
		'container'    => 'div',
		'echo'         => true,
		'link_before'  => '',
		'link_after'   => '',
		'before'       => '<ul>',
		'after'        => '</ul>',
		'item_spacing' => 'discard',
		'walker'       => '',
	);
	$args     = wp_parse_args( $args, $defaults );

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

	if ( 'preserve' === $args['item_spacing'] ) {
		$t = "\t";
		$n = "\n";
	} else {
		$t = '';
		$n = '';
	}

	/**
	 * Filters the arguments used to generate a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param array $args An array of page menu arguments.
	 */
	$args = apply_filters( 'wp_page_menu_args', $args );

	$menu = '';

	$list_args = $args;

	// Show Home in the menu.
	if ( ! empty( $args['show_home'] ) ) {
		if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {
			$text = __( 'Home' );
		} else {
			$text = $args['show_home'];
		}
		$class = '';
		if ( is_front_page() && ! is_paged() ) {
			$class = 'class="current_page_item"';
		}
		$menu .= '<li ' . $class . '><a href="' . home_url( '/' ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';
		// If the front page is a page, add it to the exclude list.
		if ( 'page' === get_option( 'show_on_front' ) ) {
			if ( ! empty( $list_args['exclude'] ) ) {
				$list_args['exclude'] .= ',';
			} else {
				$list_args['exclude'] = '';
			}
			$list_args['exclude'] .= get_option( 'page_on_front' );
		}
	}

	$list_args['echo']     = false;
	$list_args['title_li'] = '';
	$menu                 .= wp_list_pages( $list_args );

	$container = sanitize_text_field( $args['container'] );

	// Fallback in case `wp_nav_menu()` was called without a container.
	if ( empty( $container ) ) {
		$container = 'div';
	}

	if ( $menu ) {

		// wp_nav_menu() doesn't set before and after.
		if ( isset( $args['fallback_cb'] ) &&
			'wp_page_menu' === $args['fallback_cb'] &&
			'ul' !== $container ) {
			$args['before'] = "<ul>{$n}";
			$args['after']  = '</ul>';
		}

		$menu = $args['before'] . $menu . $args['after'];
	}

	$attrs = '';
	if ( ! empty( $args['menu_id'] ) ) {
		$attrs .= ' id="' . esc_attr( $args['menu_id'] ) . '"';
	}

	if ( ! empty( $args['menu_class'] ) ) {
		$attrs .= ' class="' . esc_attr( $args['menu_class'] ) . '"';
	}

	$menu = "<{$container}{$attrs}>" . $menu . "</{$container}>{$n}";

	/**
	 * Filters the HTML output of a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param string $menu The HTML output.
	 * @param array  $args An array of arguments.
	 */
	$menu = apply_filters( 'wp_page_menu', $menu, $args );

	if ( $args['echo'] ) {
		echo $menu;
	} else {
		return $menu;
	}
}

Uses

Uses	Description
wp-includes/l10n.php: __()	Retrieve the translation of $text.
wp-includes/formatting.php: sanitize_text_field()	Sanitizes a string from user input or from the database.
wp-includes/formatting.php: esc_attr()	Escaping for HTML attributes.
wp-includes/query.php: is_front_page()	Determines whether the query is for the front page of the site.
wp-includes/query.php: is_paged()	Determines whether the query is for a paged result and not for the first page.
wp-includes/functions.php: wp_parse_args()	Merge user defined arguments into defaults array.
wp-includes/link-template.php: home_url()	Retrieves the URL for the current site where the front end is accessible.
wp-includes/plugin.php: apply_filters()	Calls the callback functions that have been added to a filter hook.
wp-includes/option.php: get_option()	Retrieves an option value based on an option name.
wp-includes/post-template.php: wp_list_pages()	Retrieve or display a list of pages (or hierarchical post type items) in list (li) format.
wp-includes/post-template.php: wp_page_menu_args	Filters the arguments used to generate a page-based menu.
wp-includes/post-template.php: wp_page_menu	Filters the HTML output of a page-based menu.

Changelog

Version	Description
4.7.0	Added the `item_spacing` argument.
4.4.0	Added `menu_id`, `container`, `before`, `after`, and `walker` arguments.
2.7.0	Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_page_menu