WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get pages

Description

This function is used to get a list of all the pages that are defined in the blog. Essentially get_pages gives you an array of the pages, and that array is not tree-like. See the wp_list_pages() Template Tag for the output of page titles in a tree-like fashion.

Note that, although similar to get_posts, several of the parameter names and values differ.

Usage

 <?php get_pages$args ); ?> 

Default Usage

<?php $args = array(
	'sort_order' => 'ASC',
	'sort_column' => 'post_title',
	'hierarchical' => 1,
	'exclude' => '',
	'include' => '',
	'meta_key' => '',
	'meta_value' => '',
	'authors' => '',
	'child_of' => 0,
	'parent' => -1,
	'exclude_tree' => '',
	'number' => '',
	'offset' => 0,
	'post_type' => 'page',
	'post_status' => 'publish'
); ?>

Parameters

sort_column 
(string) Sorts the list of Pages in a number of different ways. The default setting is sort alphabetically by Page title.
  • 'post_title' - Sort Pages alphabetically (by title) - default
  • 'menu_order' - Sort Pages by Page Order. N.B. Note the difference between Page Order and Page ID. The Page ID is a unique number assigned by WordPress to every post or page. The Page Order can be set by the user in the Write>Pages administrative panel.
  • 'post_date' - Sort by creation time.
  • 'post_modified' - Sort by time last modified.
  • 'ID' - Sort by numeric Page ID.
  • 'post_author' - Sort by the Page author's numeric ID.
  • 'post_name' - Sort alphabetically by Post slug. Not supported yet, as of WP 3.2.1 (See: http://core.trac.wordpress.org/ticket/14368 )
Note: The sort_column parameter can be used to sort the list of Pages by the descriptor of any field in the wp_post table of the WordPress database. Some useful examples are listed here.
Note: get_posts() uses the parameter 'orderby' instead of 'sort_column'. Also, get_posts() automatically prepends 'post_' to these values: 'author, date, modified, parent, title, excerpt, content'.
sort_order 
(string) Change the sort order of the list of Pages (either ascending or descending). The default is ascending. Valid values:
  • 'asc' - Sort from lowest to highest (Default).
  • 'desc' - Sort from highest to lowest.
Note: get_posts() uses the parameter 'order' instead of 'sort_order'.
exclude 
(string or array) Define a comma-separated list of Page IDs to be excluded from the list (example: 'exclude=3,7,31'). Beginning with Version 3.0, an array of Page ID also can be used. There is no default value.
include 
(string or array) Only include certain Pages in the list generated by get_pages. Like exclude, this parameter takes a comma-separated list of Page IDs. Beginning with Version 3.0, an array of Page ID also can be used. There is no default value.
Note: If this parameter is provided, child_of, parent, exclude, meta_key, and meta_value params are ignored, and hierarchical is set to false.
child_of 
(integer) Displays the sub-pages of a single Page only; uses the ID for a Page as the value. Defaults to 0 (displays all Pages). Note that the child_of parameter will also fetch "grandchildren" of the given ID, not just direct descendants.
  • 0 - default, no child_of restriction
parent 
(integer) Displays those pages that have this ID as a parent. Defaults to -1 (displays all Pages regardless of parent). Note that this can be used to limit the 'depth' of the child_of parameter, so only one generation of descendants might be retrieved. You must use this in conjuction with the child_of parameter. Feed it the same ID. Also note that the hierarchical parameter must be set to 0 (false) -- which is not default -- or else no results will be returned for any page other than the root (ID=0).
  • -1 - default, no parent restriction
  • 0 - returns all top level pages
exclude_tree 
(integer) The opposite of 'child_of', 'exclude_tree' will remove all children of a given ID from the results. Useful for hiding all children of a given page. Can also be used to hide grandchildren in conjunction with a 'child_of' value. This parameter was available at Version 2.7.
hierarchical 
(boolean) Display sub-Pages in an indented manner below their parent or list the Pages inline. The default is true (display sub-Pages indented below the parent list item). NOTE: This default value will prevent meta_key page searches finding sub-pages. You need to set 'hierarchical' => 0 for this to work properly. Valid values:
  • 1 (true) - default
  • 0 (false)
meta_key 
(string) Only include the Pages that have this Custom Field Key (use in conjunction with the meta_value field).
meta_value 
(string) Only include the Pages that have this Custom Field Value (use in conjunction with the meta_key field).
authors 
(string) Only include the Pages written by the given author(s)
Note: get_posts() uses the parameter 'author' instead of 'authors'.
number 
(integer) Sets the number of Pages to display. This causes the SQL LIMIT value to be defined. Default to no LIMIT. This parameter was added with Version 2.8.
Note: get_posts() uses the parameter 'numberposts' instead of 'number'.
offset 
(integer) Then number of Pages to pass over (or displace) before collecting the set of Pages. Default is no OFFSET. This parameter was added with Version 2.8.
post_status 
(string) A comma-separated list of post status types that should be included. For example, 'publish,private'.

Return

(Array) 
An array containing all the Pages matching the request

Example

Displaying pages in dropdown list

In this example a dropdown list with all the pages. Note how you can grab the link for the page with a simple call to the function get_page_link passing the ID of the page.


<select name="page-dropdown"
 onchange='document.location.href=this.options[this.selectedIndex].value;'> 
 <option value="">
<?php echo esc_attr( __( 'Select page' ) ); ?></option> 
 <?php 
  $pages = get_pages(); 
  foreach ( $pages as $page ) {
  	$option = '<option value="' . get_page_link( $page->ID ) . '">';
	$option .= $page->post_title;
	$option .= '</option>';
	echo $option;
  }
 ?>
</select>

Displaying Child pages of the current page in post format

<?php
	$mypages = get_pages( array( 'child_of' => $post->ID, 'sort_column' => 'post_date', 'sort_order' => 'desc' ) );

	foreach( $mypages as $page ) {		
		$content = $page->post_content;
		if ( ! $content ) // Check for empty page
			continue;

		$content = apply_filters( 'the_content', $content );
	?>
		<h2><a href="<?php echo get_page_link( $page->ID ); ?>"><?php echo $page->post_title; ?></a></h2>
		<div class="entry"><?php echo $content; ?></div>
	<?php
	}	
?>

Changelog

  • Since: 1.5.0

Source File

get_pages() is located in wp-includes/post.php.

Related

Page Tags: get_all_page_ids(), get_ancestors(), get_page(), get_page_link(), get_page_by_path(), get_page_by_title(), get_page_children(), get_page_hierarchy(), get_page_uri(), get_pages(), is_page(), page_uri_index(), wp_list_pages(), wp_page_menu()

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.