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: [email protected]
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.