Incoming Objects

The Related Object Fields are a powerful way to relate an object in WordPress to one or more other objects. There is one small problem with these field types though – the relationships these fields set up between two objects are unidirectional. For example, suppose Post A has a related_post field with Post B selected. Technically, this is stored in metadata for Post A, which means that Post B doesn’t really relate back to Post A in any way.

Let’s look at it more generally though – Post A could be selected as a related post in not just one but many posts, which we represent in Figure 1 below:

Figure 1: Posts related to Post A

Here we illustrate a scenario where Post B, C, D and E each have Post A selected in a related post select box.

In the context of Post A, we refer to Post B, C, D and E as incoming posts, and the API has methods of that namesake to query these posts. In fact, each of the MEOW_Post, MEOW_Term, and MEOW_User classes has an incoming, incoming_terms, and incoming_users method to deal with incoming posts, terms and users respectively, allowing you to query any type of relationship.

As you’ll see, these methods are incredibly easy to use, and they’re also presets on the WOOF::posts, WOOF::terms, and WOOF::users methods, so you can tweak any other query arguments you need to.

Querying incoming posts is actually quite a tricky operation to perform behind-the-scenes, so these methods will save you a lot of time if you ever need to work with incoming objects.

An example from the MasterPress site

We like to eat our own dog food, so the MasterPress web site uses its fair share of related field types. We’ll look at one example in particular, to see how to work with incoming posts in practice.

Each method in the Class Reference is represented by a post under the custom post type method, which contains a details field set with a related_methods multi-item related post field:

Figure 2: The Details field set for our method post type

And here is a screenshot of the content entered into our custom field, for the WOOF::query_posts method specifically:

Figure 3: Related Methods Content for WOOF::query_posts

So this defines the methods that WOOF::query_posts relates to. Let’s look at how we could list all of the related methods in 2 separate lists – one for the methods the current post is related to, and one for the incoming methods related to this post:

Example 1: Outgoing and incoming methods

This might give us something like:

Figure 4: Related methods lists

So this works well, but you’re probably thinking “surely just one list that shows related methods going both ways is better?”. If you are thinking that, you’re surely correct – for this particular application, we really just want to show related methods together.

Lists of related objects, both ways

While our API doesn’t contain any specific methods to give us a list of both outgoing and incoming related objects, we can call on some facilities of the WOOF_Collection class and get that list in 3 lines of code. First, here’s what we’ll need to do:

1. Get the list of methods that this method relates to, in the details->related_methods field
2. Get the list of incoming methods relating to this method.
3. Combine the results from 1 and 2 and mix well.
4. Remove any dupes, as Figure 4 shows a few.
5. Sort them by title, because we care about maximum usability.

Let’s look at the code to do it:

Example 2: All this in just 3 lines of code!

This example shows some of the great benefits of using the WOOF_Collection class – steps 3, 4 ,and 5 are quickly achieved by using the WOOF_Collection::merge method to merge the outgoing collection into the incoming, then using WOOF_Collection::dedupe to remove any duplicates (which uses a comparison on the “id” property by default), and finally the WOOF_Collection::by method to sort the collection by the title “property”.

Note the explicit use of the posts method on line 4 of example 2 above, which is necessary since we actually need the collection of posts before we can merge. While you can iterate over the related_method object directly, you can’t use it to merge into another collection.

In the end, we have our $related variable containing the list of related methods, which we can present as one tidy list. Try doing all that in 3 lines of code without this API 🙂

Dynamic incoming_something methods

To make querying our incoming posts, or terms even easier the MEOW_Post, MEOW_Term, and MEOW_User classes all contain __get and __set magic method implementations which can retrieve incoming posts and terms of a certain type or taxonomy. We do this by accessing the unknown method or property “incoming_post_type_plural” to get the incoming posts under post_type or “incoming_taxonomy_plural” to get terms under taxonomy. Let’s rewrite line 3 in example 2 to use this trick

Example 3: Another magic method trick

Incoming Terms and Users

We won’t cover the use of incoming terms and users here, since they’re very similar to the techniques used for posts. Please refer to the Class Reference for more details, specifically the methods: MEOW_Post::incoming_terms, MEOW_Post::incoming_users, MEOW_Term::incoming_terms, MEOW_Term::incoming_users, MEOW_User::incoming_terms, and MEOW_User::incoming_users, which all contain example-usage.

• ← Related Object Fields
• Manipulating Posts and Terms →