WordPress Plugin: Easy Graphs

Everyone likes data visualizations so I wrote a plugin that will make the quick and secure creation of Pie Charts, Bar Charts and Line Charts easy. The answer is: Easy Graphs.

Easy graphs is very simple to use. It’s a shortcode – [easy_graphs]

Not just like that. The shortcode also requires one parameter “data”. This parameter is a comma separated list of number values “1,2,3,4,5,6,7″.

You can also add a “type” parameter. The “type” can be “line”, “bar” or “pie”. “bar” is the default.

For a Bar graph, you can optionally pass additional parameters: width, height, and color.

Example: [easy_graphs height="200" type="bar" data="30,70,65"]
[easy_graphs height="200" type="bar" data="30,70,65"]

By default, width and height are populated from your media embed sizes that are set in your Settings > Media menu inside WordPress. Color should be a hex color code.

For a line graph, the options are similar: color1, color2, height and width.

If you will: [easy_graphs height="200" type="line" data="200,150,175,260"]
[easy_graphs height="200" type="line" data="200,150,175,260"]

In this case, color1 is the “fill” color and color2 is the line color. Both should be hex.

For Pie charts, there are some additional limitations but fewer parameters: color1, color2 and diameter.

Try this: [easy_graphs diameter="150" data="40,60" type="pie"]
[easy_graphs diameter="350" data="40,60" type="pie"]

Diameter should be an integer represented in pixels. Color1 and color2 are the fill colors of the pie slices. The limitation is the pie chart, at this time, can only take 2 values. I’ll work on that.

On the roadmap are other things. Make the pie chart take more values than just 2. Maybe include other graph types. Labels so the data can be more easily understood.

What would you add to this?

Download Easy Graphs

TUTORIAL: Using WordPress’ Ajax API

WordPress has tons of APIs to do tons of things. It really does. One of the cool ones that I’ve been using a lot lately, has been around for a bit. It’s the Ajax API. Sure, you could write your own Ajaxy thing but why do that when WordPress lets you do it all very simply.

This tutorial will show you how to replicate the functionality that is presented in the “Like” button at Facebook. It assumes that you have WordPress set to require users to be logged in to take such actions. It wouldn’t make much sense for someone to not be logged in for such functionality. Obviously, you could do something else with Ajax (polls? Loading new content?) that doesn’t have the same assumption, but in this case… we’re assuming a user is logged in and the $current_user global is set.

Getting Started

Let’s start with the basic PHP class (you do write good object-oriented code, right?)

1
2
3
4
5
6
7
8
class My_Like_Button {

    function __construct()
    {
    }
}

$my_like_button = new My_Like_Button;

This code is just a basic skeleton that provides a constructor (the __construct() method, which I’ll use later. It also instantiates a new My_Like_Button object and assigns it to the $my_like_button variable for use in the global scope. Obviously, you can use whatever strikes your fancy for the class name or the global variable.

Building the HTML for the Like Button

Next, we need the basic HTML structure that will be used in our theme for the Like button. For the sake of simplicity, I’m not providing any CSS, but feel free to do as you wish. We need to add this as a new method in our class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
function like_button()
{
    if( !is_user_logged_in() )
        return false;
       
    global $current_user;
       
    $html = '<form action="" method="post">
        <input type="hidden" name="like_post_id" id="like_post_id" value="'
. get_the_ID() .'">
        <input type="hidden" name="like_user_id" id="like_user_id" value="'
. $current_user->ID . '">
        <input type="button" name="like_this_post" id="like_this_post" value="Like" />
    </form>'
;
    return $html;
}

This form provides two hidden form fields using get_the_ID() and the $current_user object. Having done this (and after ensuring there is a logged in user), we can now drop this into our theme in the Loop as a template tag:

1
<?php echo $my_like_button->like_button(); ?>

Sending the Ajax Request with jQuery

This is useless by itself. We need something to handle the Ajax. But before we get there, we need to understand how Ajax works within the WordPress context.

All requests must go to wp-admin/admin-ajax.php. Forget the confusion about why you would send a front-end Ajax request to the back-end. You just do.

On the back-end, you’ll have to define functions that will hook into the Ajax API to let WordPress know how to handle the request. More on that in a minute. Let’s build some jQuery to send this to admin-ajax.php.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
function js()
{
    wp_enqueue_script( 'jquery' );
    wp_print_scripts();
    ?>
    <script>
    jQuery(document).ready(function(){
           
        jQuery('#like_this_post').click(function(){
            var like_post_id = jQuery('#like_post_id').val();
            var like_user_id = jQuery('#like_user_id').val();
           
            jQuery.post(
                '<?php echo get_option('siteurl') . '/wp-admin/admin-ajax.php' ?>',
                {
                    action      : 'register_like',
                    user_id     : like_user_id,
                    post_id     : like_post_id,
                    _wpnonce    : '<?php echo wp_create_nonce('nonce-register_like'); ?>',
                },
                function(response) {   
                    alert(response);
                }
            );
               
        });
    });
    </script>
    <?php
}

This is just a PHP function that we can use to throw some jQuery (using the .post() method for our Ajax call) into the head. Note the nonce. You must include this for security. Additionally, you must have an action set. The action is used by WordPress to route the Ajax request.

Finally, we’re passing two extra pieces of data – user_id which is the WordPress user ID and the post_id which is the WordPress post ID of the current $post object inside the Loop. Both of these are supplied in the hidden form fields we created earlier.

Let’s add a new method for hooks and call it in our constructor, so that hooks are executed when the object is instantiated:

1
2
3
4
5
6
7
8
9
function __construct()
{
    $this->hooks();
}
   
function hooks()
{
    add_action( 'wp_head', array( $this, 'js' ) );
}

Supplying the Ajax Handler

Having hooked the jQuery into WordPress, we now need something on the other end to handle the request and return something back to our page. For this, let’s create a method called handle_like().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
function handle_like()
{
    global $wpdb;
    $user_id = (int) $_POST['user_id'];
    $post_id = (int) $_POST['post_id'];
       
    if( !is_user_logged_in() )
        return false;
       
    if( !wp_verify_nonce( $_POST['_wpnonce'], 'nonce-register_like' ) )
        die( 'Go away, asshole!' );
       
    /*
        Here is where we do some sort of database operation to associate
        the Like of the given post with the user who performed the action
       
        Make sure you check for errors. In order to return data, you must
        echo something that the originating page can see. True or false
        only makes sense on this page and not back there.
           
        Typically, you'd output some sort of JSON, XML or plain text.
    */

    $meta_id = add_post_meta( $post_id, 'user_liked', $user_id );
    if( !$meta_id )
        echo "Like not recorded";
    else
        echo "Like recorded";
    exit;
}

In this method, it’s important that all data be sanitized to avoid security problems. I’m performing the most basic of data security here by casting the $_POST variables for the users ID and the post ID to integers.

We’re also checking to make sure the user is logged in. This is why using the built in WordPress Ajax API is actually kind of important. If you build your own Ajax handler, there’s no way to reliable tie in to WordPress to use other APIs like the User API.

Finally, make sure you verify the nonce so you know the request is coming from a legitimate source.

The three security procedures I just listed will largely prevent SQL Injection, ensure authenticated users and eliminate the possibility of Cross Site Request Forgery (CSRF) and generally should be used in all WordPress plugin development.

Simply though, the above method takes the post ID, the user ID and creates a new record in the postmeta table. On success, it will print a success method readable by the original sending page and vica versa on failure.

Note: You must use die() or exit() at the end of the method to make sure the Ajax response exits properly.

Tying the Handler into WordPress

Now that we have a handler method to do our bidding, we need to make sure WordPress knows about it so it routes Ajax requests to the proper place. To do this, we leverage the wp_ajax_{$action} hook.

Remember earlier, while building the jQuery Ajax request, I mentioned that an action POST variable had to be set? WordPress looks to this variable to create a dynamic hook that we can use our new Ajax callback to hook into.

1
add_action( 'wp_ajax_register_like', array( $this, 'handle_like' ) );

Because our action in the js() method was set to register_like, the hook WordPress creates dynamically is wp_ajax_register_like and we can use that to hook our Ajax handler onto.

Wrapping it all Together

Easy right? Use jQuery to send data, wp-admin/admin-ajax.php to receive the Ajax request and pass it on to an appropriate handler function, and send data back to the original page. On the receiving end, you can use normal means to handle the returned data as you wish.

You can download the full code used here at Github.

TUTORIAL: Adding an oEmbed Provider to WordPress

I don’t often write tutorials. I probably should. But normally it’s only when someone asks me something and I think, “Hey, self… you should write up how to do this”. As if a book wasn’t enough.

Last night I was at the Austin Web Holiday party, a gathering of some 15+ technical meetup groups cross-pollinating over beer and socializing. I was introduced to one guy (can’t remember his name!) who had built a video site and enabled it for oEmbed. He couldn’t understand why WordPress wouldn’t just automatically let users use his videos, like it does for YouTube, Vimeo, etc. The full list of default oEmbed providers are listed here.

WordPress doesn’t allow automatic use of oEmbed for security reasons. Otherwise, someone could build a video service stuffed with malicious code that could potentially access your database or create a man in the middle attack or worse. WordPress.com certainly doesn’t allow arbitrary oEmbed sites and the dot-org open source software doesn’t allow arbitrary stuff automatically. But it can be done, on the dot-org side, with a plugin. All it is a hook.

Here’s an example. If you want to register an oEmbed video site that is, say, at (randomly) http:/mysuperawesomevideosite.com and your videos are of the format http://mysuperawesomevideosite.com/video/*, it’s as simple as adding a function in your plugin (or more properly from a PHP perspective, a method in a class – but that’s a personal preference. The method/function should call the  wp_oembed_add_provider() function.

In it’s simplest form, all you have to do is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
class My_Plugin {

  var $oembed_endpoint;
  var $oembed_format;

  function __construct()
  {
    $this->oembed_endpoint = 'http://mysuperawesomevideosite.com';
    $this->oembed_format = 'http://mysuperawesomevideosite.com/video/*';

    $this->new_oembed();
  }

  function __destruct() {}

  function new_oembed()
  {
    wp_oembed_add_provider( $this->oembed_format, $this->oembed_endpoint );
  }

}

Then, to make this code work, just instantiate the class somewhere.

1
$my_plugin = new My_Plugin;

Voila!