Creating a Widget with the WordPress Widget API
The first thing to do is decide where this widget is going to be used. If it’s part of your theme you can just place it in your themes functions file, or you can place it in a separate file and include it into your functions file for neatness.
If it is part of a plugin you can just place it inside your plugin file. If you are just making a widget and you don’t want to alter your theme, you can always make a plugin that adds the widget. To make a plugin just create a brand new file using notepad, notepad++ or another text editor (not a word processor) with the following at the very top:
|
1 2 3 4 5 6 7 8 9 |
<?php /* Plugin Name: My Widget Plugin URI: http://my-website.com Description: Adds My Widget. Author: My Name Version: 1.0 Author URI: http://my-website.com */ |
What Widget Are You Making?
Okay, now that we’ve covered the different methods of adding a widget let’s get to how to create one. I’m going to show you how to create a random image gallery widget. This widget would be good for a photography site or any website that focuses on images. It shows one random image from the media library in your sidebar. Here is what it could look like with a little bit of styling.
Gallery image © NBC Studios. Used for illustrative purposes, no infringement intended.
Remember you can make this widget do whatever you’d like, this is just an example I’m using to show you how a widget is created.
Object Oriented Programming
The new WordPress Widget API is based around extending a class. This is part of a method of coding called OOP (Object Oriented Programming). Let’s take a look at what it looks like:
|
1 2 3 4 5 |
class My_Gallery_Widget extends WP_Widget { } add_action('widgets_init', create_function('', 'return register_widget("My_Gallery_Widget");')); |
That is the basics of extending a class. WP_Widget is the class defined by WordPress and you extend it with your own widget. The last line tells WordPress to register the widget using a quick anonymous function.
Creating The Widget
Okay. Let’s take a look at the entire widget code and then we’ll go through it.
|
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 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
if( get_bloginfo('version') >= '2.8' ) { class My_Gallery_Widget extends WP_Widget { function My_Gallery_Widget() { parent::WP_Widget(FALSE, $name = 'My Gallery Widget'); } function widget($args, $opts){ echo $args['before_widget']; echo $args['before_title'] . 'Gallery Widget' . $args['after_title']; if($opts['lateRand']) $order = '&orderby=rand'; else $order = ''; $images = get_posts( 'post_type=attachment&numberposts=1'.$order ); if($images) : foreach($images as $att) : echo wp_get_attachment_image($att->ID, 'thumbnail'); endforeach; endif; echo $args['after_widget']; } function update($new_opts, $old_opts) { return $new_opts; } function form($opts) { $lateRand = esc_attr($opts['lateRand']) ?> <p> <label for="<?php echo $this->get_field_id('lateRand'); ?>"> Latest or Random: <br /> <small> (Check to show Random, uncheck to show Latest) </small> <input class="widefat" id="<?php echo $this->get_field_id('lateRand'); ?>" name="<?php echo $this->get_field_name('lateRand'); ?>" type="checkbox" <?php if($lateRand == TRUE) echo 'checked="checked"'; ?> /> </label> </p> <?php } } add_action('widgets_init', create_function('', 'return register_widget("My_Gallery_Widget");')); } |
Okay. First we check the WordPress version is over 2.8 which is when the WordPress Widget API was introduced. This isn’t needed if you know the version installed will always be over 2.8, but it’s a good habit to get into.
We extend the Widget class as we mentioned earlier. The first function is also known as the constructor and is ran when the class is instanced/ran. In this case it calls the parent constructor which is the WP_Widget class we extended, it also sets the name (Human/nice Name) of our widget at the same time.
Next is the widget function. This function defines what should be output by the widget. In my case I grab an attachment from the media library. You should add in whatever you want your widget to do here. It’s important to note that it pulls in two parameters. The first contains standard parameters passed by WordPress. The second contains the options saved by the widget, if it has any.
Next up is the update function. This just passes the newly saved options on to WordPress to be saved into the database. If you want to do anything every time the widget’s options are updated feel free to add it here. Otherwise you can just leave this bit as is.
Lastly is the form function. This is where you output the form to allow options to be saved for your widget. You need to escape your options so they are safe to use in the form HTML. You can do them one by one, or you can run $opts through a foreach and then run esc_attr() on each one. There is no need to output a form as your output from this function will be placed inside one created by WordPress.
The idea is just to output form fields as you need them. Feel free to copy the way I’ve laid my fields out if you like. I’ve used a checkbox here, but you can use text fields too. here is an example:
|
1 2 3 4 5 6 |
<p> <label for="<?php echo $this->get_field_id('my_field'); ?>"> My Fields <input class="widefat" id="<?php echo $this->get_field_id('my_field'); ?>" name="<?php echo $this->get_field_name('my_field'); ?>" type="text" value="<?php echo $my_field; ?>" /> </label> </p> |
The last line as I mentioned earlier, registers the widget with WordPress.
That’s it. You should now have a new widget on your widgets page. Drag it over to the desired sidebar & you should be able to use it as you would any other widget.
If you have any questions, or you need any help please let me know via the comments. If you would like any hands on help I’m available to hire, check out my Hire Me page for more or email me via that page for a customized quote.
2 Comments
Zack Brady
Thanks, gave me a good start. Need to find some stuff on saving the options properly now though. Perhaps ad that bit. I would think that most people would need that.
Paul Robinson
Hi Zack,
I’m not sure I understand? The widget API does not require any special instructions for saving the options. The options for the widget are saved by WordPress in the
update()method. If you need to do anything to the data gathered by the options you can do it there before it is saved. If you just want to save it (as is the case in this tutorial) just return the array with the options contained in it.I’ve just tried the code Widget code here in WordPress 3.5 & it is still working perfectly (and saving the options). Are you having trouble getting the options to save?