Now that we’ve done that minimal amount of preparation, we’re going to take a look at the Thesis Box class with a brief introduction to the Thesis Box Class. Now, there’s going to be a zip file for you on the resources section of this lesson when I get up that will have 2 example boxes in it. These example boxes were written by the Thesis 2 development team for developers to use as reference to understand how to write their own boxes.
Creating a Simple Box
One of the boxes in that is the simple box and we’re going to start off with this simple box as our starting place for writing a box. The kind of box we are writing is different from the one you’ve seen me describe before. If you’ve watched the Thesis 2 Technical Review videos, you’ll note that when I talk about creating a box, I do talk about creating a box.php file then having this header in it and that kind of stuff.
These boxes are going to be included with the skin so they’re going to be referenced differently and in particular, they don’t have a header like this. We just start this off by just coming in and we’re going to copy the whole thing. I’m going to come over to lesson_5_responsive_blue_masters, open up the library, open up boxes. And you can see there’s no box in there so I’m just going to create a new file called, Box and inside this file, I’m going to place every box I create.
What a Box is Comprised Of
I’m just going to delete this and paste what we just copied out of that other sample box. Now, a box consists at a minimum of a unique class name, a title inside of a translate function. The purpose for the translate function is if somebody wants to add a translation file to allow your skin to be translated into French or German or something else, it’ll use this function here to translate the title. In minimum, you need a class name, a translate function with the title and some kind of HTML.
The HTML is the output, it’s what ultimately gets written when the box is placed inside of template so we’re going to start there actually. We’re going to come to here and delete anything that’s not absolutely necessary.
The Use of a Unique Identifier
We’re going to start off by giving ourselves a unique class name and I always start with the unique identifier which in this case, is Thesis Responsive Blue Masters so trbm and I’m just going to call this Sample Box. You would recognize that trbm from when we created the path.
Sample Box Code
So trbm_sample_box extends thesis box and in the title, I’m just going to say, Sample Box then note here that it says, custom_text_domain. Now, we’re going to replace that custom text domain with our own custom text domain which in this case, is just the unique identifier, trbm. So Thesis title = __(‘Sample Box’, ‘trbm’); and what I’m going to do here is echo ‘Hello World; okay.
What this is going to do is, it’s going to create a box inside of our skin and you’ll be able to click on that box and drag it some place and wherever you drag that box to, it’s going to print out ‘Hello World’. That’s a very simple expression of what a box can do here. Once we’ve done that, we need to make reference to that box here in our skin file.
Defining an Array
The way we do that is to begin by defining an array of the boxes that we’re adding. In this case, we’re only adding one box. So we’ll say public then $boxes_class_list then = array and at the moment, it’s just going to have one and we’re going to call that the name of this box which was trb_sample_box. This is now a variable that can be used anywhere inside of our class and that variable contains an array with one element in it.
Create Function to Add the Boxes
The next thing we need to do is create a function that will take this and add it to the list of boxes that Thesis is using. So we’re going to create a new function called add_boxes. Now, this function is going to be attached to the Thesis Boxes Filter that has a variable called boxes so we’re going to place that variable inside of the parenthesis here as a parameter.
Requiring a File
Then we need to require our box file, we need to make reference to the box file then we want to merge the boxes array that Thesis creates with our own array which is our new $box_class_list. The first thing we’re going to do is just require this file so we’re going to require_once then we’re going to use this constant here so we’re going to require_once that constant.
Remember our box.php is inside of boxes which is inside of lib so we’re going to say /lib/boxes/box.php so there’s the file that is requiring this file now. That’s the way in which sometimes we say, include this time – I want it to fail if it’s not there so I’m saying, require. I could just as easily say require_include_once if I wished.
Then I’m going to use a function called array_merge and I’m going to use a Thesis 2 convention here. Rather than assigning this array to a variable then returning that variable, they’re just returning the array itself so return array_merge. Array merge takes the target array or I guess it takes the destination array, the array you want to merge into and the array you want to merge.
In this case, the array we want to merge into is $boxes and the array we want to merge in there is this variable. Now, the way you reference the variable and a class like this is to say, $this variable so $this->boxes_class_list. So array_merge of $boxes with $this->boxes_class_list so essentially what’s it’s going to do is add trbm_sample_box to the $boxes array and this isn’t quite enough for us because all we have to do now is take this function and add it to the Thesis Boxes filter.
Adding a Filter
Just like our actions were happening up here, so will our add filters . Say, add_filter then the name of the filter which is thesis_boxes then the name of our function. The way you reference a function here is rather than just giving the function name, what you say is, array. Then inside the array we’ll say, $this then the name of our function which is add_boxes. Because we are using object oriented programming here in Thesis 2, the syntax looks different than it used to.
Which Syntax to Use
It used to be when you added an action, wp_head then the function name and added a filter thesis_boxes then the function name. Now, when you’re doing this inside of a class, what you do is make reference to $this then head_scripts, $this then add_boxes. The simple function name now becomes an array with the first element of the array being the designator $this and the second element of the array being the function name.
Now, if this function name is not inside the class, then you would use an ordinary system. You would just say, $this, ‘head_scripts’ if head scripts was not inside the class. That’s probably just confusing the situation but when referencing in an add_action or add_filter, when referencing a function inside of the class, you use this syntax. And when referencing a function outside of the class, you use the syntax you’re already familiar with, the typical syntax.
We have succeeded here in adding our image size, we’ve added a filter, thesis_boxes and that thesis_boxes is taking this list and merging it in with the Thesis boxes list. We should be able to save this document, open up FileZilla and upload those files.
Go down to wp-content, thesis, skins, lesson_5 then library and boxes. You can see there’s no box over here so we’ll just upload the box and we’re also going to have to upload the skin file because the skin file is different so we’ll upload our skin file, overwrite it.
Come here and refresh this and now, that sample box should show up here; it’s right here. The sample box, because the way we constructed it, it showed up here not inside this list. If we come over to our featured box area now and just drag our sample box over, save the template, we should right in the middle of this some place, have ‘Hello World’, there it is.
There is ‘Hello World’ and that showed up because of where we placed that box. We could just as easily take that box and put it in Header Area Page, save the template and now it’s up here in the top instead. That’s the down and dirty simple version of this where we can add a very simple box to a skin.