In order to learn how to create a widget we need to understand the WordPress Widgets API. The Widgets API is a bit confusing because it includes both sidebars and widgets.
WordPress Sidebars and Widgets
If the original developers of WordPress had seen down the road to what’s happened with sidebars and widgets, they probably wouldn’t have named sidebars “sidebars” and they probably would’ve had a Sidebars API and a Widgets API entirely separate from each other. They didn’t really anticipate how flexible and complex the use of sidebars and widgets would be so they include them all in this one Widgets API.
The net result of which is that we’ve already talked about sidebars. How to create sidebars, how to register sidebars, how to use dynamic sidebars, declare a dynamic sidebar and that kind of thing. We’ve already learned how to do that. We’ve already interacted with this Widgets API a bit already.
What we’re going to be looking at now is not the sidebars functions but the widget functions. The widgets of course are those bits of functionality that are in the widgets panel that you drag into a sidebar. There’s a whole set of these widget functions that we’re going to learn about. We’re just going to jump down here to the section called Default Widgets.
2 Parts of Widget Creation
Fundamentally, in order to create a widget, the widget creation has two parts. The first part is this section right here where you are extending the widget class and this is where all the real function of the widget happens. This is where all the function of the widget exists.
The second part of it is this Register Widget. You create a widget and you register a widget. Just like the sidebars, you create the sidebar and register the sidebar. The sidebars don’t show up properly and don’t work if you don’t have all of those elements defined. The same thing is true with widgets. If you don’t have both the widget definition and the registration of the widgets, the widgets won’t show up and won’t work. So, we have these two parts, extending the class and registering the widget.
Now, the widget class actually has a whole bunch of different parts to it. However for our purposes, there really are only 4 parts that we need to interact with. Those 4 parts are the constructor function, the form function, the update function and the widget behavior function.
This constructor function is essentially where you sort of setup the widgets own definition. It allows you to create and use several widgets of the same type on any given page. Back when I started working in WordPress, most widgets could only be used once on any page and couldn’t be used multiple times on the same page.
That was because there wasn’t a system for reusing the widget code several times on a given page but this extended widget class gives us that ability and this public function__construct is where we setup the elements that can be reused in each widget or can create a separate instance of each widget.
Create the Form
The second part of this is the form. This is essentially that part of your widget where you fill things out. In this case, let’s go to my widgets panel to just look at an example of one of those forms. Your form is this: the title, the content here, this checkbox “Automatically add paragraphs” and I have other things like dynamic widgets that adds an additive element to the form. Once we’ve gone through the construction part of widget, the next thing we’re going to do is create the form that allows us to do the data input.
Update the Widget
The third part of this is to update the widget. What we’re going to end up doing is saving 3 instances of widget information. We’re going to have the old instance which is the old information that was stored in the database about this widget. We’re going to have a working instance which is all of the information that we have entered into that widget form then we’re going to have a third instance which is the new instance which is what will happen when the old instance and the working instance get combined.
At any point in this process, we really have 3 sets of data to work with. We have the old set, we have the set that we’re working on and we have the new set that exists after it’s been saved. This is setting up the process for doing that.
Action and Behavior of the Widget
Finally, we have the actual behavior of the widget. Once we have updated some options in here, we have the forms, we can enter the data, we have the ability to update the widget options with that data and now in this last part, we take the information that we entered in the form and we do something with it. In our case, ultimately we’re going to decide if we show a title and decide if we show an image.
If we show a title, we’ll show the title, if we’re going to show an image, we show the image, if we’re going to show the page title, we show the page title and in all cases we’ll show the excerpt and the link. All that happens inside of this fourth function which is the action and the behavior of the widget.
Now, because we are extending the existing WP_Widget class, these names should be unchanged. You should use these names because they correspond to existing names inside of this class. When we build our construct here, it’s going to be using the construct class inside of WP_Widget. When we do our form, it’ll be doing the same thing. We could change the name of these but then they wouldn’t behave properly.
Public Function Names
These public function names are function names that you should imagine or set in stone. You could always add additional functions inside the class to do something and that would be an extension of a class. But these functions are going to be critical for us to have and they need to be named exactly what they are here. That’s the basic way in which this works.