wp_page_menu( array|string $args = array() )
Displays or retrieves a list of pages with an optional home link.
Description 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 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()
- 'sort_column'
Return Return
(string|void) HTML menu
Source 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 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 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; } }
Expand full source code Collapse full source code View on Trac
Changelog 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. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Display Home as a Page
The following example causes “Home” to be added to the beginning of the list of pages displayed. In addition, the Pages wrapped in a
div
element, page IDs 5, 9, and 23, are excluded from the list of pages displayed, and the pages are listed in Page Order. The list is prefaced with the title “Page Menu”.Display Home as a Page called Blog
The following example causes “Blog” (instead of “Home”) to be added to the beginning of the list of pages displayed:
Display only Home
The following example displays just a link to “Home”. Note that the include=9999′ references a page ID that does not exist so only a link for Home is displayed.