If you are new to WordPress, but already know how to program, the typical "Hello, World" examples aren't helpful. You need to know how to make the right API calls, and where to find documentation about the actions and filters that WordPress makes available to you.
This presentation is a brief introduction skimming the surface of the API hook system in WordPress. It does not go into deep detail, but gives brief "real world" examples of how to use filters and actions, along with pointers on where to find the main documentation that will help you get started on your own plugins.
2. Who am I?
Dougal Campbell
Blog: geek ramblings http://dougal.gunters.org
Twitter: dougal
Facebook: DougalCampbell
WordPress “Developer Emeritus”
Core features: Post custom fields (postmeta), Blogging
API support, Conditional GET support for feeds, Mass
re-enabling for plugins
Plugins: Text Filter Suite (pirate filter), EasyGravatars,
Theme Preview, Fancybox Gallery
Created Ping-O-Matic and Twitual
3. Who is this session for?
This session is for you if some combination of the following
apply to you:
Use WordPress (duh!)
Know at least a little bit of PHP (functions, arrays)
Beyond “Hello, World”, but don’t grok the WP API yet
Keep hearing about “hooks”, “actions”, and “filters”
You’re just curious, darnit!
4. What are plugins?
Extend the functionality of WordPress
Alter content before it is displayed
Interact with 3rd party services (data in/out)
5. Terminology
Filters: Let you modify content before using it
Actions: Let you “do something” at certain points
in the code flow
Hooks: Generic term for filter and action names
API: Application Programming Interface - fancy
name for all of the functions available to you
7. Filters
In photography, a filter lets you change how an image
looks, from its true reality into something different. Color
filters, blur filters, etc. In programs like Photoshop, filters
take this to a whole new level: posterization, color
conversions, art styles, etc.
In WordPress, filters let you take an original piece of
content (post title, content, option values, etc) and
transform it. Original content goes in, new content comes
out.
8. Actions
Actions don't change anything, they just do stuff. For
example, whenever you publish a new post, an action
could update your status on Twitter. Or an action could see
that a visitor to your site came from Digg, and display a
special greeting to them. Or it could do something totally
invisible, like collecting visitor stats in your database.
Actions are less about content, and more about events that
happen as part of the process of processing a visit and
displaying your content to the visitor, or as a result of
actions you take when you configure your WordPress site.
9. How do you use them?
Fundamentally, the filter and action hooks are very easy to
add to the WordPress execution flow:
Create a function
Tell WordPress to add your function as a filter or
action
That's it. It's that simple.
10. How do you use them?
Fundamentally, the filter and action hooks are very easy to
add to the WordPress execution flow:
Create a function
Tell WordPress to add your function as a filter or
action
That's it. It's that simple.
Well, okay, not really. You need to know which actions and
filters WordPress provides to you. Let's break it down to
the next level with a simple real-world example...
12. Hooking it in
How do we tell WordPress about our filter function? With a
filter hook.
Adding a filter hook looks like this:
add_filter(hook-name, function-name);
Where ‘hook-name’ is the name of a WordPress filter API
hook, and ‘function-name’ is the name of the filter function
you wish to pass content through.
13. Hooking it in
The ‘function-name’ part is easy: we just wrote it. It’s our
‘dc_add_copyright’ function.
add_filter(hook-name, ‘dc_add_copyright’);
But what is this ‘hook-name’ you speak of?
14. Hooking it in
WordPress hook names are used to identify various
'events' that occur during the building of your pages. In our
case, we are looking for the filter hook that is used to
modify your post content. That hook is conveniently named
'the_content'.
add_filter(‘the_content’, ‘dc_add_copyright’);
Easy peasy! Except, how did I know what the name of the
hook was? This is where some research might be
necessary when you're first getting started...
15. Codex API Resources
The Codex is the community-maintained online
documentation site for WordPress. In particular, you might
want to bookmark these pages:
http://codex.wordpress.org/Plugin_API/Filter_Reference
http://codex.wordpress.org/Plugin_API/Action_Reference
These pages should list the names of every available filter
and action hook.
16. Action Hooks
Adding an action hook is extremely similar to adding a filter
hook:
add_action(hook-name,function-name);
Where ‘hook-name’ is the name of a WordPress action API
hook, and ‘function-name’ is the name of the function you
wish to fire when that hook event occurs.
17. Events?
As the WordPress code executes, there are several key points at which action
events can fire. Some occur automatically, some fire based on user actions, or
certain conditions being true or false, or at certain points in the display of your
theme.
A few examples:
init: fires after most of the main WP core is loaded
parse_request: fires when WP is determining what kind of request is being
made (post, page, archives, category, etc.)
wp_head: fires in a theme inside the ‘header.php’ template
wp_footer: fires in a theme inside the ‘footer.php’ template
19. Hooking it in
This looks almost exactly like our filter example:
add_action(‘wp_footer’, ‘dc_print_copyright’);
Now when WordPress is outputting a page, and the theme
calls do_action(‘wp_footer’), our function will be run, and it will
print the copyright notice.
20. Best Practices
Namespacing: Make sure that your functions and variables are unique. Give
them a prefix, or encapsulate your code into a class.
Security: WordPress provides many functions to help you keep your code
secure. Use them! esc_attr(), esc_url(), esc_sql(), esc_js(), wp_nonce_url(),
wp_nonce_field(), etc.
If there is something you are trying to do that seems hard, WordPress has
probably already solved the problem for you. Look for existing functions that
do what you need. Don’t re-invent the wheel!
21. What we didn’t cover
The standard plugin header
http://codex.wordpress.org/Writing_a_Plugin
Object methods require a special way to specify the
filter or action function name: array(&$this,
‘function_name’);
Plugin option screens, saving and retrieving plugin
settings
“Pluggable” functions (override core functions)
http://codex.wordpress.org/Pluggable_Functions