In part 1 of our series on “Searching the WordPress Codex Effectively,” we went over some of the most common structures in WP functions – knowing these structures will help you when searching and using them from the Codex.
Now, what if you have found what you’re looking for in the Codex, copied and pasted the line of PHP from beneath the “Usage” section, and it’s still not working? And what are all these strange things between the parenthesis and under the “Parameters” section – why doesn’t it just work!?
We’ve all been there; strapped for time, don’t want to sift through numerous sources to delve into all the complexities of PHP – you just want to paste something in and for magic to happen so you can get on with your life. The good news is, the more you use the Codex and tinker in your template files, the more you will begin to learn how WordPress (and PHP) work.
What each Codex section entails
To start, let’s use the_date(); from the Codex.
Most of the Function Reference pages are arranged with a few sections you should pay attention to: Description, Usage, Parameters, and Examples. There are other sections here, but for now, let’s just master these four as you will be jumping into them a lot during your WordPress endeavors.
Keep in mind that this article is assuming that WordPress.org doesn’t change their Codex layout anytime soon. Here’s a screenshot below to show what the current Codex looks like in the event that it ever changes in the future.
1. Description:
This section tells you what it does. It also includes any important notes you need to know, like whether or not it’s deprecated (no longer supported) or if it needs to be in the loop to work. So if you’re copying and pasting the code into your file and it’s not working, this is the first place you want to check in the Codex to ensure that you’re aware of any warnings and using it as intended.
For the_date(); function, it will display or return the date that the post was published. There’s also a special note about how this function works versus get_the_date.
2. Usage:
This is what the function looks like and you can usually copy and paste into your template. However, if the function appears like the_date(); does, and has variables in it (e.g. $format, $before, $after, $echo aka stuff inside the parenthesis ), then it may or may not work as is.
Luckily for us, the_date(); will work in the loop without anything in the parenthesis, but that won’t always be the case with other functions. That’s what the following section, Parameters, entails. Let’s take a look and see what might be missing and how far we can go with this function.
3. Parameters:
This is where the bells and whistles for a function is. You can find out what’s mandatory for the function to work and what options you have available to make the most of the function. You can think of parameters as the pieces needed to build or properly display what the function does.
Let’s see what the parameters for the_date(); looks like.
What’s pictured above is this:
- $format – this is just a stand-in on the Codex to show you where your parameters should be placed. If you leave in the variables as if you just copied from the Usage section, it will ignore the variables in there because it’s already doing its default functionality – unless one of those parameters are required.
- (string)(optional) – This is the type of data it accepts, more about that here. And whether or not this needs to be filled in for the function to work.
- Default – This tells you what the default value is. If you’re okay with default, then no need to fill anything in here.
Still a bit unclear?
Another way to understand it is this: Imagine there’s a function that builds a bike (Magic, remember?) and in order for the bike to magically appear in your driveway, you need to provide it with some information or it won’t know what to do. “Function, I want my bike, what do you want from me?”
Well, the bike function has four parameters. Color, size, tires, marathon.
my_bike( $color, $size, $tires, $marathon );
If my_bike had a Codex Parameters section under Usage, it would look like this:
$color
(string) (optional) The color of your bike. Only red, blue, orange, white, and black accepted.
Default: red
$size
(string) (optional) What size bike this is. Only adult and child for this.
Default: adult
$tires
(string) (required) What kind of tires are on this bike? We need to know in order to build our magical bike, so if this is not provided, the function my_bike will fail – after all, what good is a bike without tires? Your options are cool tires, awesome tires, and super tires (I obviously know nothing about bikes.)
Default: None – this says none because there will never be fallback value for this, since this is a required parameter, this is something you must fill in and therefore doesn’t need a default.
$marathon
(boolean) (optional) Is the bike for marathoning? If it is, set to TRUE as in yes, it’s true that I want to use my bike for marathons. Defaults to False, as in no, I want a non-marathon bike.
Default: FALSE
Hopefully this example gives you a bit more understanding on parameters and why those are important in a function. The great thing about the Codex is, if sometimes the parameters are still a bit unclear, the Examples section will show you how to put the function in use.
4. Examples:
After reviewing the Description, the Usage, and the Parameters of a function, if things are still a bit fuzzy, the Examples section shows how to get that function in action. The Examples are also a great way to see the most common uses for a function.
Conclusion
At this point, including this article and it’s predecessor, we’ve learned how to effectively search the Codex for functions and what all the jargon on a Codex page is, section by section. Without having to dive too deep into PHP, we’ve also picked up some basics like using echo with ‘get’ functions as well as function parameters.
Hopefully, this makes the process of using the Codex for your templating adventures seem just a bit more magical – or at the very least, aids in getting the job done quicker so that you could head on off to the beach.
If that bike analogy for parameters was really helpful – you can download a handy Codex imitation image here. Have a happy summer!
