Identifying Functionality and Output

Actions and filters hook our functions to WordPress plugin API commands. By now, you should have an understanding of how this works and how it looks in a plugin file. In generic terms, WordPress plugins have two distinct purposes:

• Functions: Defined within the plugin code through a combination of actions and hooks; essentially, functions define what the plugin does.
• Output: What is displayed on your site as a result of the plugin function(s). For example, if the plugin function(s) makes calls to the database to retrieve a certain type of post (for instance, from a certain category or tag) from your content, the output is how those posts then get displayed on your site for your readers to see. Plugins can also use HTML markup and CSS to provide basic styling for the output.

Members of the WordPress community eager to learn more often ask how to go about dissecting a WordPress plugin, possibly to modify its internal functionality or even its output. In Book VII, Chapter 5, we discuss providing an API specific to your plugin. You can determine a plugin function, as well as how it outputs the result of the functions on your Web site by taking a look at the source code of the plugin.

When digging into an existing plugin that you'd like to alter, you want figure out what action and filter hooks it's using. Some plugins make this easy by putting most or all of the calls to hooks at the bottom of a file (often the primary plugin file). We use a plugin called TweetMeme Retweet Button as an example of how you can look into the source code of the plugin and make alterations. The TweetMeme Retweet Button plugin can be installed automatically through your WordPress Dashboard or downloaded at http://wordpress.org/extend/plugins/tweetmeme. Scroll to the bottom of tweetmeme.php and look for the add_action() and add_filter() functions:

// Only all the admin options if the user is an admin if(is_admin()){
   add_action('admin_menu', 'tm_options'), add_action('admin_init', 'tm_
    init'), }
// Set the default options when the plugin is activated
function tm_activate(){     add_option('tm_where',
'before'),     add_option('tm_rss_where', 'before'),
add_option('tm_source'),     add_option('tm_style',
'float: right; margin-left: 10px;'),
add_option('tm_version', 'large'),
add_option('tm_display_page', '1'),
add_option('tm_display_front', '1'),
add_option('tm_display_rss', '1'),
add_option('tm_ping', 'on'),
add_option('tm_hashtags', 'on'), }
add_filter('the_content', 'tm_update', 8);
add_filter('get_the_excerpt', 'tm_remove_filter', 9);
add_action('publish_post', 'tm_ping', 9);
add_action('wp_head', 'tm_head'),
register_activation_hook( __FILE__, 'tm_activate'),

We can see most of the hooks the plugin uses (admin_menu, admin_init, the_content, get_the_excerpt, publish_post, wp_head) grouped nicely into one section. By now, you should know what most of these hooks do. If not, that's okay, too. You can look up literally hundreds of hooks on the WordPress Codex, which has plain English descriptions of many WordPress hooks:

• WordPress Filter Hooks: http://codex.wordpress.org/Plugin_API/Filter_Reference
• WordPress Action Hooks: http://codex.wordpress.org/Plugin_API/Action_Reference

By analyzing what hooks the plugin uses, you can determine how that plugin interfaces with WordPress to pass the results of its code to the rest of the WordPress system. For instance, TweetMeme calls the tm_ping() function on the publish_post action. The publish_post action hook always runs within WordPress whenever a post is published. From this line, we can deduce that an examination of the tm_ping() function will tell us what additional functionality occurs on this action.

Search for function tm_ping; you find the following lines of code:

function tm_ping($post_id) {
// do we have curl
   if ((get_option('tm_ping') != 'off') &&
      function_exists('curl_init'))            { $url = get_permalink($post_id);
    // create a new cURL resource          $ch = curl_init();            // set URL
    and other appropriate options          curl_setopt($ch, CURLOPT_URL, 'http://
    api.tweetmeme.com/ping.php?url=' . urlencode($url));          curl_setopt($ch,
    CURLOPT_CONNECTTIMEOUT, 2);         curl_setopt($ch, CURLOPT_TIMEOUT, 3);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);          // grab URL and pass it
    to the browser         curl_exec($ch);          // close cURL resource, and
    free up system resources         curl_close($ch);
}
  }

When publishing or editing a post, the TweetMeme plugin uses curl to ping the TweetMeme API with the appropriate URL of the current post.

Everything inside a plugin contained in a function runs only when that plugin is called. Typically, action and filter hooks are contained in a function. Otherwise, the code will run sooner than necessary or not work at all.

Starting with the hooks at the bottom of the file makes it easier to follow the path of the plugin's functionality. We see that tm_init() is called on the admin_init action, tm_options is called on the admin_menu action, and so on.

Say you want to modify the styling of the TweetMeme button. To locate this part of the code, a logical place to start is the the_content filter, because the TweetMeme Retweet Button plugin outputs the TweetMeme button within the post content on your site:

add_filter('the_content', 'tm_update', 8);

From here, follow the path to the tm_update function. In this function, the button output comes from the $button variable, which is generated by the tm_generate_button() function:

$button = tm_generate_button();

The tm_generate_button function finally uncovers the code for the actual output of the button. The Tweetmeme.com domain delivers the button via an iframe, which is an HTML page embedded in your site, using the HTML <iframe> markup tag. In this function, you can change the button to an image that you host, change the dimensions of the elements in the div, or make any other modifications you prefer in order to change the output of the button as it appears on your Web site.