Lonewolf Designs

Wordpress plugins are pieces of addon code that extend the functionality of Wordpress, either behind-the-scenes or extra visual code. Widgets allow these code segments to be quickly and easily added to predefined sidebars on most themes.

Before Wordpress version 2.0, these extra visual plugins had to be hand coded into the theme template, so a knowledge of PHP is required. In version 2.0 they introduced "Widgets" which wrap around a plugin and allow a non code editing method for incorporating into a theme using sidebars and a drag and drop interface.

This tutorial covers creating a Widget, creating a plugin widget, adding sidebars to a theme, and upgrading a non-widget plugin.

Creating a Simple Wordpress Plugin

You can use this as a code snippet for your projects. I am going to create a simple plugin that does nothing but display "Hello World". I'll leave the actual functionality of the plugin to you

Create a new php file in your plugin directory called my-hello-world.php, and type the following plugin code:

The lines inside /* and */ are used by Wordpress to find out about the plugin. We have one function called sampleHelloWorld which does exactly that.

Now, traditionally we would have had to open up the sidebar of the theme you are using, find the location of where you want the Hello World displayed, and hard code the function in. Upload to the server and test. If for some reason there is a problem with your plugin (or a third party plugin) then your site would almost certainly stop working. Changing the location from the left to the right sidebar means editing both files accordingly. This isn't very good.

Widgets

Widgets take away the need for editing the sidebar files of a theme and allow for a drag and drop interface in the admin panel. Lets have a look at how we can wiget enable our plugin.

The first function here is what will be displayed on the sidebar when its set-up correctly. Notice that we are calling on our old function. This is upgrading the existing plugin to be widget enabled. You can if you like replace the function call with the function statements and combine the two functions.

The second function is called by Wordpress when the plugin is activated. It calls a Wordpress function that will register a new widget which will be called "Hello World" which will call our new widget function.

Add action just tells Wordpress to call myHelloWorld_init when the plugin is loaded.

Enhancements for Theme Compatibility

While this widget will function fine, we can make some improvements to enable greater theme compatibility – not everyone uses the same themes as you test on.

Wordpress will pass parameters to your widget, which contain information about the sidebar and the CSS classes. We should process these parameters and output the correct tags, or you risk breaking some themes.

The first thing we need to do is change our sampleHelloWorld function so that it will accept parameters, then to process these parameters into variables. This is done using the extract function.

These two lines will allow us to reference some variables and output correct html structure for the theme being used. The most important variables are before_widget, after_widget, before_title and after_title. Previously we have surrounded the widget title with a hard coded H2 tag with a css class widgettitle, but many themes do not support these tags. They may use a div, or a h1 or a span, so we need our widget to be flexible.

Testing your Plugin

If you check your plugins page now, you should now have a new plugin listed called Hello World which you can activate. On the Presentation tab, select widgets, and you should see your new widget available to be dragged onto a sidebar. Save your changes and admire your new work.

Wordpress Widget listed as installed

Stop! My Theme Doesn't Support Widgets!

If your theme does not have widget enabled sidebars, this little tutorial will help make it widget enabled. I am using a very basic sidebar theme, most sidebars are a little more complex than this.

The first of these lines does an if else statement, if we have a sidebar function call it otherwise we do the existing hard coded sidebar.

The second line (endif) tells the if statement where the hard coded sidebar ends. Anything between the first and second lines will be shown if widgets are disabled or no widgets are assigned to the sidebar.

Before you can add a widget to this sidebar, we need to make Wordpress aware of it by registering it.

Open, or create, functions.php in your theme folder, and find (or add) a line like this:

<?phpif(function_exists('register_sidebars')) register_sidebars(1);?>

Where the parameter to register_sidebars is the number of sidebars defined in your theme. You can have any number of sidebars. Now you will be able to add widgets to your sidebar.

Should you wish to configure the elements that will appear before and after a widget, or the tags that a widget title will appear in, you can setup the options array and pass it to the register_sidebar function.

53 Responses to “How To Create Wordpress Widgets”

Nice tutorial. After doing this over and over again I created to tool to take the tedium out of creating WordPress Widgets. Take a look over at http://www.widgetifyr.com and let me know what you think.

Great post , You’ve really hit the nail on the head, I just don’t understand why people quite get it. I’m not for sure how many people I’ve talked to concerning this very thing in the past month, and they just can’t get it.

I’m trying to create a sidebar widget using the code at http://www.stopie6.com/widgets.html (Simple Text Message), but can’t work out which code to change in your example, and where to put the code in from the link? How would the php file handle that if statement?

Hello sir, i have a question. How can i create a title field for the widget so the user can rename it with whatever they like. I really blind about php and Wordpress coding. So could you tell me the code and where to place it. Don’t worry i can figure it out. Thanks:).

Is that supposed to be an actual less than bracket, making an opening php tag?

And, I thought when I started reading this that the Hello World example was just to show you the initial step. What is the purpose of it being called later in the function? I thought for an instant maybe we were supposed to put HTML in there, but you have the widget tags to use what the user theme has already…

You are correct about the php tag, it got converted to html chars along the way

Not sure quite what you mean about calling the function? I guess your referring to the call to sampleHelloWorld() from within widget_myHelloWorld($args)? This is just to keep the different sections code separate. You can replace sampleHelloWorld() with whatever you wish.