Hooking with WordPress

Hooking with WordPress

WordPress Plugins 103

WordPress Hooks

WordPress Hooks• Actions• Filters

WordPress Actions

ACTIONS ARE THE HOOKS THAT THE WORDPRESS CORE LAUNCHES AT SPECIFIC POINTS DURING EXECUTION, OR WHEN SPECIFIC EVENTS OCCUR. YOUR PLUGIN CAN SPECIFY THAT ONE OR MORE OF ITS PHP FUNCTIONS ARE EXECUTED AT THESE POINTS, USING THE ACTION API.

~~ WORDPRESS CODEX

WordPress Actions

WordPress Hooks

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

WordPress Actions

Basic Functions• do_action()

– http://codex.wordpress.org/Function_Reference/do_action

• add_action()– http://codex.wordpress.org/Function_Reference/add_action

• remove_action()– http://codex.wordpress.org/Function_Reference/remove_action

WordPress Actions

Basic Functions• do_action()

– http://codex.wordpress.org/Function_Reference/do_action

This is where the action fires in the code, and where your hook will attach itself.

Example: do_action( ‘my_action’ );

WordPress Actions

Basic Functions• add_action()

– http://codex.wordpress.org/Function_Reference/add_action

This is what you use to add your action (or functionality) to the do_action() sequence.

Example:add_action( ‘my_action’, ‘my_functionality’, 10 );

WordPress Actions

Basic Functions• remove_action()

– http://codex.wordpress.org/Function_Reference/remove_action

This is what you use to remove a specific action that has been added … and it requires a call to an action, too?!

WordPress Actions

Basic Functions• remove_action()

Example:function remove_my_action(){

remove_action( ‘my_action’, ‘my_functionality’, 10 );

}

add_action( ‘init’, ‘remove_my_action’ );

Note: the priority being used; and, adding to the init action.

WordPress Filters

FILTERS ARE THE HOOKS THAT WORDPRESS LAUNCHES TO MODIFY TEXT OF VARIOUS TYPES BEFORE ADDING IT TO THE DATABASE OR SENDING IT TO THE BROWSER SCREEN. YOUR PLUGIN CAN SPECIFY THAT ONE OR MORE OF ITS PHP FUNCTIONS IS EXECUTED TO MODIFY SPECIFIC TYPES OF TEXT AT THESE TIMES, USING THE FILTER API.

~~ WORDPRESS CODEX

WordPress Filters

WordPress Hooks

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

WordPress Filters

Basic Functions• apply_filters

– http://codex.wordpress.org/Function_Reference/apply_filters

• add_filter– http://codex.wordpress.org/Function_Reference/add_filter

• remove_filter– http://codex.wordpress.org/Function_Reference/remove_filter

WordPress Filters

Basic Functions• apply_filters

– http://codex.wordpress.org/Function_Reference/apply_filters

This is where the filter fires in the code, and where your hook will attach itself.

Example:apply_filters( ‘my_filter’, ‘my_original_value’ );

WordPress Filters

Basic Functions• add_filter

– http://codex.wordpress.org/Function_Reference/add_filter

This is what you use to add your filter (or new value) to the apply_filters() item.

Example:add_filter( ‘my_filter’, ‘my_new_value’ );

WordPress Filters

Basic Functions• remove_filter

– http://codex.wordpress.org/Function_Reference/remove_filter

This is what you use to remove a specific filter that has been used … and it is best to follow the remove_action() example as the safest method to implement.

WordPress Filters

Basic functions• remove_filter()

Example:function remove_my_filter(){

remove_filter( ‘my_filter’, ‘my_new_value’, 20 );

}

add_action( ‘init’, ‘remove_my_filter’ );

Note: the priority being used; and, adding to the init action.

Hooking with WordPress

1. Open your local test environment

2. Make sure the BNS Bio plugin is installed and activated

3. Add the [bns_bio] shortcode to a post

4. Open your text editor

5. Navigate to the BNS Bio folder

6. Ready?

BNS Bio Plugin

The BNS Bio plugin adds a simple shortcode to your WordPress installation that outputs the author details of the post it is added to.

The plugin uses a different approach to options by utilizing “extension” plugins versus an options panel. This is primarily for the purposes of using BNS Bio as example code.

BNS Bio Structures

• Uses the Class PHP structure– Uses a simple constuctor method

• __construct()

– Enqueues its own stylesheet with an optional call to a custom stylesheet• Scripts_and_Styles()

– Collect the author details which it passes back to the shortcode `bns_bio`• author_block()

BNS Bio __construct()

The constructor method of the BNS Bio class calls an action to add the Scripts_and_Styles functionality …

/** Add Scripts and Styles */

add_action( 'wp_enqueue_scripts', array( $this, 'Scripts_and_Styles' ) );

… note the difference from the earlier example.

WordPress Actions

Basic Functions• add_action()

– http://codex.wordpress.org/Function_Reference/add_action

Example:add_action( ‘my_action’, ‘my_functionality’, 10 );

Using in a Class example:add_action( ‘my_action’, array( $this, ‘my_functionality’ ) );

BNS Bio author_block()

• This is the main code of the plugin.• There are many instances of hooks

(actions and filters) available to work with.

Examples:do_action( 'bns_bio_before_all' );

apply_filters( 'bns_bio_author_url_text', …

apply_filters( 'bns_bio_author_desc', …

BNS Bio Box

This is an “extension plugin” for BNS Bio.

It adds a rounded corner border, or box, around the BNS Bio output by hooking an additional CSS container into the ‘bns_bio_before_all’ and ‘bns_bio_after_all’ actions; then adding the appropriate style properties to create the look.

BNS Bio Box Code

The essentials:• Define the functions to be used• Hook them into the appropriate action

– add_action( 'bns_bio_before_all', 'bns_bio_open_box' );– add_action( 'bns_bio_after_all', 'bns_bio_close_box' );

• Add the stylesheet (using the common enqueue method; and another add_action call)

BNS Bio List

This is another “extension plugin” for BNS Bio that changes the output to an unordered list by hooking into the available actions and adding the appropriate HTML (‘ul’ and ‘li’) elements.

It also includes its own enqueued stylesheet and calls an optional custom stylesheet if available.

BNS Bio List Code

The essentials:• Add the ‘ul’ container:

– add_action( 'bns_bio_before_all', function(){ echo '<ul class="bns-bio-list">'; }, 20 );– add_action( 'bns_bio_after_all', function(){ echo '</ul><!-- .bns-bio-list -->'; }, 9 );

• Add the ‘li’ containers:– add_action( 'bns_bio_before_author_name', 'bns_bio_list_item' );– add_action( 'bns_bio_before_author_url', 'bns_bio_list_item' );– add_action( 'bns_bio_before_author_email', 'bns_bio_list_item' );– add_action( 'bns_bio_before_author_desc', 'bns_bio_list_item' );

NB: I used two different methods for adding the functionality: a call to a predefined function (‘bns_bio_list_item’) and anonymous functions1

BNS Bio List Notes

1. The anonymous functions were used for example purposes and may not work with versions of PHP earlier than 5.3.0 where they were introduced.

BNS Bio Hide

This is another “extension plugin” for BNS Bio that changes the output by hiding the author email details.

There are actually three items that need to be addressed to hide the email line in the output:• What displays before the email• What displays as the author (pre) email text• What displays as the author email

WordPress Plugins 103

The essentials:• remove_action( 'bns_bio_before_author_email', 'bns_bio_list_item' );

– (as applied to the init hook – see original ‘remove_action’ example)• add_filter( 'bns_bio_author_email_text', '__return_null', 100 );• add_filter( 'bns_bio_author_email', '__return_null', 100 );

Notes:• The remove_action priority is left as the default as the ‘bns_bio_list_item’

function was added at the default priority (these priorities must match).• Filters are essentially a “last one standing” mechanism; and in this case, the

WordPress ‘__return_null’ function was called at a very late priority to help insure it is last to run and therefore the final output.

WordPress Plugins 103

Hooking with WordPress

Questions and Answers

Credits

Presented by Edward Caissie

for the WordPress GTA Meetup group

on November 19, 2012.

Contact Details:Email: edward.caissie@gmail.com

URL: http://edwardcaissie.com

Quick Resources

Codex References - Actions:

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

http://codex.wordpress.org/Function_Reference/do_action

http://codex.wordpress.org/Function_Reference/add_action

http://codex.wordpress.org/Function_Reference/remove_filter

Codex References – Filters:

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

http://codex.wordpress.org/Function_Reference/apply_filters

http://codex.wordpress.org/Function_Reference/add_filter

http://codex.wordpress.org/Function_Reference/remove_filter

WordPress Power Point Template Credits

m62 visualcommunications:http://www.m62.net/powerpoint-templates/technology-templates/wordpress-powerpoint-template/

WordPress Plugins 103: Hooking with WordPress

Thank You.