So let’s talk about the Thesis 2 way for customizing PHP, the Box API. The fundamental concept that underlies the Thesis 2 box API is that by using it, you are creating repeatable user configurable code.
Creating Repeatable User Configurable Code
This code can be used over and over and over again in many different conditions throughout the site and users can easily make changes to it. They can easily set conditions, they can set options and they can make changes from easily created sets of options.
Using the Thesis Developer Documentation
I would like to draw your attention again, back to the seminar page. The Thesis Developer Documentation is kind of hidden. If you’re on the site, the way you get to it is by going to the Developers section and then there’s a link to the API there.
You can also just get to it from the resources and Chris has done a lot of work on the API documentation. There’s still some stuff that needs to be done yet but he’s done a lot of it. We’re going to be spending a bunch of our time in the box API here today and a little bit of time in the options API.
This box API is not really intended for beginner programmers, it’s not necessarily a self-explanatory as I hope this is. But a reasonably experienced programmer can read this API documentation and figure it out pretty well. I found it to be very useful.
When I first entered programming in 2.1 none of this documentation was available and I spent all my time practicing and playing with 2.1 trying to figure out what it did and now we’ve got the API documentation to help us figure it out.
Create a New Box
Let’s create a new box and I’m going to start inside of my wp-content, thesis, boxes folder. First we create a new folder and we’ll call it byob-custom-excerpt. So that’s the name of the folder.
Inside that folder needs to be a file and that file must be named box.php. It can’t be named anything else, it needs to be named box.php. And inside of box.php you need to start off with a header. We’re just going to take the example header from this other box that I created for you and I’m just going to draw your attention there for a second here.
BYOB Simple Sample Box
This BYOB Simple Sample Box essentially is a box that shows you example code and how that code shows up in various options. It’s a kind of a skeleton box. It doesn’t really do anything, it just throws you various options and various formats. But I think you will find it useful as a starting place for creating boxes or as a sample for you to refresh your memory on how some of the options work.
Specific Header Requirements
We’ll go ahead and open up that box now, Simple Sample Box. It starts off with this header and the header has some very specific points. First, it has name colon and the name of the box and in this case, the name of the box is going to be BYOB Custom Excerpt.
This name is the name that shows up in the Manage Boxes menu. And then the author name and then the version number.
This version number also shows up there but is also used by those of us who have automatic update systems. Our automatic update systems go out and check the version number of the boxes that we create and then test against whether or not there’s an update and if there is, it tells you so. It does that based on this version number. All of DIY themes stuff has that same kind of thing going on. This automatic update process is based on this version.
Then you have a description and this description also shows up the Manage Boxes section and we’re going to say, “This box gives the user the chance to set the length of the excerpt and customize a “Read More” link.”.
Then we have a class name. This class has to be unique, right? There can’t be two boxes in the same website with the same class name so it has to be unique. I’m calling it custom_excerpt and that’s the name of the class.
So this is the required content of the header, name, author, version, description and class. If you’re missing any of that, it’s not going to work properly, it’s looking for those things specifically.
Now with that, it’s also looking for the class and I do believe that Chris has an example of that here. So it says the very beginning of this then is this class, my_box_class_name extends thesis box. Let’s copy this, we’ll come back over to our box and paste that. So my_box_class_name extends thesis box and you have to replace my_box class name with this class.
Creating New Boxes from an Existing One
I almost never write boxes from scratch. I almost always create a box from a copy of another box. I routinely forget to change these to make them exactly the same. If you fail to make these the same, it’s going to show up and it’s going to install just fine but none of the settings will show up right. So you have to make sure that the class that’s described here is the same as this class here.
Now, the purpose for this is not really to teach you about object-oriented programming, I’m just teaching you the structure that has to go there. But we are in fact, using object oriented programming in this system where we declare a class, we declare that class extends another class and then we use methods and properties and stuff like that for doing this.
We’ll talk about object oriented programming some other time, really all you really need to know is this is the syntax that needs to be used in order for this to work and it’s a little bit different than the typical procedural syntax that you’re familiar with.
Core Properties and Core Methods
So there’s our header, here’s our class and then you have things that are called core properties and core methods. And again, we’ve got core box properties and our core box properties that we care about today. Those are the box type and the box title and the box name. There are other potential properties as well but none of those really fit into this conversation in an introductory format, they’re all more extensive, more complex use cases.
So, a box property is something that the box is looking for that it’s going to use and the first core box property is type. The type is the kind of functionality of the box and there are 3 box properties.
There is box which essentially is a content element. That is, it will display some kind of content either from your site or from your database or from your page or your post. The type box usually displays some kind of content.
The second type is rotator and that usually contains something else. So you can drag other boxes into it.
And then type=false is the kind of box that doesn’t result in a box that shows up in the Skin Editor, it results in a box that does something. So you install it and it does something but it doesn’t necessarily create a box that you can manipulate inside the Skin Editor.
Now, if you don’t include a public $type then box is assumed and we are going to be public $type = ‘ box’; because we’re doing the excerpt. We don’t need to drag anything into the excerpt. This box doesn’t need to contain anything. Excerpt is a kind of content so that makes the most sense, public $type = ‘box’.
The next two core properties are title and name. Now, these properties are set inside of the translate function. So what we’re going to do is copy this and come back over here and just add a space and then paste it. Okay, protected function translate.