How to Write and Activate a Function in WordPress
If you’re starting out developing your own WordPress plugins, or you’re creating your own themes, a skill you’ll need to learn is writing functions.
Maybe you’ve written a function which didn’t work and you’ve given up in frustration. Or maybe you’re confused by action and filter hooks and you’re not sure how to get your function to work.
In this post, I’ll help you get past any teething problems with writing functions. I’ll show you how to structure your function, give you best practice tips, and clarify the methods you can use to activate your function.
So let’s get started!
- What You’ll Need
- Where Should You Put Your Function?
- Writing Your Function
- Activating a Function
What You’ll Need
To follow along with this tutorial, it’s helpful if you have a function you’re already working on. That way you can put what you learn into practice and you’ll get more from it. In which case, you’ll need some tools:
- A code editor
- A development installation of WordPress
- The file for your function – which could be in your theme’s functions.php file or could be in a plugin.
If you don’t have that because you haven’t started on your function yet, don’t worry – read on and you’ll learn how to get started.
Where Should You Put Your Function?
Before starting, you need to consider where you’re going to put the code for your function. You have two choices: your theme functions file or a plugin.
Which you use will depend on the purpose of your function:
- If it’s related to the design and display of your content, then put it in your theme. It’s directly related to the theme and will only work alongside the rest of the theme’s code.
- If it’s functional (and most functions are, the clue is in the name), then put it in a plugin.
Many of us start out in our functions file as that’s easier, then we move on to creating plugins when we’ve gained confidence. Creating a plugin is actually very simple – check out our guide to creating plugins.
If you’re confident that your plugin should be in the theme functions file and your theme doesn’t already have one, then see our ultimate guide to the functions file.
Writing Your Function
So, now you’ve got your file open (either functions.php or your plugin file) and you’re ready to write that function. Let’s break it down into parts.
I know what you’re thinking: comments, can’t we just get on and write some code already? But I always add comments before coding my plugin. This way, I can see what my function is for when I go back to it. Sometimes I don’t need to go back to a piece of code for years, and trust me, I’ll have forgotten how that code worked when I do! And if anyone else ever needs to work on your function, the comments will help them understand what it does.
My function is going to be a simple one to register a couple of Google fonts in my theme. It’s going in the theme functions file because it is related to display and not layout. But first I’ll add some comments:
I format my comments like this so they’re clear and easy to find when I’m quickly scrolling through the file at a later date.
Opening The Function
Now it’s time to write the function. You open it with the word
function and the name of the function. You should always use a prefix to your function name to help ensure that its name is unique. That way it won’t clash with any functions in your theme or any third party plugins. Use your name, your initials, or the name or initials of the site or plugin you’re writing the code for.
You follow this with curly braces, within which the code for your theme goes:
Populating The Function
All of the code which you want the function to run goes inside the braces. This includes any conditional tags, which I’ll explain in more detail later on. Here’s my code for my google fonts function:
I’m not going to teach you how to code a specific function here, as that will depend on what you’re trying to achieve. We’ve got plenty of other posts which will help you with a variety of functions – not to mention our Academy courses on WordPress development!
Here’s the full function:
But once you’ve done that, you might open a page in your site and wonder why nothing’s happening. That’s because you haven’t activated your function yet.
Activating a Function
A function is useless unless you activate it in some way, telling WordPress when to fire the function. You have three options for this:
- Code the function directly into your theme template file (or another plugin file).
- Attach it to an action hook.
- Attach it to a filter hook.
Let’s look at each of these.
Coding the Function into Your Theme Template File
This option is only available to you if you’re working with your own theme.
If you want to do it with a third party theme, you’ll have to create a child theme, duplicate the relevant theme template file from the parent theme in your child theme, and add your function to that. If the template file is changed by a future update of the parent theme, your child theme file (which WordPress will use) won’t reflect that.
I’m going to assume that you’re working with a theme you’ve developed yourself, and you have a snippet of code that you want to repeat in multiple template files. Instead of creating an include file and calling it in those files, you’ve decided to use your functions file and create a function – which for a snippet of code is more efficient.
Let’s imagine your function echoes out the date. Here it is:
Now, to add this code to your theme, you would add this to your theme template file, in the place where you want the code to run:
Simple as that! You simply add this code to the relevant template file in your theme.
Firing Your Function Via an Action Hook
An alternative is using an action hook. This is code which allows you to run code attached to it, every time WordPress encounters the hook.
You can either use hooks already provided by WordPress, or you can create your own.
In the case of the fonts function I wrote above, you’d use a hook provided by WordPress: the
wp_enqueue_scripts hook. So to fire my function I’d add this outside the braces:
So my full function will look like this:
Now let’s look at an example where I could write my own hook. Instead of coding my function to output the date directly into my theme template file (in this case the loop), I use
do_action() to add an action hook, then hook my function to that.
So in my template file I add this:
Then I attach my function to that, so the whole thing reads:
Firing Your Function Via a Filter Hook
The other kind of hook is a filter hook. This will already be wrapped around some code or content when it’s created, and your function will override that. It’s useful if you want to code something into a theme template file but give yourself the option of overriding it later. WordPress also provides you with a range of filter hooks for use with various functions.
If you’re not sure of the difference between the two types of hook, our guide to action and filter hooks will clarify things for you.
Here’s an example: a piece of text in a template file.
Note: I know that writing text directly into template files isn’t best practice. I also know that doing it like this without internalization is also bad practice. But it’s a straightforward example, so please don’t beat me up in the comments.
To add a filter hook to your template file, you use the
apply_filters() function with the filter name as the first parameter and the default content as the second:
And here’s how you’d hook a function attached to it:
Note that the
add_filter() function after the function is very similar to the
add_action() function. The first parameter is the name of the hook and the second is the name of the function. Also note that the
apply_filters() function is often preceded by
echo, because it’s echoing out some text (in this case, a heading).
Using Conditional Tags
When you’re using hooks to fire your functions, you can combine this with conditional tags to define the circumstances under which a function will fire.
Something I often see people get wrong is the positioning of conditional tags. Logic may tell you that you only want the function to fire in specific circumstances, so you put the conditional tag outside the function, right?
Here are two ways I’ve seen it done, both of which are WRONG. First, wrapping the tag around the action hook:
And second, wrapping it around the function – also WRONG:
The only correct way is putting the conditional tag around the code inside your function. So the function will fire in all cases, but if the condition is not met, nothing will actually happen.
Here’s the correct way to use a conditional tag to check for a single post:
Using a conditional tag like this makes things simpler and more precise, and is a powerful use for functions.
Knowing How To Write and Activate Functions Will Kickstart Your WordPress Development
Understanding how functions work and being able to write them is an essential skill if you’re planning to code your own WordPress themes and plugins. With this guide, you’ll know exactly how to write your functions correctly and how to select which method for activating them.Tags: