wp_page_menu() WordPress Function
The wp_page_menu() function is used to display a list of pages as a menu. The list of pages is generated by the Wordpress core function get_pages(). The wp_page_menu() function can be used in a template file by adding the following code: The wp_page_menu() function accepts two arguments. The first argument is an array of options that can be used to customize the menu. The second argument is the name of a custom menu to be used if one has been created. The wp_page_menu() function can be used to create a simple menu of pages or a more complex hierarchical menu. By default, the menu will be displayed as a list of pages with the top-level pages being the first items in the list. Sub-pages will be indented under their parent pages.
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 which results in a Walker_Page instance being used.
Default value: array()
- 'sort_column'
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. See wp_page_menu() * for information on accepted 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. See wp_page_menu() * for information on accepted arguments. */ $menu = apply_filters( 'wp_page_menu', $menu, $args ); if ( $args['echo'] ) { echo $menu; } else { return $menu; } }
Expand full source codeCollapse full source codeView on TracView on GitHub
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. |