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 5′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.

Latest From the Blog

MasterPress 1.1.4 now available

MasterPress 1.1.4 is now available. This release contains an important compatibility fix for WordPress 4.5 to allow correct detection of the taxonomy term editing screen. Without this fix, any custom fields you have attached to custom taxonomies will not be shown at all in the editing form. Note also that MasterPress will still detect the edit screen correctly in… 

Plugin Requirements

MasterPress requires a minimum of WordPress version 3.4, MySQL 5, and PHP version 5.2.4.

We also recommend that PHP is configured to use a memory limit of 64MB per request (128MB may be required for sites with higher complexity).

This plug-in is not compatible with the WordPress.com hosted service.

Traversal