Manipulating Field Sets and Field Data
To complement the content entry interfaces MasterPress brings to the post, term, and user editing screens in WordPress, the MasterPress API includes methods to manipulate field sets and the content for custom fields programatically via the MasterPress API. Keeping in line with our goal of making this API as easy to use as possible, a lot of this manipulation happens through simple property assignment statements, made possible by implementations of PHP′s __set magic method across all of the field and field set objects.
The material in the examples below assume that you are familiar with the techniques presented in the Working with Field Sets and Fields and Manipulating Posts and Terms recipes.
Editing single-item field sets
First we’ll take a look at an example of manipulating existing data first, which will introduce some interesting features along the way. Let’s use our example car again, from the Working with Field Sets and Fields recipe:
Figure 1: Our example content
Here is an example of how we might edit the details for this car, noting that some of the changes are a little contrived to prove our point:
Example 1: Editing our car fields
There’s a few interesting points to make about this example:
- We are setting the field values through simple properties on the $det, which is a MEOW_FieldSetCollection but these properties aren’t actually available in that class. Again, we’re making use of the __set magic method to allow highly intuitive field assignment.
- Lines 8 and 11 set the make and related model fields, which are related term and related post fields respectively. Internally, these fields require storage of very different values to what we’re assigning, yet the example works as expected.
- Likewise in Line 10, we set the image field via a WOOF_Image object, but we certainly don’t store that in the database.
The value_for_set method
Lines 8, 10, and 11 of example 1 appear to be very liberal about the values they allow you to assign fields to. This is made possible by a special value_for_set method that field types can implement, whose job it is to take an assigned value and transform it into the correct type of value to store.
For basic text fields, there is no need to implement this method, since their values are simply text as it is assigned, but for field types such as the suite of related field types and the image field type, this method can be used to allow theme developers to set values for fields in many different ways.
For example, the assignment on line 11 is made possible by the MPFT_RelatedPost::value_for_set method, and the assignment on line 10 is made possible by the MPFT_FileBase::value_for_set method. These methods aim to make the API more forgiving, and if you’re looking for documentation on any special allowances for field values, check to see if the field type class has a value_for_set method.
Editing multiple-item field sets
Now we’ll consider how to work with multiple field sets. Lets use our photos example from the Working with Field Sets and Fields recipe:
Figure 2: Multiple photos
First, we’ll look at a quick example of editing an existing item in this collection, which is similar to Example 1:
Example 2: Editing the 2nd specific caption
Editing an existing item in a multi-item set is much the same as for a single-item field set. In line 7, we assigned the 2nd photo from the collection to the $photo variable. From there, it’s very similar – just set the field values you want to via property assignment, and call update at the end.
Adding new items
Adding new field set items to a multi-item field set is quite easy, and uses similar techniques to those explored in Manipulating Posts and Terms. Let’s look at code to add another photo to the field set in Figure 2:
Example 3: Adding a new field set item
Line 7 of this example is the only point of difference here: we simply create a new photo set via the MEOW_FieldSetCollection::create method. From there, it’s a simple case of setting the properties fields again, and calling update.
Another way you can add a new item is via the MEOW_FieldSetCollection::insert method, which creates a new item and updates the database immediately:
Example 4: Inserting an item
Note: the update method will recreate all of the metadata stored against the entire collection each time it is called. Thus, if you need to make lots of additions you are better to use create instead, with a single update at the end.
Removing items
Removing items from a field set collection is also an easy operation. Let’s remove the photo we just created, which would be at index 4:
Example 5: Removing an item
We first find the photo we want to remove, and once we have it, call the MEOW_FieldSet::remove method, which removes the object from our collection.
We’ve intentionally changed the object that update is called on here though, instead choosing the actual post object stored in $beetle. This is perfectly valid and we’ll explore this point in detail right about now…
Creating or editing an object and its field data at the same time
The MEOW_Post, MEOW_Term, and MEOW_User fields bring an important feature to the update methods of their WOOF counterparts – the ability to detect changes to MasterPress custom fields, and also update those. This even works when creating an entirely new post, term, or user too. Let’s look at a quick example:
Example 6: Creating posts and their field sets at the same time
The code in Example 6 is made so much better by the fact that we don’t have to call update separately on the field set – it makes field sets feel like a core feature of WordPress in a sense.