wp_page_menu

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

Description

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

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.

Returns (string|void)

HTML menu

Parameters (1)

0. $args — Optional. (array) => array()
Arguments to generate a page menu. See wp_list_pages() for additional arguments.

Options

  • sort_column (string) => 'menu_order, post_title'

    How to short the list of pages. Accepts post column names.

  • menu_id (string) => is string

    ID for the div containing the page list.

  • menu_class (string) => 'menu'

    Class to use for the element containing the page list.

  • container (string) => 'div'

    Element to use for the element containing the page list.

  • echo (bool) => true

    Whether to echo the list or return it. Accepts true (echo) or false (return).

  • 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.

    • after (string) => '
    '

    The HTML or text to append to the menu.

  • item_spacing (string) => 'discard'

    Whether to preserve whitespace within the menu's HTML. Accepts preserve or discard..

array(

    /**
     * How to short the list of pages. Accepts post column names.
     *
     * @type string
     * @default 'menu_order, post_title'
     */
    'sort_column' => 'menu_order, post_title',

    /**
     * ID for the div containing the page list.
     *
     * @type string
     * @default is  string
     */
    'menu_id' => is  string,

    /**
     * Class to use for the element containing the page list.
     *
     * @type string
     * @default 'menu'
     */
    'menu_class' => 'menu',

    /**
     * Element to use for the element containing the page list.
     *
     * @type string
     * @default 'div'
     */
    'container' => 'div',

    /**
     * Whether to echo the list or return it. Accepts true (echo) or false (return).
     *
     * @type bool
     * @default true
     */
    'echo' => true,

    /**
     * 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'.
     *
     * @type int|bool|string
     * @default ''
     */
    'show_home' => '',

    /**
     * The HTML or text to prepend to $show_home text.
     *
     * @type string
     * @default ''
     */
    'link_before' => '',

    /**
     * The HTML or text to append to $show_home text.
     *
     * @type string
     * @default ''
     */
    'link_after' => '',

    /**
     * The HTML or text to prepend to the menu.
     *
     * @type string
     * @default '
    ' */ 'before' => '
      ', /** * The HTML or text to append to the menu. * * @type string * @default '
    ' */
    'after' => '
'
, /** * Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. * * @type string * @default 'discard' */ 'item_spacing' => 'discard' );


Usage

  1. if ( !function_exists( 'wp_page_menu' ) ) { 
  2. require_once ABSPATH . WPINC . '/post-template.php'; 
  3.  
  4. // Optional. Arguments to generate a page menu. See wp_list_pages() for additional arguments. 
  5. $args = array( 
  6. 'sort_column' => 'menu_order, post_title', 
  7. 'menu_id' => is string, 
  8. 'menu_class' => 'menu', 
  9. 'container' => 'div', 
  10. 'echo' => true, 
  11. 'show_home' => '', 
  12. 'link_before' => '', 
  13. 'link_after' => '', 
  14. 'before' => '', 
  15. 'after' => '', 
  16. 'item_spacing' => 'discard' 
  17. ); 
  18.  
  19. // NOTICE! Understand what this does before running. 
  20. $result = wp_page_menu($args); 
  21.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/post-template.php  
  1. function wp_page_menu( $args = array() ) { 
  2. $defaults = array( 
  3. 'sort_column' => 'menu_order, post_title',  
  4. 'menu_id' => '',  
  5. 'menu_class' => 'menu',  
  6. 'container' => 'div',  
  7. 'echo' => true,  
  8. 'link_before' => '',  
  9. 'link_after' => '',  
  10. 'before' => '<ul>',  
  11. 'after' => '</ul>',  
  12. 'item_spacing' => 'discard',  
  13. walker => '',  
  14. ); 
  15. $args = wp_parse_args( $args, $defaults ); 
  16.  
  17. if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ) ) ) { 
  18. // invalid value, fall back to default. 
  19. $args['item_spacing'] = $defaults['item_spacing']; 
  20.  
  21. if ( 'preserve' === $args['item_spacing'] ) { 
  22. $t = "\t"; 
  23. $n = "\n"; 
  24. } else { 
  25. $t = ''; 
  26. $n = ''; 
  27.  
  28. /** 
  29. * Filters the arguments used to generate a page-based menu. 
  30. * @since 2.7.0 
  31. * @see wp_page_menu() 
  32. * @param array $args An array of page menu arguments. 
  33. */ 
  34. $args = apply_filters( 'wp_page_menu_args', $args ); 
  35.  
  36. $menu = ''; 
  37.  
  38. $list_args = $args; 
  39.  
  40. // Show Home in the menu 
  41. if ( ! empty($args['show_home']) ) { 
  42. if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) 
  43. $text = __('Home'); 
  44. else 
  45. $text = $args['show_home']; 
  46. $class = ''; 
  47. if ( is_front_page() && !is_paged() ) 
  48. $class = 'class="current_page_item"'; 
  49. $menu .= '<li ' . $class . '><a href="' . home_url( '/' ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>'; 
  50. // If the front page is a page, add it to the exclude list 
  51. if (get_option('show_on_front') == 'page') { 
  52. if ( !empty( $list_args['exclude'] ) ) { 
  53. $list_args['exclude'] .= ', '; 
  54. } else { 
  55. $list_args['exclude'] = ''; 
  56. $list_args['exclude'] .= get_option('page_on_front'); 
  57.  
  58. $list_args['echo'] = false; 
  59. $list_args['title_li'] = ''; 
  60. $menu .= wp_list_pages( $list_args ); 
  61.  
  62. $container = sanitize_text_field( $args['container'] ); 
  63.  
  64. // Fallback in case `wp_nav_menu()` was called without a container. 
  65. if ( empty( $container ) ) { 
  66. $container = 'div'; 
  67.  
  68. if ( $menu ) { 
  69.  
  70. // wp_nav_menu doesn't set before and after 
  71. if ( isset( $args['fallback_cb'] ) && 
  72. 'wp_page_menu' === $args['fallback_cb'] && 
  73. 'ul' !== $container ) { 
  74. $args['before'] = "<ul>{$n}"; 
  75. $args['after'] = '</ul>'; 
  76.  
  77. $menu = $args['before'] . $menu . $args['after']; 
  78.  
  79. $attrs = ''; 
  80. if ( ! empty( $args['menu_id'] ) ) { 
  81. $attrs .= ' id="' . esc_attr( $args['menu_id'] ) . '"'; 
  82.  
  83. if ( ! empty( $args['menu_class'] ) ) { 
  84. $attrs .= ' class="' . esc_attr( $args['menu_class'] ) . '"'; 
  85.  
  86. $menu = "<{$container}{$attrs}>" . $menu . "</{$container}>{$n}"; 
  87.  
  88. /** 
  89. * Filters the HTML output of a page-based menu. 
  90. * @since 2.7.0 
  91. * @see wp_page_menu() 
  92. * @param string $menu The HTML output. 
  93. * @param array $args An array of arguments. 
  94. */ 
  95. $menu = apply_filters( 'wp_page_menu', $menu, $args ); 
  96. if ( $args['echo'] ) 
  97. echo $menu; 
  98. else 
  99. return $menu;