Design Philosophy
While a key part of the MasterPress API involves getting custom field data out of MasterPress and into your templates, the majority of it is actually concerned with providing a better API to WordPress core itself, with a focus on a number of key design attributes.
Consistency and Memorability
As any experienced jQuery developer will know, one of the best things about that library is that you find yourself needing to access the documentation less and less the more you use it – that is, it is highly memorable. The MasterPress API has been heavily inspired by this ideal, being written to be as consistent as possible in a number of key ways:
- Variable and method names are always in lowercase with multiple words separated by underscore. While this may sound small, it makes a big difference, for example, when you don’t need to remember the capitalisation of “ID” when accessing object IDs, in our case, it’s always id.
- Everything needs to be echoed – all methods in this API return a result that always needs to be echoed into a template. This saves developers from wondering whether they need to use get_the_property, or set a flag to return a property: the_property(arg, TRUE) or something else – in our case it’s always going to be:
echo $the->property - Normalised property names – property names are generally normalised both within and across different object types in WordPress. If I want an ID of an object, it’s always “id” regardless of whether I’m dealing with a Post object, a Term, or a User.
Structure and Hierarchy
Since it is entirely object-oriented, the MasterPress API allows you to write code that reads a lot better – in some cases it almost reads like english (or at least some type of pseudocode). A brilliant example of this can be seen in the code snippet below, which displays a collection of recipes (a custom post type) which contain the ingredient lime (a custom taxonomy term).
Even if you were not particularly familiar with WordPress or indeed PHP, you could probably make some sense of what the code above is trying to do. Compare this with the need to use a query to achieve the same result:
The code above is a lot more difficult to decipher. It should be noted that our API needs to use the WordPress API to work its magic too, but it aims to make the interface to your posts and terms a lot easier to grapple with.
The MasterPress API also makes clever use of PHP’s dynamic language features (so called “magic methods”) to augment core objects in WordPress with custom field data made available by MasterPress, in the most intuitive way possible. Lets take our recipe example again, and suppose we want to place an image underneath the recipe link, taken from an image field called photos in the field set details. This is very easy in the MasterPress API:
Ignoring the question of “how is this possible?” for now, the code above achieves what we set out to do without needing intermediate retrieval of IDs which are then passed into other functions to get our final result – the dynamic structure of the objects in the API mean that we can dig into their properties by chaining property access across a single line. Again, if you’re familiar with the jQuery library, you’ll understand why this can be a very powerful coding style, while also being highly developer-friendly. (If you’re wondering about whether the code above will explode when properties don’t exist, the section on Silent Failure covers this).
Brevity
The MasterPress API aims to allow you to write theme code that is brief and concise, by abstracting over some of the more complex operations in the WordPress API. The examples in the Structure and Hierarchy section above illustrate this point well – while the final example there is doing some big things behind the scenes to render out a list of links and photos, the code required in your theme template is very concise and (hopefully) just makes sense.