Codex

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

User:JamesVL/query posts

Query Posts

Control which posts show up in The Loop with the WordPress query_posts() function.

It accepts a variety of parameters in the same format as used in your URL. (e.g. p=1 to show only post of ID number 1)

Usage

Place a call to query_posts() in one of your Template files before The Loop begins. The wp_query object will generate a new SQL query using your parameters.

WordPress then ignores the other parameters it received via the URL (such as page number or category).

Purpose

Why go through all the trouble of changing the query that was meticulously created from your given URL?

You can customize the presentation of your blog entries by combining it with page logic (like the Conditional Tags) - all without changing any of the URLs.

Common uses might be to

  • Display only a single post or page on your homepage
  • Show all posts from a particular time period
  • Show the latest post (only) on the front page
  • Change how posts are ordered
  • Show posts from only one category

Query Parameters

This is not an exhaustive list yet. It is meant to show some of the more common things possible with setting your own queries.

Category Parameters

Show posts only belonging to certain categories.

  • cat
  • category_name

Show One Category by ID

Display posts from only one category ID:

query_posts('cat=1');

Show One Category by Name

Display posts from only one category by name:

query_posts('category_name=Staff Home');

Exclude Posts Belonging to Only One Category

Show all posts except those from a category by prefixing its ID with a '-' (minus) sign.

query_posts('cat=-3');

This excludes all the posts that belong only to category 1. There is a proviso however: it will exclude all the posts that belong only to category 1. If a post belongs to another category as well, it will still be picked up.

Author Parameters

You can also restrict the posts by author.

  • author_name=Harriet
  • author=3

author_name operates on the user_nicename field, whilst author operates on the author id.

Post & Page Parameters

Retrieve a single post or page.

  • p=1 - use the post ID to show the first post
  • name=first-post - use the Post Slug to show the first post
  • page_id=7
  • pagename=about

As a consequence of the Template Hierarchy, home.php executes first. This means that you can write a home.php which calls query_post() to retrieve a particular page and set that to be your front page. Without any plugins or hacks, you’ve got a mechanism to run, show and maintain a non-bloggy front page.

More useful perhaps would be to take advantage of WP’s new Page functionality and use that for you front page. You could set your "about page" to be the entry point or maybe your site's colophon. You might even do something a bit more dynamic and set a custom page that shows a list of the latest comments, posts, categories and archives. See the example below.

  • orderby=title - order the list by page/post name
  • orderby=date - self-explanatory :)
  • order=ASC - ascending order

Changes the ordering of the list. This can be handy when making page templates, such as indexes. Note the distinction between "orderby" and "order".

Time Parameters

Retrieve posts belonging to a certain time period.

  • hour=
  • minute=
  • second=
  • day= - day of the month; shows all posts made, for example on the 15th
  • monthnum=
  • year=

Page Parameters

These deal a listing of posts broken up over multiple pages, not with the parameter.

  • paged=2 - show the posts that would normally show up just on page 2 when using the "Older Entries" link.

Examples

Exclude A Category From Your Home Page

Placing this code in your index.php file will cause your home page to display posts from all categories except category ID 3.

<?php
   if (is_home()) {
      query_posts("cat=-3");
   }
?>

Retrieve a Particular Page

To retrieve a particular page, you could use the following:

<?php
query_posts('page_id=7');      //retrieves page 7 only
?>

or

<?php
query_posts('pagename=about'); //retrieves the about page only
?>