Now that we’ve covered the Thesis 2.1 way for customizing PHP, the Box API, we’re going to create a simple ‘Hello World’ box. We’ll just work in this byob custom excerpt box that we’ve been looking at so far.
Customize an Existing Box for Hello World Box
We’ll name it BYOB Hello World and we’ll give it a class of byob_hello_world. And then let’s go to that box name, custom-excerpt, in the file structure and we’re going to change that to hello-world. So I’m going to say ‘Hello World Title’ as its title.
The Name of the Box
We’re going to come back to the name in just a moment but this shows up all kinds of places. It shows up inside the Skin Editor specifically. So we need to give it a title and this little thing here is for translation. We could just say $this->title = (‘Hello World Title’) but we don’t want to do that because we want people to be able to come along and put it in a Portuguese or Romanian or whatever.
So what we’re using is this WordPress translation function which essentially tells WordPress that if there’s a text domain loaded for this, that anything that’s contained inside of a double underscore (__) plus parenthesis, it’ll translate this first piece of text based on this text domain. Now, that’s kind of beyond the scope of this conversation but everything we do that could be translated, we’re going to do it this way rather than just doing it in straight English.
Core Methods and Properties
Then you have core methods and core properties which we said are Type, Title and Name. The first of the core methods we’re using is translate. Then really for the time being the only other core method we are going to use is HTML.
HTML is the place where whatever HTML you create gets output. You don’t to say where it’s going to be output because the box is dragged to the location where it should be output. So you don’t have to place it at a hook or anything like that. Thesis automatically notes the specific location of this box and then outputs this HTML at that location.
Types of Box Options
Then there’s one final thing and that is box options. Box options are the places in the box where you can set options and there are 3 specific types of options that we’re going to look at.
There are HTML options, there are box options and there are template options. There are a few other types of options as well. If we look at our sample box, here’s our translate function. These are other functions that we’re not actually using today but are the construct and the preload function.
Here’s an example of class options. This results in options that are added to the boxes menu. This is the box options and it results in options that are written to the Skin Content menu. And then HTML options and it results in options that are written to the specific box itself in the Skin Editor.
So you have these in this case, 3 different types of options. There are more types of options like I said but these are the ones that are in this simple version and we’re going to leave it at that here for today.
And then you have your function HTML which is the function that creates the content or that displays the specific HTML and the content that you want to display.
Add HTML Function to the Box
So now we’re going to go back to our example #3 which is our ‘Hello World’ box. So we created our box and it’s public type box. We have our first function in here which is translate and the only other thing we need to do is place an HTML function here.
So what we’re going to do is copy his HTML function right here I’m going to talk more about $args = array and extract($args) and so on and so forth. But suffice it to say that every HTML function you create should have this stuff in it. It shouldn’t be just html, it should be html($args = array) like that and then extract($args) and you’ll see why in a few minutes but this is our sort of bare bones HTML function.
Here’s where we would simply say, echo “Hello World”. So that’s a very simple box. This is going to place “Hello World” in fact, that’s what I should say, “This box places “Hello World” any place the box is located.”.
Upload the Box
Let’s hit save to that and bring my FileZilla up here. Go over to boxes and then I can just take this box and upload it like this, right? This is the manual installation method. We could have zipped it up and uploaded it and so on and so forth but since we’re programming it from here, we’re just using the manual upload method. Essentially it’s just copying it to our boxes menu and our boxes directory.
Let’s come back over here to the Skin Editor and go to our Boxes. Here’s our BYOB Hello World, “This box places “Hello World” any place the box is located”. Go ahead and click on that and hit save boxes and then go to my Skin Editor.
Add the Box to Specific Area on a Template
I can create a new Hello World box, notice it says Hello World Title here, I can create a new one of these. And let’s just put it above the headline area in the Home page right there. So there are no options for me to change, it just says Hello World Title here.
Now that I’ve got that, I don’t have the choice of putting another one in, right? I can only put one of these in a single template, I can’t put more than one in with the way it’s comprised. But if I hit save template and then come on over to the Home page, Hello World has been added before the rest of the content, it’s there the way we want it.
The beauty of the box is that this Hello World isn’t anywhere else. It’s definitely not on the Home page or the Front page because it’s not added to the Front page template. So I don’t need any of that conditional language to control where it goes. I don’t need to say well if it’s the Front page, don’t show it or if it’s the Home page, show it.
All I have to do is drag the box into the location and if I wanted it to show up on the Front page, then I open up the Front page template and I add it to the template. So again, down to Hello World Title, add the box and then drag it down here to the Content column. Save the template and now, on the Front page, it actually does exist and there it is, it says Hello World.
This is the power of the box, now I can drag it anywhere I want it. I don’t need any further language necessary in order for me to place it anywhere on any template or to exclude it from any template. It just automatically happens because of the box.
Creating a Multi-Instance of the Box
Now, if I want to make a multi-instance of this box, then I need to add the name. So I’m going to copy the title and instead of this title, say $this->name and let’s change ‘Hello World Title’ to ‘Hello World Name’. So you can see the different places this shows up. Save it, upload it and now, presto change-o now ‘Hello World Title’ is blue.
Notice it said “Hello World Title” in here but “Hello World Name” here? This means I can put it anywhere I want. So ‘Howdy’ and I can create as many instances of it as I want. So Content Column and let’s just do another one, Hello World Title. Add it and I can take it and drag it down say into the Footer. Save the template and now on my Home page, I’ve got Hello World up there and I’ve got Hello World down here.
So, simply by adding the name, when you add the name to the box, gives you the ability to have multiple instances of the box. And that’s the only thing you have to do in order to make multi instances of the box.