Chan Can Code

From time to time, you will encounter some WordPress plugins that comes with some useful PHP functions which have no corresponding shortcodes. What if you need to place them into your Section Widget?

Of course, if you trust those who have access to your WordPress backend, the PHP shortcode plugin is always there for you. But if you are concerned about security (and you should be!), then allowing anyone to execute abitray PHP code is almost always a bad idea.

It turns out that WordPress’ shortcode API is actually very easy to use. With some minimal PHP knowlege, writing shortcodes is almost a trivial task. So, instead of allowing abitary PHP code, you can select only a few “safe” functions and turn them into shortcodes. To put this tutorial into context, let’s say we would like to display the Askimet spam counter on our frontpage. The Akismet plugin itself already provided such functionailty out of the box:

Want to show off how much spam Akismet has caught for you? Just put <?php akismet_counter(); ?> in your template.

Sweet. So how would you turn that into a shortcode? Here is all the code you’d need:

function akismet_counter_handler($atts, $content = null) {
    ob_start();

    /* Content begins - replace with your own code */
    if (function_exists('akismet_counter')){
        akismet_counter();
    }
    /* Content ends here */

    return ob_get_clean();
}

add_shortcode('akismet_counter', 'akismet_counter_handler');

Yep, that’s it. With these few lines of code you’ve created your own [akismet_counter] shortcode! Don’t worry if you have no idea what is going on here, I’m going to walk you through the details here.

Simply put, the shortcode API works very much like text subsition. To define and register a shortcode in WordPress, you need to call the add_shortcode function with two parameters – the name of the shortcode and the name of a “handler function” for this shortcode. On line 13 of the example, we are basically telling wordpress to look for any occurance of [akismet_counter] and replace that with the return value of the akismet_counter_handler PHP function.

As you might have guessed, the “handler function” is just a PHP function that returns a String. Because the akismet_counter function will directly echo its output, we created an output buffer on line 2 and returned that content as a String on line 10. Also, because our shortcode depends on another plugin which might or might not be installed or activated, it is probably a good idea to make sure the akismet_counter function actaully exists before calling it to avoid the nasty PHP error.

Now you have a brief idea of the how the shortcode API works, the only missing piece is where to put it. There are two logical places to put these kind of code – package it with your theme (inside your functions.php) or as a standalone plugin. This is ultimately a personal preference but I prefer the latter approach because it lets me keep the code in one place.

To complete this tutorial, I have packaged the sample code into a “template” which can be downloaded here. Modify it as you like and upload it to your “/wp-content/plugins/” directory, actiavte the plugin and enjoy!

Tags: php, section widget, shortcode, wordpress

This entry was posted on Tuesday, October 6th, 2009 at 10:05 am and is filed under Uncategorized. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.