Original can be found here.
Hooks: why?
————-
When you write a plugin you want to be able to switch it on and off whenever you want. This is not that trivial: say you write a function that does something useful, simply calling the function from your code gives an error when your plugin is deactivated. If you are lucky, it displays nothing, if you are less fortunate it displays all kinds of ugly debug information that people can abuse.
That is why ‘hooks’ were invented. Simply put, a hook is a point somewhere in the generation of your page where you can attach functions. When the hook is reached, all functions attached to it are executed in order of priority. When there are no functions attached to it, it does nothing.
So a plugin should do two tasks:
- define a useful function
- attach that function to the right ‘hook’
Many hooks exist already, and most people stick to those hooks. However, hooks are not black magic. Nothing stops you from defining your own hooks, and that is exactly what I’ll do in this page: I’ll create a trivial plugin, put it on my own hook at a place in the page where I like it.
Adding a hook
————–
The first thing I’ll do is the thing many people fear: I’ll create a hook. Using the default theme as an example, the page has a div called "content" which contains the posts in one page. I might want something to happen on the top of the "posts" section, maybe a status message, or a ‘recent comments’ section. That would be the right place to add my own hook.
Now before do that, there is some danger here: many hooks exist already, and before everyone starts defining their own hooks with the same names, let’s set a rule here: if you define your own hook, it should start with your own initials, to let the world know that it works for your plugins and to avoid name collisions. If it is a useful hook, it might become a standard hook for everyone one day.
Ok. Now let’s dive into the "default" theme directory (of course, we work on a backup) and start hacking on "index.php". The spot I had in mind was on line 4, right below the "content" div. I create a hook here called ‘lv_content_head’, because ‘lv’ are my initials, and it is the head of the content. I don’t use any parameters for now.
Below line 3 of "index.php", right below the "content" div, add the following line:
< ?php do_action("lv_content_head"); ?>
That’s all. If you load the page, you’ll see that nothing special happened. That is as it should, because there are no functions attached to it yet.
Now let’s write a "Hello World…" function.
A "Hello World" function
————————-
Now let’s create a real plugin; the file is called "helloworld.php", which will go in the "plugins" directory. The function is plain php; the "Plugin Name" entry in the commented section is is mandatory.
< ?php
/*
Plugin Name: Hello World
*/
function helloworld() {
echo "Hello World…";
}
Now if you would add the closing php-tag, you could see it already in the plugins part of the site administration. Right now, it is not a plugin yet, because it merely defines a function. The next step is to put the function on the hook. Keep the editor open!
Attaching a function to a hook
——————————
Just now we did two things:
- we created a hook somewhere in the generation of the page, and
- we created a function that is to be called when the hook is reached.
The next step is to attach the function to the hook. This is done by calling the function add_action, where its first parameter is the name of the hook (‘lv_content_head’ in our case), and its second parameter is the name of the function (‘helloworld’ in our case).
Our editor is still waiting for us, so add the function to the hook, and close the php part:
add_action("lv_content_head", "helloworld");
?>
Now the entire plugin looks like this:
< ?php
/*
Plugin Name: Hello World
*/
function helloworld() {
echo "Hello World…";
}
add_action("lv_content_head", "helloworld");
?>
Call it helloworld.php and put it in the wp-content/plugins directory.
From the admin panel it can now be activated, and it should display "Hello World…" on the top of the content area.