Having described the basic concept for creating a widget, we’re now going to put this basic concept into play in our child theme.
Where To Create The File Structure
If you are not developing this in the context of a child theme but are instead doing this as something for Thesis or in Genesis or some other theme, you would do this inside of your custom_functions.php file in the Genesis theme. But because this class is teaching how to do this in the context of a child theme, we’re going to be using the child theme’s file structure for adding this.
Create Widgets Folder
Way back when we set up this file structure, we created this widgets folder. I told you that this is where we’re going to put our widgets information in so that’s what we’re going to do now, we’re going to create a file and it’s going to be a new PHP file. We’re going to give it our unique identifier, crtc which stands for custom responsive child theme but of course you’ll put in whatever it is you are using. We’re going to call this, crtc_example_widget. We’re creating our new file for this.
In this new file, I’m going to paste a template for this. This template essentially includes everything that I just mentioned. It’s got the public function__construct(), it’s got the public function form, public function update and public function widget. We need to start this whole process off by giving our widget a name.
Syntax For Creating a New Class
The name I’m going to give this is, CRTC_Example_Widget. Notice how I am using uppercase letters in here? The acronym is all uppercase and the first letter of each of these is uppercase. That is the WordPress standard for identifying the fact that we are talking about a class. This is not just a function we’re defining here, it’s not just a widget name, we’re actually creating a new class so we’re using this uppercase letter in the definition of that class name. This class is going to extend the WP_Widget class.
Build the Construct
The next thing for us to do then is to build our construct so we’ve got our public function__construct. The construct includes two things. First, you are going to set up our widget options and secondly, we’re going to create the widget itself. There are a number of widget options that you can set inside of this construct but we’re going to set two of them. We’re going to set the class name and a description.
Set Widget Options
First, the description is this thing right here where it says, “Display the number of comments Akismet has caught”, that is the description that we’ll be creating. Then here, the class name is something that you can see that’s added to the HTML. Right here, widget_black_studio_tinymce, that is a class name that is added to this widget and that lets you give specific CSS classes for this type of widget so you could say li class widget_black_studio_tinymce. Anyway, this is the class name so we’re going to setup a description and a class name in this widget options.
I’m just going to jump right over here to the page and I’m going to cut and paste this information. We’ve defined a variable called $widget_options which is an array and the first element of that array is its class name. Now we want to specify the class that we want added here. I’m going to just say, crtc-example-widget so it’ll automatically append this.
Under description, we’re just going to enter a description, ‘This widget creates a text box similar to a text widget’. Neither of these are required but a description is useful for helping somebody figure out what to do with their specific widget so I always like to do both of these things.
The next part of this is the actual construction itself and this takes a very specific form. What this form means is that this information here is being sent to the construct function of the parent. The parent in this case, is WP_Widget. Because this is extending the parent class, what’s happening here is that this section is going to be immediately translated into the construct part of the WP_Widget class.
Now, there are other ways of specifying this but this is the PHP5 way of tying this widget constructor into the same analogous function, WP_Widget so it needs to look like this, parent::__construct. Then it takes 4 arguments but only 2 of them are required.
Arguments in WP_Widget Class
The first is the base ID and this is kind of like a slug. It’s just again a name that we’re going to use to define it. You might as well leave out widget because when this construct gets built, it automatically adds widget to this base_id. I’m just going to say, crtc_example. Then we’re going to give the widget a name. This widget name is what you see here on the widgets panel right there, Akismet Widget, Another Wishlist Member, Breadcrumb NavXT. In this case, we’re going to say, Example Text Widget.
The third argument is the &widget_options variable which we defined up here. It will take a fourth argument as well and that’s called, control_options. It’s a place where you can set up specific settings for the way in which the form will be displayed. I’m not really going to talk about that in this case because they are generally not necessary and certainly not necessary for what we’re doing today but you could create a set of form options as well and add that to this widget definition.
Unique Widget ID
Having said that, this public function__construct is relatively simple. We’re just defining our options then we’re creating the widget. Every time these widgets are created, what happens is this unique widget ID gets incremented. For example, the unique ID of this widget, the first time this widget is used is going to be widget, crtc_example_1 and the next one will be example_2, the next one will be example_3. That’s what this ID is for.
Obviously you can see that in action here where we have two different text widgets. If we look at those two different text widgets here, here’s your ID, black-studio-tinymce-3, this is analogous to that widget ID where this number gets incremented so you can keep track which widget goes where. That’s that public function__construct.
Set Widget Variables For Our Form
The next part of this then is to create our form. Our form in this case, we’re going to start off by setting up our widget variables. I’m just going to cut this out here for a second.
Our first widget variable is the title of the widget so we’ve created a variable called title then we’re saying, the variable title equals this instance of the title. Notice how form takes instance? That means this specific instance of the widget. If you have 15 of the same widgets on the same page, each instance is different so each title is potentially different.
The title is this instance of the title and I’ve got this sort of generic thing, another variable equals instance of another variable. But what we’re going to do here is say, &show_title = &instance[‘show-title’]; and the final is going to be say, &message = &instance[‘message’]; and for this simple widget, those are the three variables that we’ll be using.
We’ve set up our variables first and we’ve said that this variable is going to be equal to the instance of the title, this show_title is going to be equal to this instance of show_title and the message is equal to this instance of the message. Obviously, any one of these things could be my favorite generic variable fishsticks and it would continue to work because this is a variable name so it could be whatever you want it to be. That’s the variables.
Create the Form
Now, we have to create our form. When we create our form, we’re using HTML input types. In order to use these HTML input types, we are first escaping PHP to go in to HTML then what we’re going to do first is have our title. I want to talk a bit about the different types of input because the first kind of input we’re going to do is a text input. If you go to w3schools and look at their forms, inside of this form, you have a variety of different input types.
Different Input Types
There’s input type=”radio”, input type=”password”, input type=”text”, input type=”checkbox” and then there is another kind of input type that is called text area. It’s not actually an input, it’s analogous to an input and it’s a text area.
The first one we’re going to look at is input type=”text”. Let’s look at the input so you can see which attributes the input can take. These are the standard attributes. It can take a class, an ID, a title, it could also take a tab index which might be interesting in some contexts, it can take a style and a name. We’re going to be using these attributes here in this form for text.
We start off with input and we’re going to give it a class. Now, the class is a built-in WordPress Admin class called “widefat” and this is going to give it a specific width. We don’t have to use this this class if we don’t want to but we will because it’s built specifically for this purpose.
So we’ll say our input class-“widefat” and now we’re going to echo this get_field_id for title. This is a function inside of this class where each instance of the title gets a field ID so that again you can have 20 copies of the same widget on the same page.
How Input Works
If you specified an ID here, then it will be the same each time and you don’t want it to be the same in each time. What happens is, this get_field_id is the function inside of this widget class that goes and grabs the ID, the specified field and the unique ID of that specified field. The ID is going to be this unique number and the name is analogous, it’s the same thing.
Instead of get_field_id, it’s going to be get_field_name for that instance of the title. The type of this is equal the “text” and finally, the value of our input is going to be the value of the variable $title. So we’ve got our variable $title here which is the instance of title. The value is going to be the value that sits inside of that variable. That’s how this input works.
Label the Input
Now, we are going to put a label on top of this input. We’re going to tie the two IDs here together so the label for this input is going to be this get_field_id(‘title’). The label is going to be tied to this input and the text that we want inside this label. This is an attribute that is unique to labels and it allows you to select the label and it will automatically place the cursor in the input.
See how I selected ID and now it selected that box? If I click on the title, it does that? That is the ID attribute of label. If you leave it out, you can click on this and nothing happens but if you leave that ID and when you click on the label, it takes you automatically to the input field that’s related to that label which is another reason why we want to use a unique ID. So label for and it gets this field ID and it links it to the ID of this input class.
This one is actually a re-setup and doesn’t require us to do anything, this one is very generic now. The text area is a bit different than input type=”text” because it will take a width and a height, it will also take an ID, a name, plus it can take a default value.
The input tag here, is a self-closing input tag, there was no closing tag for the input. The text area is not self-closing so it has a typical HTML tag. The text area has an opening tag then the content and a closing tag.
Again, our label is the same as above here except in this case, what we’re going to do is our text area is going to be our message so instead of another variable, what we want to do is grab our message. We’re going to let it be 16 columns wide and 20 columns tall, the field ID is going to be message so we replace the field name and we’re going to echo not another variable but this variable that we created up here, so not variable but message.
If this wasn’t in a variable, it would put the default text there instead and would never show you what was being stored so we always have to use this function here inside of the text area tags to display what has already been stored.
Create the Checkbox
Now we’re going to create one more type of input and that is going to be the checkbox. Notice how I’ve wrapped each one of these in paragraph tags? That’s a convention for creating this form. The next piece of information is a checkbox and this checkbox is going to say, should you display the title of the widget on the page or not?
That’s the thing I hate about text widgets is if you put a title in your text widget, then the title automatically displays and if you don’t put a title in the text widget, then you have a whole bunch of text widgets that you don’t see a title for when you’re looking at your widgets panel. This is something I always put in my widgets because it allows you to put a title in but still not display it.
This is an input. We’ve got a and. These are classes that WordPress creates. Actually, this is an innovation here so I’m going to cut it out for the moment. We’re going to get to that in a second.
If you’re familiar with checkbox, you’ll know that checkbox often takes this thing that’s called checked, and we’ll get around to showing you how to use checked but at the moment, but we’re not going to use it. So we’ve got type=”checkbox”, id=”get_field_id(‘show_title’), name=get_field_name(‘show_title’), value=”1″, so if it’s checked, then its value is equal to 1.
Beside this input, we’re going to add a label and that is again for that field ID show_title. The label will be, “Display the widget title”? If you check on it, the answer is, “Yes, display the widget title”. Now that we have our form, we need to have that system of updating of the pieces of that form. That’s our new instance, working instance and old instance. These two values here come directly from the class so you don’t change these, you’d use new instance and old instance.
Create a Working Instance
What this is going to look like then is this. We’re creating a working instance called instance, it equals the old instance so we start off by just taking the value of the old instance and writing it into this value of the working instance. Then working instance ‘title’ is going to be equal to $new_instance[‘title’] and the working instance of ‘another_variable’ which we don’t really have is not going to be another variable, is equal to a $new instance[another variable’].
Actually, what we have here is $instance[‘show_title’] = $new_instance[‘show_title’] and $instance[‘message’] = $new_instance[‘message’] then we return instance. That’s fairly straightforward essentially, this will get more complicated here when we start sanitizing the data because that’s really what this is for. It’s for taking this information and sanitizing it before it goes into the database but we’re not going to talk about that quite yet.
Setup Output Variables
The last thing we want to do here is setup how the class is going to behave, what’s it’s going to do. It does a couple of things. First, we have to set up our output variables and it looks like this. Notice that this public function brings in the value of $args and brings in the value of $instance. Instance are these things that we saved here. Args is something else that it gets from the theme and I’ll talk about that here in a second. Again, we’re going to set up our variables so that title equals the instance of ‘title’.
Title is something that WordPress has created a filter for. WordPress allows you to filter a widget title from someplace outside of the widget itself. So you could put your custom functions.php file to change the widget title somewhat. We’re going to allow that filter to be used here so that this ability to change the widget title exists inside of our widget.
Essentially, apply_filter means apply the widget title filter to this instance of the title is what that code says. Then our message is going to be equal to the instance of ‘message’. In fact, let’s just copy this again and we’re going to say, $show_title = $instance[‘show_title’]. So we’ve got all those parts.
Write Output HTML
Now that we’ve set up our output variables, we’re going to write our output HTML. Writing our output HTML is pretty simple. It starts off with echo $before_widget. Now before_widget is one of these arguments, before_widget, before_title, after_widget, after_title are the arguments that are extracted here under $args.
Let’s just take a look at these sidebars here for a second. If we go to child theme, functions and look at our sidebars, here when we register our sidebars, we specified before_widget say this, after_widget say this, before_title say this and after_title say this.
Remember when we discuss this, we talked about this placeholders for widget class and widget ID. What happens here then is, this set of $args, are those four things, before_widget, after_widget, before_title and after_title. What happens is it takes these unique IDs and classes that we’ve specified up above and inserts them into that before_widget and does the same thing in the before_title.
Anyway, we echo before_widget which is the argument that was extracted here. Then we say, if there is a title, so if somebody has entered something in the title, then we’ll echo $before_title then the variable $title then after_title and below that, we’ll add a bit of HTML. We’ll wrap this in a div and wrap the message in a p tag. We’ll echo a div and a p tag then we’ll echo our message and echo our closing p and div tags then we close it out and say echo $after_widget.
There’s one other thing here though and that is, at the moment, we aren’t using our show_title variable, we’re just saying if there is a title here, echo the title. But what we really want to do is say, if there is a title && $show_title. So if there is a title and if show_title has been checked, then echo $before_title, $title and $after_title. If there is no title, then it’s not going to do it and if show_title hasn’t been checked, it’s not going to do it.
I suppose you could say in this case, you could do the same thing, if($message) then show this information. This probably not really necessary but you could do that as well so hit save. Am I on the right spot? Thesis responsive, library then we’re going to go down to widgets, upload the file, refresh that. Let’s see wp-admin then come over to our widgets and look for our widget. Actually, we’re not going to see our widget. Our widget doesn’t show up here yet because we’ve only done one part of this.
The reason why that’s not there is because we haven’t registered this widget and we also haven’t included the file in our child theme. That’s the next thing we’re going to do, we’re going to register this widget. We could register the widget here. We don’t necessarily have to register the widget any place special. It could theoretically be registered here. Let’s just come over to our widgets API and look at our register_widget.
Register the Widget
In this case, register_widget just takes the name of the My_Widget. We could come along here and just say, register_widget then make sure we’ve got the right widget name in here and do that. However, it’s not really what I want to do. What I really want to do is put all my registration in a separate file.
Now you’re not going to do this if you’re creating this in your custom_functions.php file. If you’re not building a child theme, ignore this part of it now but because we are building a child theme, we’re going to actually create function to register all of our widgets at the same time.
In that case, we’re going to create a new file and we’re just going to call it, crtc_widgets. In this, we’re going to create a function crtc_register_childtheme_widgets then what we’ll do is come back over to our CRTC_Example_Widget and take this widget registration out of there and put in here.
As we work our way through this process, we’re going to add more things to this so we’ll have more widgets to register. We’re going to do that and we’re going to grab this name of this function and come over to our loop, crtc_loop.php. Remember, we created this function called fishsticks inside the loop? Again, it is created exactly the same way as we just created our other class and we said run the widgets init.
The action that we’re going to run at widgets_init our fishsticks function and fishsticks function registers our sidebars while we’re also going to register our widgets. So register_sidebars, register_widgets is happening inside of function fishsticks which is being called inside of our constructor.
This is that Thesis Custom Loop API constructor that exists inside that template. We’re going to save that, come back over here and look for a second at what $instance[‘message], right, absolutely right. There is no $ sign there because it’s the name of the option, not a variable. So we’ll save.
Include Files in Include Path
We have to do one other thing and that is include these two files in our include path. If we come over here to our functions.php file and we look at this for a moment, we’ve defined these constants. We’re going to define a new constant and it’s going to be CRTC_WIDGETS then it’s going to go to CRTC_LIB and /widgets.
Now, we’ve defined the path of that widgets folder and we’re going to include these files in our include path so include_once, not CRTC_FUNCTIONS but CRTC_WIDGETS, the actual name of the files, we’re going to include our crtc_widgets.php and then the new widget file which is crtc_example_widget.php.
That’s all of the pieces of the puzzle that are necessary in order to bring this widget into fruition. We’re going to save that and open this up in Filezilla. I think the easiest thing for me to do at this point is simply to upload the functions and we’ll upload the lib and that gets everything up there.
Now, when we look in this, here’s our Example Text Widget and we can drag it over here to Sidebar 1. Here’s our form, here’s our widget title, “Here’s our title”. Look, I didn’t change label for this variable so the label is still label for this variable rather than enter some text. Display the widget title then “Here is some text that we will display”. Hit save, come back over and go to a page that has that on it. So “Here’s our title” and “Here is some text that we will display”.
Notice how it didn’t save that checkbox? It didn’t save that checkbox because of that checked function I’m going to talk about here in a minute. If we save it again, it’s saving the fact that it’s not being checked so we come back over here and refresh it and now the title is not going to show, only the text is going to show.