WordPress Plugin Bootcamp Part 1 – Getting Started

wpplugins

WordPress plugins are big, and for good reason. Not only are they incredibly useful, they also are an excellent way to gain publicity and the real powerhouse of WordPress’ flexibility and customizability. A good plugin can really make a difference, and there’s no reason why you can’t get in on it and learn to write your own.

This week, we’re going to be going all the way from the ground floor to the complex ins and outs of advanced WordPress plugin development. Are you ready?

Let’s Go!

To get the most out of the tutorials I’ll be posting this week, it would probably be best if you have a few things at hand so that you can follow along and learn by doing. Here’s what that might include:

  • A WordPress test environment – whether that’s local or on your server is up to you
  • A good IDE and FTP client – check out 10 Apps for Developers on a Shoestring Budget
  • A basic understanding of PHP – don’t worry if you’re a beginner, but it helps to at least understand the syntax

So you’re armed to the teeth and ready to go start coding? The first thing will take a look at is conventions - if you’re going to do it, you want to look professional, right?

Defining Your Plugin

getting started
The WordPress plugin system seems almost magical – you simply drop a folder into wp-content/plugins and the plugin, with it’s name, description and extra information just appears on the Manage Plugins page - ready to be activated at your whim. What really happens is that when WordPress loads it scans the plugins directory and then grabs a ‘header’ out of  each plugin folder, which has all the plugin information defined inside of it.

You, the plugin author, get to define all that information in a comment at the top of you main plugin file (which should have the same name as the plugin directory). So, create a PHP file called by the name of your plugin-to-be (like “social-ninja.php”) inside a folder with the same name. Now at the top of the file, type your plugin information out according to the pattern below. If you’ve ever done WordPress theme development, this will look very familiar – just like the comment that goes at the top of style.css:

< ?php
/*
Plugin Name: plugin name
Version: plugin version
Description: your description here
Author: your name here
Author URI: your uri here
Plugin URI: plugin-specific address (for support, docs, etc.)
*/
?>

Now, if you try uploading your plugin folder to wp-content/plugins, your new plugin will show up on the Manage Plugins page – it works! Of course, this plugin doesn’t do anything just yet, but we’ve got our foundation down. By the way, WordPress will not read any plugin files other than the main one with the header in it – you must include() them.  Next up is how to practice ‘Defensive Development’ with your plugin!

Making Your Plugin Bombproof

bombproof
One of the things that is very important to remember when developing a plugin is that it should never, ever stop the rest of WordPress from running by causing an error. That is the cardinal sin of plugin development. Your plugin may be running in different WP versions with any combination other plugins and who knows what kind of a theme, which makes it very important to always practice ‘Defensive Development’ and don’t assume anything.

That means always checking if a function exists before calling it:

< ?php
if( function_exists('yourfunction') ){
    yourfunction();
}
?>

It’s also a good idea to check the WordPress version to be sure it’s not really ancient. WordPress provides a function for doing that: version_compare(). It accepts 3 args – the current version (you can use global $wp_version), the version you’re comparing it to, and the operator the function should use to compare them. Here’s what that looks like:

< ?php
if(version_compare($wp_version,"2.6","<"):
     //produce error message if version is less than 2.6
else:
     //place plugin code here
endif;
?>

There’s a whole lifetime of opportunity for making your code hardier and more stable (that’s what a developer does!) but just remember that you shouldn’t assume anything and you’ll be well on your way to writing bombproof plugins. So, now that we’ve got that covered it’s time to look at hooks – the big celebrities in plugin development.

Actions and Filters – The Heart of WP Customization

actions & filters
Actions and filters – the two types of Wordpress ‘hooks’ are the where the true power and flexibility of WordPress lies. There are literally hundreds of them, one for each little point in all of WordPress’s possible routines, allowing you to do virtually anything you want with WordPress.

Actions are what they sound like – events that are triggered at certain points in WordPress’s routines. Using the add_action() hook, you can attach a function to any one of those actions so that your function will be executed when WordPress reaches that point. For example, the wp_head action is activated when wp_head() is called in the current WordPress theme, so it is often used to include things like stylesheets that will be used to style plugin output. So you could put this in your plugin file:

function print_my_stylesheets(){
    echo ""
}

add_action('wp_head','print_my_stylesheets');

Now, when wp_head() is called it will call print_my_stylesheets(), which will echo the stylesheet link tag that we told it to.

Add action accepts four parameters – the hook (like ‘wp_head’), the function name (like ‘print_my_stylesheets’), an optional priority (a way to control the order that functions are executed in when more than one are bound to the same event – default is 10 and the lower the number, the sooner the function is excuted) and an optional number of accepted arguments for hooks that pass more than one argument.

There are lots more actions:

  • init – runs after WordPress has loaded but before any headers/content are sent
  • publish_post – triggered when a post is published, or an already published post is updated
  • create_category – runs when a new category is created
  • comment_post – happens just after a comment is added to the database
  • rss_item – triggered after each RSS item when RSS 2 feed is published
  • switch_theme – runs when theme is changed

These are some of the most useful, but there are too many to list here, so I’d encourage you to check out the Action Reference – it’s a lot of fun.

wp-plugin-api-screenshot

The other type of hook is a filter. The difference between an action and a filter is that while an action just executes the functions attached to it, a filter actually passes its content to those functions.

For example, there is a popular filter called the_content which actually takes the data produced by the template tag the_content() and passes it to your filter function, allowing you to manipulate and append things to the_content. This is often used for adding social promotion links, end-of-post advertisements, etc.

Filters are implemented very similarly to actions – with an add_filter() function that accepts the same four parameters. The only difference you have to define an argument to hold the content passed to your handler function, and then be sure to return it :

function wp_social_promo($content){
    $promo_bar = "define your code";
    return $content . $promo_bar;
}

add_filter('the_content','wp_social_promo');

There are far more filters even than actions, but here’s a sampling:

  • wp_title – edit content passed to the wp_title() function
  • get_the_excerpt – manipulate content printed by get_the_excerpt()
  • get_bookmarks – edit bookmarks before they are printed
  • default_content – allows you to set default content for a new post
  • several ‘pre’ filters (comment_save_pre, content_save_pre) allowing you to edit content before it goes into the database rather than before it’s displayed.

Again, I’d recommend browsing the Filter Reference to get the full scoop.

Bonus: Adding Scripts

add scripts
OK, let’s fit one more juicy tidbit in here: how to include Javascript files. Scripts are important to a lot of plugins, so it’s one of the more fundamental plugin-building skills. There are two ways to do it – a good way and an even better way:

  • The good way- use the wp_head action hook and call a function that writes out the necessary script tags.
  • The even better way - use wp_enqueue_scripts(), a WordPress function that’s  designed specifically for adding scripts.

Because its very purpose is to allow easy script inclusion, wp_enqueue_scripts() has several features that make it a much better choice. The coolest thing is that it will let us include WP built in scripts like jQuery, colorpicker, Prototype, thickbox and more just by referring to their name- we don’t even have to include them in our plugin package. Here’s what it looks like:

wp_enqueue_script('handle','src','array of dependencies','version');

And here’s how the params work:

  • handle – lowercase string holding the name of the script, the only required parameter. For WP supported scripts, this is all you need (ie, ‘jquery’ or ‘thickbox’).
  • src – URI to the script. You only need this if it is a custom script that is included with the plugin.
  • array of dependencies – An array of script handles that must be loaded before this one, like how a jQuery plugin would need jquery loaded first. This is optional.
  • version – Optional, mostly useful if caching is in use.

Pretty handy, huh? Now if you’re ever marooned on a desert island at least you’ll know how to reference scripts for WordPress plugins :)

Wrapping Up

So you’ve got your first lesson in WP Plugin development. I hope you’ve enjoyed yourself, learned something new, and that you’ll refrain from  being shy and go drop a question or opinion in the comment form! I’ll be publishing a whole slew of great WP Plugin resources on Friday, but in the mean time feel free to go browse WordPress’s guide to Writing a Plugin.

Tomorrow we’ll be covering custom widgets, how to build those cool plugin management pages, and saving/retrieving plugin options, so be sure to check back!

Written By Nick Parsons

Nick is the editor of Webitect and a developer + designer from Houston TX.

5 Comments

  1. MAC

    January 18th, 2010 at 02:33 pm

    This is a great article! Word press plugins are a subget wich i’m very fond of.

    I’m refering and linking to it from my own website.

    Cheers!

    Miguel Azevedo e Castro

  2. Mike Smith

    January 24th, 2010 at 06:17 am

    this is awesome. I’m going through all of the posts in this series tomorrow. thanks for posting this all up.

  3. Stephanie

    December 13th, 2010 at 10:54 am

    FYI: The above code “if(version_compare($wp_version,”2.6″,”<"):" should be "if(version_compare($wp_version,"2.6","<")):" …it's missing a closing parenthesis in the expression.

    Thanks for the great tutorials :-)

  4. crossbow cocking rope

    August 3rd, 2013 at 06:11 am

    176172 547660As I website possessor I think the articles here is very wonderful, regards for your efforts. 103161

  5. balustrade

    August 3rd, 2013 at 06:16 am

    982042 373942I

What Do You Think?