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

$argsarray|stringoptional

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.

More Arguments from wp_list_pages( … $args )

Array or string of arguments to retrieve pages.

• child_of int
  Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
• sort_order string
  How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'.
• sort_column string
  What columns to sort pages by, comma-separated. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'menu_order', 'post_modified_gmt', 'post_parent', 'ID', 'rand', 'comment*count'.
  'post*' can be omitted for any values that start with it.
  Default 'post_title'.
• hierarchical bool
  Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.
  Default true.
• exclude int[]
  Array of page IDs to exclude.
• include int[]
  Array of page IDs to include. Cannot be used with $child_of, $parent, $exclude, $meta_key, $meta_value, or $hierarchical.
  
• meta_key string
  Only include pages with this meta key.
• meta_value string
  Only include pages with this meta value. Requires $meta_key.
  
• authors string
  A comma-separated list of author IDs.
• parent int
  Page ID to return direct children of. Default -1, or no restriction.
• exclude_tree string|int[]
  Comma-separated string or array of page IDs to exclude.
  
• number int
  The number of pages to return. Default 0, or all pages.
• offset int
  The number of pages to skip before returning. Requires $number.
  Default 0.
• post_type string
  The post type to query. Default 'page'.
• post_status string|array
  A comma-separated list or array of post statuses to include.
  Default 'publish'.

Default:array()

Return

Source

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="' . esc_url( 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;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_page_menu’, string $menu, array $args )

Filters the HTML output of a page-based menu.

apply_filters( ‘wp_page_menu_args’, array $args )

Filters the arguments used to generate a page-based menu.

Changelog