WordCamp Ann Arbor 2014 Introduction to WordPress Hooks

build create W O R D C A M P G R A N D R A P I D S

W O R D P R E S S H O O K SI N T R O D U C T I O N T O


build create W O R D C A M P C H I C A G O

H I .

Designer, developer, marketer, writer, etc.

Co-owner build/create studios

@buildcreate @wilsonographybuildcreate.com

I ’ M I A N , N I C E T O M E E T Y O U .

http://buildcreate.com


W A L K A W AY E N L I G H T E N E D


L E T ’ S TA L K A B O U T H O O K S

“Hooks enable us to literally hook into parts of the WordPress page lifecycle to retrieve, insert, or modify data, or they allow us to take certain actions behind the scenes.”

- T O M M C FA R L I N @ T U T S P L U S


A W O R L D W I T H O U T H O O K S


I T ’ S P R E T T Y D A M N H A C K Y

• Including extra PHP files for ajax requests

• Hacking into plugins to change display/functionality

• Hacking *gasp* WP core files

• Hacking theme files (when you should be using a child theme)

• Hackity hack hack hack.


F I LT E R S

• Applying changes to content/data

• Uses functions:

• apply_filters()This is the hook.

• add_filter()This is what you use to tie into the hook.

A C T I O N S

• Hooks your functions into an action in WP

• Uses functions:

• do_action()This is the hook.

• add_action()This is what you use to tie into the hook.


Filters and Actions are nearly the same thing in WordPress, almost identical syntax, capabilities, and limitations.

The difference is how you use them.


F I LT E R S

• Change something you’re pulling out of WP- the content, a media file, etc.

• Change something you’re putting into the WP database

A C T I O N S

• Tying into existing WP processes, like sending email, saving a post, saving a comment, etc.

• Add an action to your plugin/theme to allow other developers to manipulate it without hacking

T H E S A M E , B U T D I F F E R E N T.


N O W L E T S D E M Y S T I F Y.


A N AT O M Y T I M E

add_filter( $hook, $function_to_add, $priority, $accepted_args );

The name of the filter to hook into

Your function you want to run when the filter is applied

Lower numbers = earlier execution of your filter

Any additional arguments you want to pass to the function

add_action( $hook, $function_to_add, $priority, $accepted_args );


S O M E N I T T Y G R I T T Y N O T E S• Usually a filter comes with one argument by default- the content that you’re going to be

modifying. Some filters accept additional arguments as specified in the matching “apply_filter” call. Make sure you’re aware of these when you use the filter.

• Though you can pass all kinds of arguments into your filter function, the only thing you get back is the value of what you’re filtering. So for example if you’re using ‘the_content’ filter, and you have your function accept the post ID as well as the default content argument, all you can safely return at the end of your function is the content.

• Actions don’t return any data, only true. Always true. Deal with it.

• Actions also allow you to pass “all” as the hook name to tie into every hook. Yikes.

• You can pass a class method like so: array( 'My_Class', ‘my_class_method’ ).This is especially useful in plugin development when ofttimes your plugin has several class methods.


U P N E X T: A S U P E R D U P E R S I M P L E E X A M P L E


add_filter(“the_content”, “my_filter_function”, 10);

function my_filter_function($content) { $output = “<div class=‘user-content’>$content</div>”; return $output; }


add_filter(‘the_content’, ‘my_filter_function’, 10);

function my_filter_function($content) { $output = '<div>'.$content.'</div>'; return $output; }

This variable comes through from the matching apply_filter()


Your function you want to run when the filter is applied

Lower numbers = earlier execution of your filter


D E F I N I N G Y O U R H O O K S

apply_filter( $tag, $value, $arg );


The value you want to modify with the filter

One or more additional arguments passed to the filter function

do_action( $tag, $arg);

See? The only difference is that we aren’t passing a value to modify.


E X A M P L E H O O K S

• save_post - Action: runs whenever a post or page is created/updated. Useful for saving custom meta information.

• add_meta_boxes - Action: used to add meta boxes to the WordPress edit screen. You’d then probably wind up using the save_post action to validate the data before saving.

• wp_enqueue_scripts - Action: used to add styles and scripts to the front end. Used a lot in themes and plugins. There’s also an admin and login version for adding styles and scripts to those areas.

• the_content, the_title, etc - Filter: used to modify the content and title respectively. There are also filters to modify these in the editor on the backend of WordPress.

• wp_authenticate_user - Filter: used to tie into the authentication process and run your own authentication function on the user’s login form submission.

• body_class - Filter: say you want to add some classes to the body based on various conditions (assuming you’re using the body_class function in your template), you would use this hook in your functions.php to handle that.


Where does all of this fit into the WP loading process?

L E T S G E T T E C H N I C A L


D I Y H O O K S I N Y O U R T E M P L AT E

<div id=“main-content”> <?php !do_action(“my_before_content”); !if ( have_posts() ) { while ( have_posts() ) { the_post(); the_content(); } // end while } // end if !do_action(“my_after_content’); !?> </div>

These are your hooks, this is what your add_action calls will tie into. !Now you can easily add stuff before or after the content, without muddying up the template!


add_filter(‘my_before_content’, ‘add_before_content’, 10);

function add_before_content() { $output = ‘<div>This comes before the content!</div>’; return $output; }

add_filter(‘my_after_content’, ‘add_after_content’, 10);

function add_after_content() { $output = ‘<div>This comes after the content!</div>’; return $output; }

A N D T H E N I N Y O U R F U N C T I O N S . P H P


O N E M O R E T H I N G - A J A X


<script> var ajaxurl = <?php echo admin_url('admin-ajax.php'); ?> $("#my-action-link").on("click", function(e){ $.ajax({ url: ajaxurl, type: "POST", action: "my_action", success: function(data) { alert(data); } }); }); </script>

S T E P 1 : T H E J A VA S C R I P T

Look familiar? If you’re used to using ajax, it should. The key difference here is the action parameter, which is our first step in tying our ajax request into WordPress.

Grab the admin url so you are submitting your ajax request to the correct url.


add_action(‘wp_ajax_my_action’, ‘my_action_function’, 10);

add_action(‘wp_ajax_nopriv_my_action’, ‘my_action_function’, 10);

function my_action_function() { $output = ‘<div>This comes after the content!</div>’; return $output; }

S T E P 2 : T H E P H P

The wp_ajax hook is dynamic in that the hook name includes your action name from the previous slide. Adding the “nopriv” version of the hook allows the ajax call to work for non-logged in users as well.


The best way to learn is to look at other people’s code and in the WordPress Codex. See how they use it, how it comes together, and of course try it yourself!

Experiment!


M E O W W E ’ R E TA L K I N !


N O W Y O U ’ R E T H I N K I N G W I T H H O O K S

• Work WITH plugins as the author intended instead of hacking them!

• GTFO WP core files!

• Build better themes, child themes, and plugins!

• ????

• Profit!


T H A N K S F O R C O M I N G !

• http://codex.wordpress.org/Plugin_API/Action_Reference

• http://code.tutsplus.com/articles/the-beginners-guide-to-wordpress-actions-and-filters--wp-27373

• http://www.zell-weekeat.com/wordpress-actions-and-filters/

• http://codex.wordpress.org/Plugin_API/Filter_Reference

• http://www.slideshare.net/wilsonography/introduction-to-wordpress-hooks

R E S O U R C E S


http://codex.wordpress.org/Plugin_API/Action_Reference

http://code.tutsplus.com/articles/the-beginners-guide-to-wordpress-actions-and-filters--wp-27373

http://www.zell-weekeat.com/wordpress-actions-and-filters/

http://codex.wordpress.org/Plugin_API/Filter_Reference

http://www.slideshare.net/wilsonography/introduction-to-wordpress-hooks

Internet

WordCamp Ann Arbor 2014 Introduction to WordPress Hooks