In this part of this series on WP_Query, you'll learn how to use WP_Query to query for posts, pages and custom post types. You can query for specific posts and pages or you can run a query to return posts of one or more post types.
A Recap on How Arguments Work in WP_Query
Before we start, let's have a quick recap on how arguments work in WP_Query. When you code WP_Query in your themes or plugins, you need to include four main elements:
- the arguments for the query, using parameters which will be covered in this tutorial
- the query itself
- the loop
- finishing off: closing if and while tags and resetting post data
In practice this will look something like the following:
<?php
$args = array(
// Arguments for your query.
);
// Custom query.
$query = new WP_Query( $args );
// Check that we have query results.
if ( $query->have_posts() ) {
// Start looping over the query results.
while ( $query->have_posts() ) {
$query->the_post();
// Contents of the queried post results go here.
}
}
// Restore original post data.
wp_reset_postdata();
?>
The arguments are what tells WordPress what data to fetch from the database and it's those that I'll cover here. So all we're focusing on here is the first part of the code:
$args = array(
// Arguments for your query.
);
As you can see, the arguments are contained in an array. You'll learn how to code them as you work through this tutorial.
Coding Your Arguments
There is a specific way to code the arguments in the array, which is as follows:
$args = array(
'parameter1' => 'value',
'parameter2' => 'value',
'parameter3' => 'value'
);
You must enclose the parameters and their values in single quotation marks, use => between them, and separate them with a comma. If you get this wrong, WordPress may not add all of your arguments to the query or you may get a white screen.
Querying for Single Posts or Pages
Let's start with the simplest scenario: running a query to find one specific post or page.
Querying for One Post
To find a specific post (or set of posts), you have two options:
p (int): Use post ID.name (string): Use post slug.
You can use these parameters with any post type including posts, pages, attachments and custom post types. By default WordPress will query for the 'post' post type and not return pages or custom post types—if you want to do this you'll need to add more arguments or use a different argument, which I'll come to later in this tutorial.
So, to return a specific post you would use one of these:
$args = array(
'p' => '32'
);
or:
$args = array(
'name' => 'post_slug'
);
Note that the name parameter takes the post slug as its argument, not its title.
Using the name parameter makes it easier to identify what your query will fetch from the database when you revisit your code at a later date, but there is the risk that it won't work if one of your site's users changes the post slug. The post ID can't be changed so this is safer.
Querying for One Page
To query for a specific page you have two options again:
page_id (int): Use page ID.pagename (string): Use page slug.
So, to run a query fetching just one specific page from the database, you'd use one of these:
$args = array(
'page_id' => '20'
);
or:
$args = array(
'pagename' => 'page_slug'
);
Querying for One Post of Another Type
To run a query for a post of another post type, including a custom post type, you'd also use the post_type parameter. I'll cover this in a bit more detail later in this tutorial, but in brief, to query for a single post in the product custom post type, you'd use this:
$args = array(
'p' => '46',
'post_type' => 'product'
);
Or to query for an attachment, you'd use:
$args = array(
'p' => '46',
'post_type' => 'attachment'
);
Querying for Child Pages
Sometimes you might need to retrieve all pages that are children of a given page, for example if your site has a hierarchical page structure and you want to display a list on each page of that page's children.
Note: You wouldn't do this with posts as they aren't hierarchical, although you can with a custom post type if it's hierarchical.
You have three arguments you can use to do this:
post_parent (int): Use page ID to return only child pages. Set to 0 to return only top-level entries.post_parent__in (array): Use an array of post IDs.post_parent__not_in (array): Use an array of post IDs.
Let's take a look at each of them.
The first, post_parent, lets you query for pages which are children of one specific page.
So to find all pages that are children of a given page, you'd use this:
$args = array(
'post_type' => 'page',
'post_parent' => '2'
);
Note that you have to include the post_type argument as the default post type that WP_Query looks for is post.
Taking this further, this is how you'd use it to find children of the current page:
$current_page_id = get_the_ID();
$args = array(
'post_type' => 'page',
'post_parent' => $current_page_id
);
You can also use this parameter to identify top level pages, i.e. those without a parent:
$args = array(
'post_type' => 'page',
'post_parent' => '0'
);
But what if you want to identify children of multiple pages? You can do this too, with the post_parent__in parameter. This takes an array of post IDs.
So to query for the children of two of your pages, you'd use this:
$args = array(
'post_type' => 'page',
'post_parent__in' => array(
'2',
'4'
)
);
You can also exclude child pages from your query, using the post_parent__not_in parameter:
$args = array(
'post_type' => 'page',
'post_parent__not_in' => array(
'2',
'4'
)
);
Querying for Multiple Posts
It's also common to run a query to either include or exclude multiple posts. You have two arguments you can use for this:
post__in (array): Use post IDs.post__not_in (array): Use post IDs.
The post__in argument can be used for all post types and takes an array of IDs. So to output a list of specific posts, you'd use this:
$args = array(
'post__in' => array(
'36',
'52',
'246',
'354'
)
);
Note: If you use this argument to fetch posts, WordPress will still fetch sticky posts, even if they're not in your list. To omit them, you use the ignore_sticky_posts argument:
$args = array(
'post__in' => array(
'36',
'52',
'246',
'354'
),
'ignore_sticky_posts' => 'true'
);
The post__not_in argument works in a similar way, again taking an array of post IDs, but it will output everything else except the posts listed. You'd normally combine it with other arguments to avoid outputting a huge list of posts.
So to query for all posts of the product post type but exclude a few:
$args = array(
'post_type' => 'product',
'post__not_in' => array(
'36',
'52',
'246',
'354'
)
);
So to combine this with one of our earlier examples, here's how you'd query for all top level pages except the current one:
$current_page_ids = array( get_the_ID() );
$args = array(
'post_parent' => '0',
'post__not_in' => $current_page_ids
);
Note that if you've also registered a hierarchical post type, you'll need to include the post_type parameter in this code to just query for pages.
Querying for Post Types
In some of the examples above I've used the post_type parameter to identify posts of a certain type. Let's take a look at the arguments you can use with that parameter:
post: A post.page: A page.revision: A revision.attachment: An attachment.nav_menu_item: A navigation menu item.any: Retrieves any type except revisions and types with 'exclude_from_search' set to true when they were registered.- Custom Post Types (e.g.
product).
As we've seen above you can use this parameter with other arguments to make your query more specific.
So to give a simple example, here's how you'd query for all of your site's pages:
$args = array(
'post_type' => 'page'
);
Custom Post Types
Querying for a custom post type is simple: use the name you gave the post type when registering it, not the title that's used in the admin menus. So let's say you registered your product post types using register_post_type() as follows:
function register_product() {
$args = array(
'name' => __( 'Products', 'tutsplus' ),
'singular_name' => __( 'Product', 'tutsplus' )
);
register_post_type( 'product', $args );
}
The value you use for the post_type argument when querying for products isn't 'Product' or 'Products' but 'product':
$args = array(
'post_type' => 'product'
);
Attachments
By default if you try to run a query for attachments it won't work, as WordPress sets the post_status of attachments to inherit and WP_Query defaults to 'post_status' => 'publish' unless you specify otherwise. So if you want to query for attachments you must include the post_status argument:
$args = array(
'post_type' => 'attachment',
'post_status' => 'inherit'
);
Note that you could also use any instead of inherit.
Summary
Using WP_Query to create custom queries for posts and post types is something I do a lot. As you've seen from the examples here, there are plenty of possibilities:
- Use it to query for top level pages in your site.
- Use it to query for posts of a specific post type.
- Use it to query for all posts except the ones you specify.
- Use it to query for all the children of the current page.
There are many more possibilities using the arguments covered here, but this should give you a taster.
by Rachel McCollin via Tuts+ Code
