Integrating with The Loop, and the WOOF loop
The Loop is a fundamental building block used by WordPress themes to display posts. A simplified version of The Loop, for an archive template, might look something like this:
Example 1: The Loop (archive template)
The Loop uses the procedural WordPress template tags to setup a structure that loops over the current active query. The $wf object has one key method to interact with the MasterPress API from inside the loop – WOOF::the.
By way of example, let’s suppose that we’ve setup a “Drink” post type, with a “details” field set with the following breakdown of fields:
Figure 1: The details field set for a Drink post type
Furthermore, we intend to use the “description” field in this set to replace the standard WordPress “content” field in The Loop. Calling on the WOOF::the method, here is our modified loop which will bring in our description, and a photo thumbnail too:
Example 2: The Loop (using the MasterPress API)
There’s a few things to note about this code:
- We’ve replaced all “the_BLAH” style template tag calls with $wf->the->BLAH instead. This is entirely optional, it simply demonstrates how you can use the MasterPress API for these standard content fields too.
- Note that all of the $wf->the property calls must be echoed. This is a design choice – all methods (apart from debug) in the MasterPress API will only return things to you without echoing, to keep things more consistent.
- $wf->the simply returns a WOOF_Post object, representing the current post in The Loop, and then we call on some standard methods, and magic method tricks to display our custom field values.
The WOOF Loop
The code in example 2 does exactly what we need, and if you’re wanting to quickly integrate your fields into The Loop, that’s probably enough. WOOF has another method that can make our code just that bit more concise, and remove some of the repetition we can see in Example 2 – WOOF::loop. Let’s take a look at another example, which is Example 2 rewritten to use a WOOF loop:
Example 3: The WOOF Loop
This is fairly different to our standard loop, but not that hard to grasp. Of note:
- we replace our while loop and the_post setup code with a more simple foreach ($wf->loop() as $the) … endforeach loop (refer to PHP: foreach in the official PHP manual, if you’re unfamiliar).
- WOOF::loop simply returns a collection of WOOF_Post objects from the current query. This means that the loop variable $the is the same post as we retrieved via $wf->the in Example 2.
- We’ve also removed some of the $wf->the repetition we had in example 2, by using this alternative loop.
It’s entirely up to you whether you want to replace your standard theme loops with this alternative – the point we’re trying to make is that the MasterPress API lets you take this as far as you’d like to.
Note that there’s one more small improvement you could make to Example 3, especially if you needed to access more fields out of our details field set. In example 4, we create a $details variable to store our details field, to remove the repetition of accessing it:
Example 4: DRYest code ever.
Even more concise code with short open tags
For maximum compatibility with server setups, most examples in this documentation use the long form of <?php echo to echo values out to our templates. Since you need to echo a lot when using the MasterPress API, it really shines when you configure your server to use the short tag syntax for echo: <?= (which is now always available in PHP 5.4).
Let’s rewrite Example 4 using the short style for <?php echo:
Example 5: An even lighter sprinkling of content
The PHP short tag options are much-loved and much-derided at the same time. Most people creating reusable themes won’t use them because it makes their theme dependent on server configuration. But if you’re just creating a theme for yourself, they can really make your template code very readable.