The next thing we’re going to talk about is WordPress Constants and WordPress File Locations. A constant is essentially an alias for the address of a file. When you are creating plugins or creating themes, you run into this issue where obviously, you need the plugin or the theme to be portable so you can’t hard code references to where files are.
Make Code Easily Edited, Efficient and Portable
You can’t say, you’ve got to go look in thesisresponsive.com/wp-content/plugins. You can’t use absolute file locations because you’ll be using them in different domains and every domain has a different address for those files and you need a way of having relative file names.
WordPress and PHP give you the ability to define constants that you can use for assigning an alias to the address of a file. You use this so that you can move from site to site but you also use it so that your code is more modular and it allows you to change file locations without having to change a whole bunch of code. That’s why we use constants in order to be able to make the code easily edited, efficient and portable.
WordPress Ways of Referencing Constants
WordPress has 3 ways of referencing constants. If you start looking around, you’ll see that there are different expressed opinions on how to use them. There are different ways people use them and there are articles about them that are antique and no longer valid. The most recent best information is not well documented and that’s why we’re going to have a long conversation about this because it used to be that the WordPress defined constants were the only way for you to get the address of a particular file.
There were 2 WordPress define constants and they are TEMPLATEPATH and STYLESHEETPATH. If we come over and take a look at our functions.php file that we have, notice that this is the file that we copied from DIY themes, from their starter template. You can see here that he is using this TEMPLATEPATH, that’s the WordPress constant for the address of the parent theme’s root directory.
Difference Between STYLESHEETPATH and TEMPLATEPATH
STYLESHEETPATH is the reference to the current theme stylesheet location. The difference between that and TEMPLATEPATH is that TEMPLATEPATH will always take you to the parents directory and STYLESHEETPATH will take you either to the parent or to the child if there’s a child theme that’s been activated.
TEMPLATEPATH applies to parent themes or themes that don’t have child themes and STYLESHEETPATH applies to child themes or themes that don’t have child themes. Generally, when we’re talking about child themes, you’re looking at either TEMPLATEPATH for the parent or STYLESHEETPATH for the child theme. That’s the WordPress constant.
WordPress doesn’t really want you to use these and the reason is that they can’t be overwritten by the parent theme or the child theme. They are absolute constants that can’t be changed and WordPress thinks there’s a value in those things being able to change. Also, TEMPLATEPATH and STYLESHEETPATH refer to the absolute local path of a file whereas sometimes, you want the absolute http path of a file.
WordPress Sets of Defined Constants
Once WordPress figured out that people are going to want absolute http paths for files too rather than just a local path, they came up with this thing called, “get_bloginfo” and they added the theme URI as a value in get_bloginfo. That’s the second set of WordPress defined constants.
You have the first set which are the TEMPLATEPATH and STYLESHEETPATH and the second one is get_bloginfo. Well, get_bloginfo also only does one thing and that is return the absolute http path and it also ends up getting part of its address from the same settings that TEMPLATEPATH gets it from.
New WordPress Set of Ways of Defining Constants
WordPress with 3.1, I believe, came out with a new set of ways of addressing and defining constants. Those are the getDirectory paths and you have 4 of them. You have get_template_directory, get_template_directory_uri, get_stylesheet_directory, get_stylesheet_directory_uri. Those four things are very poorly documented and so there’s still a lot of confusion in the theme writing community about which of those should be used and when they should be used.
We’ll Use the Current WordPress Standard
I’m going to show you examples of using them as we go through this but we are not going to use TEMPLATEPATH or STYLESHEETPATH and we’re not going to use get_bloginfo. We are going to use the current state of the art WordPress standard which is get_template_directory, get_template_directory_uri, get_stylesheet_directory, get_stylesheet_directory_uri.
I have links to articles about those in the lesson so you can see here we’ve got, get_template_directory, get_template_directory_uri, get_stylesheet_directory and get_stylesheet_directory_uri. If you’re going to start by reading these, you want to start reading this one first, get_stylesheet_directory_uri and the reason is, this is the one that has the most thorough explanation of what to use especially in the context of a child theme.
WordPress Codex Articles
Essentially, it’s saying that if you need the http path of a file, and that usually happens if you’re going onto a page someplace, you would use this get_template_directory_uri and if you need the path for including files, folders and functions then you would use the get_stylesheet_directory without using get_stylesheet_directory_uri.
There are no other articles in the codex that make this distinction or that explains this. This is a weakness in the codex that I’m sure will get developed and fixed at some point but currently, the only place for you to get a definitive answer on this is either in theme developer’s conversations in the development site of WordPress or there are a couple of reasonably decent answers on the WordPress forum about it. But there’s so much conflicting information that I suggest you just take what I’m saying as the current gospel and you’ll probably be just fine.
Thesis does not do what I’m suggesting that we should do. If we look at the way Thesis handles this, we look at Thesis functions.php, Thesis uses TEMPLATEPATH, Thesis uses STYLESHEETPATH and Thesis uses get_bloginfo, it uses the 2 older systems. We are not going to follow that standard, we are going to instead use the current WordPress standard which is get_stylesheet_directory and get_template_directory.
Creating Constant Definitions
Now that I’ve talked about that, we want to define some constants. I’m going to show you an example of a constant definition. Here in Thesis functions.php, they have defined THESIS_LIB as being TEMPLATEPATH. ‘/lib’. Now, when they want to reference a file that’s in this library directory, they use THESIS_LIB plus the name of the file and that’s what we’re going to do here as well, we’re going to create these kinds of constants.
If we go to our functions file here, we’re going to use the PHP function called “define” for defining our constants. The PHP function “define” defines the name of a constant and the first parameter that we give it is the name that’s being defined and the second parameter is essentially the address that name is being associated with.
Defining the Child Theme Directory Location
In this case, what we’re going to start off by doing is defining the child theme directory location so we’re going to say, “define” and the thing we’re going to define is, Create a Responsive Child Theme or CRTC, that’s my unique identifier, create, path and we’re going to use get_stylesheet_directory so, define (‘CRTC_PATH’, get_stylesheet_directory());.
We’ve taken get_stylesheet_directory which is going to return the absolute local path to our child theme and it’s going to store that in this definition (‘CRTC_PATH’. We want to do the same thing with our library folder so we’re going to define (‘CRTC_LIB’ then we’re going to use the definition above, CRTC_PATH so the path to the CRTC_LIB is going to be CRTC_PATH so, define (‘CTRC_LIB’, CRTC_PATH . ‘/lib’);.
We have our first constant, CRTC_PATH and that is essentially the same thing as get_stylesheet_directory then we’re going to define CRTC_LIB as a relative to CRTC_PATH so CRTC_LIB is going to be CRTC_PATH . ‘/lib’.
And we’ll do this one more time with functions, define (‘CTRC_FUNCTIONS’, CRTC_LIB . ‘/functions’);. Can you see the pattern here? This CRTC_FUNCTIONS build on CRTC_LIB, CRTC_LIB builds on CRTC_PATH. We’ll do that one more time with classes, define (‘CRTC_CLASSES’, CRTC_LIB . ‘/functions’);.
Use of Constants for Including Files
We have now defined four constants. We’ll be defining more constants as we go through this but we have now defined four. Once we have defined those constants, we can use these constants in including files because it’s one thing to have a file structure where you’ve got lib, admin, classes, css, and functions. Now once you’ve put files in here, we need to include them, that we need to tell WordPress to use those files and so we have include statements just like this one where we are going to include our own files and we’ll use these constants in that definition.
Ultimately, what that does is it makes it easier on us to change things. For example, if we want to change any of this to library, the only thing we have to do is change this to library and everything that referenced functions and classes would now automatically reference to library instead of lib. That’s the way that works.
Now, we’re going to fix the include statement here that came with the starter template by rather than using TEMPLATEPATH, we’re going to use get_template_directory. We’re using the current WordPress way, include_once(get_template_directory() . ‘/functions.php’); and we defined these things as our path constants for these other directories.
As we start creating files then, we’ll use these to include those files. That will become more obvious here in just a few minutes. In fact, what we’re going to do here is go up a level and upload this whole theme now to the site since we’ve added some changes, we’ll just replace everything with the new. Just to make sure that it’s working properly, come back over here and hit Save, come back over to home, there we go.
We made those changes and it still looks exactly like it did before. It should look exactly like it did before since we’ve just changed the way in which our child theme references WordPress files and references Thesis.