WordPress Widgets: Refactoring, Part 10

As far as the WordPress Widget Boilerplate refactoring goes, we’re at a good place. A lot of work has been done such that introducing new classes, features, and functionality should be much easier.

And not only that: It should be easier to follow.

Thanks the work in the last post, we have a lot of work to build off of – namely, an basic administrative interface.

WordPress Widget: UI Improved

Finally, the last post said:

Over the next few articles, this is going to continue to evolve but, as you can see, we’re making sure that we have a single base class of functionality for talking with WordPress and a class specifically for rendering the administrative form.

And that’s where we’re going to pick up in this article. Specifically, we’re going to look at sanitizing and serializing the data as well as retrieving the data saved in the widget.

The WordPress Widget Boilerplate: Refactoring Part 10

Refactoring The UI

Before we get into serialization, there’s some minor work that we’re going to need to do to our administrative view. Recall from previous posts in the series that we’ve built a form that accepts:

  • a title,
  • some content,
  • and a checkbox.

This displays just fine, but it excludes some key features of the Widgets API. Namely, we need to make sure that we’re properly naming our elements using the following functions:

And then we’ll write our function simply called get which I’ll explain momentarily.

The functions above are necessary because it helps WordPress keep track of how many instances of the widget are being used and which one the user is editing. In other words, we get a lot of functionality for free.

Before showing you the code, I want to briefly discuss the purpose of the get function that we’re going to introduce. In short, it’s a way for us to pass a key (as in the key in a key/value pair) into a function and then have it easily retrieve a value for us so that it keeps our interface as clean as possible.

So, first, the get method:

The important thing to note is that this method accepts not only the key for the value we’re reading but an array referring to the instance of the array.

And now, the refactored UI:

But this still leaves functionality lacking and it leaves work for us to do. Namely, we need to sanitize the data and pass it back to WordPress, so it saves the data.

Sanitization and Serialization

For the purposes of our example, we’re going to be very strict in what we allow. Namely, we’re going to only support basic text, and we’re going to strip out everything aggressively.

This means we’re not going to allow markup or anything like that. Instead, we’re going to remove everything that’s not basic text. We can decorate it a little bit when it comes time to display it on the front-end, but we’ll leave that until the appropriate post.

To do this, we’re going to use the following functions:

Recall that we have two fields in our widget – the title field and the content field. Depending on the type of widget you’re building, you may only need a single class or function to sanitize the data. In other situations, you may need something more complex.

Keep that in mind as we go through this code as this is not going to be a one-size-fits-all solution. Instead, it’s going to be specifically for this.

Anyway, to sanitize the data, we’re going to write a class specifically for this purpose, and then we’ll make it available to our WidgetAdmin class.

Here’s the class in its entirety with a description to follow:

The class should be straight forward. It takes in the incoming values of the widget, sanitizes them, and then returns a new array to be handed back to WordPress.

There’s a catch though. This class must be a property of the main Widget class that was shown in the last post.

Secondly, the update method that’s part of the Widgets API is what will call into this class. It’s not necessary to pass the $oldInstance variable into the serializer but it’s required for the update method.

Here’s the Widget class as it’s currently built:

But if you refresh the page, you may notice that the sanitization and serialization do not seem to work when retrieving the data. And that’s what we’re going to look into in the next post.

Retrieving Data

Notice that although the functionality seems incomplete for this (since the unsanitized data is still displayed), we’re focused on making sure that we’re writing classes with cohesion, responsibility, and that aren’t tightly coupled.

We’re going to iterate on this a bit more in the next post. So study the code above, implement it if that’s what you’ve been doing, and we’ll go from there in the next post.