wp_list_pages( array|string $args = ” )
Retrieve or display a list of pages (or hierarchical post type items) in list (li) format.
Description Description
See also See also
- get_pages()
Parameters Parameters
- $args
-
(array|string) (Optional) Array or string of arguments to generate a list of pages. See
get_pages()for additional arguments.- ‘child_of’
(int) Display only the sub-pages of a single page by ID. Default 0 (all pages). - ‘authors’
(string) Comma-separated list of author IDs. Default empty (all authors). - ‘date_format’
(string) PHP date format to use for the listed pages. Relies on the ‘show_date’ parameter. Default is the value of ‘date_format’ option. - ‘depth’
(int) Number of levels in the hierarchy of pages to include in the generated list. Accepts -1 (any depth), 0 (all pages), 1 (top-level pages only), and n (pages to the given n depth). Default 0. - ‘echo’
(bool) Whether or not to echo the list of pages. Default true. - ‘exclude’
(string) Comma-separated list of page IDs to exclude. - ‘include’
(array) Comma-separated list of page IDs to include. - ‘link_after’
(string) Text or HTML to follow the page link label. Default null. - ‘link_before’
(string) Text or HTML to precede the page link label. Default null. - ‘post_type’
(string) Post type to query for. Default ‘page’. - ‘post_status’
(string|array) Comma-separated list or array of post statuses to include. Default ‘publish’. - ‘show_date’
(string) Whether to display the page publish or modified date for each page. Accepts ‘modified’ or any other value. An empty value hides the date. - ‘sort_column’
(string) Comma-separated list of column names to sort the pages by. Accepts ‘post_author’, ‘post_date’, ‘post_title’, ‘post_name’, ‘post_modified’, ‘post_modified_gmt’, ‘menu_order’, ‘post_parent’, ‘ID’, ‘rand’, or ‘comment_count’. Default ‘post_title’. - ‘title_li’
(string) List heading. Passing a null or empty value will result in no heading, and the list will not be wrapped with unordered list<ul>tags. Default ‘Pages’. - ‘item_spacing’
(string) Whether to preserve whitespace within the menu’s HTML. Accepts ‘preserve’ or ‘discard’. Default ‘preserve’. - ‘walker’
(Walker) Walker instance to use for listing pages. Default empty (Walker_Page).
Default value: ”
- ‘child_of’
Return Return
(void|string) Void if ‘echo’ argument is true, HTML list of pages if ‘echo’ is false.
More Information More Information
Menu Item CSS Classes Menu Item CSS Classes
The following classes are applied to menu items, i.e. to the HTML <li> tags, generated by wp_list_pages(). Note: The wp_list_pages() and wp_page_menu() functions output the same CSS classes.
All Menu Items All Menu Items
- .page_item
This class is added to menu items that correspond to a static page. - .page-item-$ID
This class is added to menu items that correspond to a static page, where $ID is the static page ID.
Current-Page Menu Items Current-Page Menu Items
- .current_page_item
This class is added to menu items that correspond to the currently rendered static page.
Current-Page Parent Menu Items Current-Page Parent Menu Items
- .current_page_parent
This class is added to menu items that correspond to the hierarchical parent of the currently rendered static page.
Current-Page Ancestor Menu Items Current-Page Ancestor Menu Items
- .current_page_ancestor
This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered static page.
Source Source
File: wp-includes/post-template.php
|
1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 |
function wp_list_pages( $args = '' ) { $defaults = array( 'depth' => 0, 'show_date' => '', 'date_format' => get_option( 'date_format' ), 'child_of' => 0, 'exclude' => '', 'title_li' => __( 'Pages' ), 'echo' => 1, 'authors' => '', 'sort_column' => 'menu_order, post_title', 'link_before' => '', 'link_after' => '', 'item_spacing' => 'preserve', 'walker' => '', ); $parsed_args = wp_parse_args( $args, $defaults ); if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) { // Invalid value, fall back to default. $parsed_args['item_spacing'] = $defaults['item_spacing']; } $output = ''; $current_page = 0; // Sanitize, mostly to keep spaces out. $parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] ); // Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array). $exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array(); /** * Filters the array of pages to exclude from the pages list. * * @since 2.1.0 * * @param string[] $exclude_array An array of page IDs to exclude. */ $parsed_args['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) ); $parsed_args['hierarchical'] = 0; // Query pages. $pages = get_pages( $parsed_args ); if ( ! empty( $pages ) ) { if ( $parsed_args['title_li'] ) { $output .= '<li class="pagenav">' . $parsed_args['title_li'] . '<ul>'; } global $wp_query; if ( is_page() || is_attachment() || $wp_query->is_posts_page ) { $current_page = get_queried_object_id(); } elseif ( is_singular() ) { $queried_object = get_queried_object(); if ( is_post_type_hierarchical( $queried_object->post_type ) ) { $current_page = $queried_object->ID; } } $output .= walk_page_tree( $pages, $parsed_args['depth'], $current_page, $parsed_args ); if ( $parsed_args['title_li'] ) { $output .= '</ul></li>'; } } /** * Filters the HTML output of the pages to list. * * @since 1.5.1 * @since 4.4.0 `$pages` added as arguments. * * @see wp_list_pages() * * @param string $output HTML output of the pages list. * @param array $parsed_args An array of page-listing arguments. * @param WP_Post[] $pages Array of the page objects. */ $html = apply_filters( 'wp_list_pages', $output, $parsed_args, $pages ); if ( $parsed_args['echo'] ) { echo $html; } else { return $html; }} |
Expand full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 4.7.0 | Added the item_spacing argument. |
| 1.5.0 | Introduced. |