TekTok

A friend of mine recently asked me to take a look at some code that he’d written and see if I could get it to work. I’m not going to tell you what was wrong with his code, but I will tell you that in the process of troubleshooting the code I got the idea for this post. Let’s look at how we can make a full, working WordPress sidebar widget.

There are at least two ways to make a sidebar widget in WordPress. The first is to create a file in the “wp-content/plugins” directory and activate the widget as a regular plug-in, and second is to write the code in the “functions.php” file included with your WordPress theme. I have used both and they both work just fine. I will use the first method here just because I regard sidebar widgets to be WordPress plugins.

I encourage you to work through this so that at the end you will have your fully functional WordPress sidebar widget. I’m going to call our widget “Your Lucky Number.” That is, the widget will pick a random number from a certain interval and display it to the reader.

So, look up the “wp-content/plugins” directory in your WorPress installation and in it create a new “lucky_number_widget” directory, which will contain a “lucky_number_widget.php” file, as you see in the photo below.

The file that you just created will contain all the code needed for our little widget. At the top of this file put the following code:

<?php
/*
Plugin Name: Lucky Number Sidebar Widget
Plugin URI: http://tektok.romagazin.net
Description: This widget picks a lucky number
Author: Your name here
Version: 1.0
Author URI: http://tektok.romagazin.net
*/
?>

In PHP, that’s called a comment block. That is, a block of text, between “/*” and “*/”, that has no meaning in PHP; it is only meaningful to humans. However, that kind of comment block, placed at the top of a PHP file, which resides in the “plugins” directory, has a very important significance to the WordPress platform. It tells WordPress that this file contains a plugin for the platform. As a consequence, WordPress will give you an opportunity to activate the plugin in the administration panel. If you don’t put this comment block as it appears in the above code, you will not be able to activate the plugin, therefore you won’t be able to use it. After you’ve saved the file, go to your admin control panel and click on “plugins;” you should see something similar to this picture:

OK, now it’s time we created the code that drives our widget. Put the following code right below the comment block:

function lucky_number_widget($args){
extract($args);

echo $before_widget;
echo $before_title . 'Your lucky number is:' . $after_title;

echo '<p style="font-size: 5em">' . rand(1, 20) . '</p>';
echo $after_widget;
}

In the above code: line 01 defines the function that will be called every time our WordPress widget is displayed in our blog. Line 02 is a little tricky for those who are new to PHP. Please read about the PHP extract function if you need to learn about it. To keep this tutorial short, I will only say that when the widget has to be displayed in the sidebar, WordPress calls our function with an associative array as parameter ($args). This array has the keys before_widget, after_widget, before_title and after_title and their corresponding values are string representations of HTML tags. extract transforms the key-value pairs in actual PHP variables, just as we would define $var = ’some string’;. The rest of the code is simple: it just echoes those values in the order they are meant to be echoed. Line 07 displays a random number between 1 and 20 inclusive within a HTML paragraph. That’s your lucky number!

Activate the plugin

Having coded all the functionality of our widget, we now have to write a function that WordPress will call when it loads the active plugins. This function will register our sidebar widget with the WordPress platform, so that it appears in the “Available Widgets” list under “Design->Widgets” menu.

function init_lucky_number_widget(){
//this function is called when WordPress loads the plugins
register_sidebar_widget('Lucky Number Widget', 'lucky_number_widget');
}

Just drop the above code in our file right below the lucky_number_widget() function. Read more about register_sidebar_widget().

One more line of code and then you’ll be able to see results. Under the function init_lucky_number_widget() type the following line of code:

add_action('plugins_loaded', 'init_lucky_number_widget');

Now save the file and go to your WordPress control panel. Click on “plugins” and then click “Activate” for “Lucky Number Sidebar Widget.” Click on “Design” and then on “Widgets” under it. You should see something like this:

Click the “Add” link next to its name and look to the right in the “Current Widgets” list. After you arrange it in the position you want, you should see something like this:

Click “Save” under the list. If you have a widgetized WordPress theme, you should see your widget appear on the sidebar of your blog. It should appear similar to how it appears on the sidebar of this blog; that’s your lucky number. If you don’t know what to do with it, look at my lottery widget and maybe it’ll help you hit the jackpot :-).

Congratulations! You’ve just created your first working WordPress sidebar widget. Next time, we will look at how to enhance it. We’ll write the code that allows us to modify the range of the lucky number or maybe something else. Until then, drop me a comment; tell me how it went. If you encountered problems, by all means, throw them my way. We’ll get it working!