Wordpress Plugin Tutorial Part IV - Let's add an Action Hook

If you remember part one of the tutorial series you will remember that our goal is to add a custom comment message to the comment form on a per post basis. So in order to do this there should be a field in the "Add New Post" page for the author to enter this message. We will use a Wordpress action hook in order to tell Wordpress to add such a field.
You can "hook" functionality to an "action" using an action hook. For example, saving a post is an "action" and there is an action called "save_post". You can hook your own code to this "action" and whenever the action "save_post" runs, the code that you hooked to that action will also run. Take a look at this article on action hooks to learn more about them.
A list of action hooks can be found at this wordpress page on action hooks. Usually, when new versions of Wordpress is released, new action hooks are added. In order to know which action hooks are available on which version of Wordpress, take a look at this Wordpress action hooks database.
What we want to do is to add a text field(a meta box) which the post author will use to supply a custom comment message. So the action hook that we are interested is "add_meta_boxes". If you go to this page on the Wordpress hooks database you will see that this action has been added on the Wordpress 3.0 release.

In order to hook into the action 'add_meta_boxes' code like the following can be used
add_action( 'add_meta_boxes', 'function_to_run' );
where 'function_to_run' is the code that we want to run when the 'add_meta_boxes' action executes. Now, what do we want to do when the 'add_meta_boxes' action executes? We want to add a custom field. In order to do this we use the 'add_meta_box' function. A list of such functions available to you can be found at the Wordpress function reference page.

Now change the contents of the "custom-comment-message.php" file to look like the following.
<?php
/* 
Plugin Name: Custom Comment Message
*/


if (!class_exists("CustomCommentMessage")) {
    class CustomCommentMessage {
        public function __construct()
        {
            //We hook code to the 'add_meta_boxes' action
            //The code that we hook is the function 'add_ccm_meta_box'
            add_action( 'add_meta_boxes',
                        array( &$this, 'add_ccm_meta_box' ) );
        }

        public function add_ccm_meta_box()
        {
            //We Call this method to add a meta box            
            add_meta_box(
                 'ccm_meta_box'
                ,'Custom Comment Message'
                ,array( &$this, 'render_ccm_meta_box_content' )
                ,'post'                
            );
        }

        //This is the code that adds elements to the user interface
        public function render_ccm_meta_box_content( $post )
        {            
?>
            <label for="ccm__title_reply">
                 Custom Comment Message Title : 
            </label>
            <input type="text"
                   id="ccm_title_reply"
                   name="ccm_title_reply"
                   size="25" />
<?php
        }
    }
}

if (class_exists("CustomCommentMessage")) {
    $ccmessage = new CustomCommentMessage();
}

?>

Notice that we add an action hook in the constructor. After we do so, when the "add_meta_boxes" action is executed, the code that we hooked to the action, that is, the "add_ccm_meta_box" function will run and within that code, the meta box is added using the "add_meta_box" function. We pass into this the "render_meta_box_content" function, which will print the actual input field.  I recommend you to visit this page and learn more about the "add_meta_box" function. It contains example code that you can look into. Also the comments in the above code will help you to understand it.

After doing the above changes you will see a meta box in the "Add New Post" page that looks like the following.

1 comment: