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
-
(Optional) 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()
- 'sort_column'
Return
(string|void) HTML menu
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' ) ) ) {
// 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 WP-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 (get_option('show_on_front') == 'page') {
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 WP-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;
}
Changelog
Version | Description |
---|---|
WP-4.7.0 | Added the item_spacing argument. |
WP-4.4.0 | Added menu_id , container , before , after , and walker arguments. |
WP-2.7.0 | Introduced. |