Multiple Post Queries
The MasterPress API offers many ways to retrieve multiple posts from your WordPress site, with post-related methods available in both the main WOOF class, but also many other classes across the API. All of these methods return a WOOF_Collection of MEOW_Post objects, rather than simple arrays.
First we’ll cover the fundamental way to retrieve post collections – via the WOOF::posts method, which is an abstraction around the WordPress methods get_posts or query_posts. This method is important, since all other methods which return collections of posts do so by preparing a set of post query arguments and then running them through this method.
Let’s look at a simple example using the WOOF::posts method, which supports the same parameters as the WP_Query class in WordPress:
Example 1: Retrieving a collection of posts
This is fairly similar to using get_posts in WordPress, except we don’t need to call functions like setup_postdata to affect the state of our loop. Note that the code in Example 1 does not affect the main query loop so you can’t follow it with a standard loop or use any functions (pagination for example) or plug-ins which expect that. If you want to affect the main query loop, our WOOF::posts method supports an additional argument not supported by get_posts – the query parameter, which needs to be set to 1:
Example 2: Using posts to affect the main query loop
Behind the scenes, setting the query parameter to 1 forwards the call to query_posts instead of get_posts. Another way to do this is to call the WOOF::query_posts method, with our original parameters, which is a preset on WOOF::posts with query already set to 1:
Example 3: Example 2, Line 1, rewritten to use WOOF::query_posts
The WOOF class contains a lot of other presets on WOOF::posts: WOOF::posts_by_menu_order, WOOF::posts_by_title, WOOF::posts_in, WOOF::posts_not_in, and WOOF::fposts are all examples (refer to their respective linked pages in the class reference for examples).
Accessing posts from a WOOF_PostType object
The WOOF_PostType object contains a whole host of methods for accessing posts of the type the object represents.
Firstly, let’s look at the basic way to access posts underneath this post type, by simply using the WOOF_PostType::posts method:
Example 4: Accessing posts of a specific type
Note that when you access posts in this way, the posts_per_page parameter is reset to -1 by default, since it feels more intuitive that querying posts with a post type for context would not limit the posts per page via the global setting.
Magic method queries on $wf
The WOOF class has a useful implementation of the __call magic method to run a query on a specific post type, by allowing you to call the plural form of the name of the post type with the desired query arguments:
Example 5: Accessing a car query using magic methods
This can be a very intuitive way to run queries under specific custom post types.
Posts attached to taxonomy terms
You’ll notice that there are a series of methods in WOOF_PostType that are made up of conjoining words, such as in_the, in_a, in_an, with_a, etc. These methods are designed to return a list of posts which fall under this post type, and are attached to specific taxonomy terms. They all contain the following (first 3) arguments:
- Array / String $terms – an array or CSV string of term slugs
- String $taxonomy – the taxonomy to search under
- Arguments $args = array()
These let you quickly perform taxonomy queries that almost read like English:
Example 6: A list of fast cars
These methods all prepare the tax_query parameter, and while they don’t allow everything made possible by tax_query, they certainly ease the burden of working out the correct syntax in many cases.
Its important to note that each of these methods has an $args parameter, which lets you tweak the arguments that get forwarded to the WOOF::posts method. So we can change any of the other arguments to further clarify our query, apart from the post type and tax_query, which are reserved by this function:
Example 7: Fast cars, by date
One other thing we can tweak in the $args parameter is our custom “query” parameter, which decides if the query affects the main loop – this allows us to use these methods to setup main query loops as well, which is rather flexible.
Accessing posts from a WOOF_Term object
Another way to lookup a set of posts in the MasterPress API is to first retrieve a single term object, and then request a list of posts attached to that term. This is almost like issuing a taxonomy query in reverse, let’s look at an example:
Example 8: Accessing posts attached to a taxonomy term
Again, this is simply a preset on the WOOF::posts method, and WOOF_Term has a few more preset methods for convenience.
Accessing Posts from a WOOF_Post object
The WOOF_Post class itself has a number of methods for accessing posts that are related to the current post the object represents. One group of these worth noting here are those concerned with hierarchical post types, where we can access children, siblings, parent, and ancestor posts, via the WOOF_Post::children, WOOF_Post::siblings, WOOF_Post::parent, and WOOF_Post::ancestors methods.
For example, here’s how we could access the children of a page:
Example 9: Accessing children of the current page
This is a far more intuitive way to access the children than creating the necessary query with post_parent parameter yourself. Please refer to the class reference for examples of the other hierarchical post types methods linked to above.