How To Write Built-In Widgets for WordPress Themes

So I’ve been writing my own WordPress themes for a long time now, from scratch, since WordPress 1.5.1 was released. I’ve learned a lot during that time and still have a lot to learn. The next biggest WordPress adventure for me is to write a bona fide plugin. But in the meantime, I figure it’s time to start giving back to the community. Please note that I’m not MySQL or PHP expert. I have no formal training and everything is self taught or learned from the kind and helpful folks at WordPress dot org and the MU Forums.

I learned this a while back and it has been immensely helpful, especially if you don’t know how to quite write plugins just yet. I’m going to demonstrate how to integrate a custom built widget into your theme, so you won’t need a plugin. Unfortunately going this route will mean that the widget will be theme specific and not blog specific meaning that if you change your theme, you will have to apply the same hacks to retain your custom widget(s). The added advantage of this is that you won’t have to worry about activating a number of plugins, you just have to add them in the Design menu.

Mission

We want to achieve this
We want to achieve this

I’m going to do a fairly simply widget and from these directions you can get more fancy and complicated. Currently the default WordPress install includes, under Design > Widgets, an Archives widgets. Once you’ve added it to your sidebar, it has 3 customizations: name, show post counts, and display as a drop down. This isn’t terribly useful if you have 3 years worth of blog entries because it will display all 3 years worth of entries. Sure, you could display it as a drop down, but what if you didn’t want to? What if drop downs don’t match the design of your theme? We also obviously don’t want the full list, let’s say we only want 1 year worth of archives links displayed at any given time with a link at the end that will take us to the archives page where the master list will be. Easy, we make our own widget using the available WordPress hook:

<?php wp_get_archives(); ?>

Directions

It’s important to remember that we need to add some arguments so that it will only display 1 year, no post counts, and month. So now our code becomes:

<?php wp_get_archives('type=monthly&limit=12&show_post_count=0'); ?>

If you would like the post count to show, change show_post_count=0 to show_post_count=1. The limit=12 ensures that it will only display 12 entries or 1 year worth of month archives.

1. In your theme folder, there may or may not be a functions.php file. If there isn’t, we create it. If there is, we modify it. Let’s first assume that the functions.php files does exist. If it doesn’t I’ll show you in the next post how to create one. Most of the new themes should have a functions.php file because this is where the theme is widgetized. If you theme does not support widgets, most likely it is an older theme without a functions.php file.

Open the functions.php file with a text editor like NotePad or TextWrangler. At the very beginning, you should see something similar to:

Don’t worry if it’s not exactly like above. I tend to leave myself notes so I remember what does what and it should be helpful for you to follow along also.

2. Right after, on the next line, enter:

What line 15 does is basically check to see if the sidebar widget function is available and if it is (line 17) activate Simple Archives as a sidebar widget. Now you can call your widget anything you want; just make sure the register name next to it is identical but in lowercase with an underscore. Example: ‘Cool Widget’, ‘cool_widget’. Notice how everything interacts with each other. On line 26, you now are calling the new function you created on line 17 and executing a set of code on line 26-36.

3. You may have to slightly alter the contents of line 34 according to where you created your archives page at. If you don’t know how to create an archives page, I suggest you do some reading up on page templates.

4. Upload the new modified functions.php file to your theme on your web server and if everything is done correctly, you will find under Design > Widgets, a new widget called “Simple Archives” or whatever you named it.

5. If when after you uploaded the functions.php file and your website comes up blank, there is an error somewhere in the code. Go back and double check the functions.php file.

Conclusion

Now this is a very basic example of using the functions.php file to custom create widgets. With a bit of trial and error, you can create virtually any type of widget you like as complex or simple as you like. You can further expand on this Simple Archives widget by adding additional fields such as title of Simple Archives for display, check boxes to display month, day, or year, how many entries to show, and much more. When I have more time, I’ll delve more into those topics and create an intermediate how-to that will expand upon this. In the meantime you can study the default widgets file located at wp-includes/widgets.php and see how it’s done with the archives widget and reverse engineer it.

You can also add as many of these custom widgets as you like. I used the same principle with the wp_list_categories(); functions and my FeedBurner box in my sidebar.

2 thoughts on “How To Write Built-In Widgets for WordPress Themes”

Leave a Reply

Your email address will not be published. Required fields are marked *