WP plugin: My Widget – example WordPress widget

posted on April 6, 2006

There’s a funky new WordPress plugin, WordPress Widgets, driving a fair percentage of the WP community to both ends of the enthusiasm spectrum. But love it or hate it, it’s here to stay, and you can pretty much expect to see it end up in the WordPress core in a not to distant future version.

With the appetizer out of the way, let me get to the meat of the post: a thread on the WordPress support forums lead me to the decision the example dev material provided is a bit weak, especially for the neophyte plugin writer. So in the interest of avoiding dozens of similar yelps for guidance over the months to come, I tore through the widgets that tag along with WordPress Widgets (the Google and del.icio.us ones) and after an hour had merged, molded and abused them into an example widget (with lots of explanatory comments!). And now I’m passing that work along to anyone who wants it.

The widget can be considered useful, to boot.

To install, download my-widget.php from here, upload that to your wp-content/plugins/ directory, and activate My Widget under plugins. It’s one of those you should already know this bits of wisdom, but you also need to have WordPress Widgets installed and activated as well, otherwise My Widget is little more than a piece of chocolate cake served up to a coma victim.

If you just want to use the My Widget widget, here’s what it does: when you add it on your sidebar by default it displays “My Widget” for the header (or title) and “Hello World!” for the text. Thankfully these can be edited through the widget’s control.

My Widget control

The little red arrow in the image above points at the control button on the widget bar. Click it and the following pops up:

My Widget options

Just add your own personal title and text, then close the My Widget dialog box and click Save Changes to, well, save the changes. Feel free to use it to display a welcome message or a note about yourself. I’m sure you can think of something to do with it.

So you see you can put it to use, but it’s main purpose is to provide a learning tool or framework for building your own widget. For that reason I’ve sprinkled comments liberally throughout the source code. However if anything is not clear, or if you have suggestions for making My Widget more useful, let me know.

Author: Kaf Oseo
Categories: WordPress
Comments: (33) · Leave a comment · Comments RSS2

jan
Comment » April 15, 2006 @ 3:01 pm

hi, i think there’s an error in your code, the update of the options in the control fuction if the options don’t match the newoptions should only be done if the form was submitted, else the options get always updated with empty values – at least that’s what happens on my site!

cheers,
/jan

Joey
Comment » October 14, 2006 @ 7:13 am

Hi Kaf,
Many thanks for the excellent example. With it I was able to knock together my own widget in about 30 minutes!


J

Peter Giger
Comment » December 31, 2006 @ 4:34 pm

Thanks for the good work!

matt
Comment » March 5, 2007 @ 11:51 pm

You need to put the update_option inside the submit section or else whenever you load the widget page it erases all your widget setting.

Indian Sunburn
Comment » May 5, 2007 @ 12:28 am

Cool, thanks for posting this. It has been a big help in my widget adventures.

Stefan Wagner
Comment » June 11, 2007 @ 10:29 am

Code for the option update should look like this:

// This is for handing the control form submission.
if ( $_POST['evterm-submit'] ) {
// Clean up control form submission options
$newoptions['title'] = strip_tags(stripslashes($_POST['evterm-title']));

// If original widget options do not match control form
// submission options, update them.
if ( $options != $newoptions ) {
$options = $newoptions;
update_option('widget_evterm', $options);
}
}

Bye Stefan

Diane Clancy
Comment » June 16, 2007 @ 10:17 am

Thank you very much for this! Maybe I can get figured out now.

~ Diane Clancy
http://www.dianeclancy.com/blog

Jonah
Comment » July 20, 2007 @ 4:03 pm

Thanks much for this sample but like others have mentioned there are problems with the widget info disappearing when reloading the widgets page. I believe I’ve found a simple solution for this – I just checkout some other stock widget code to see what they had in the submit section and here is what I got:

Your code:
// Collect our widget’s options.
$options = get_option(‘widget_mywidget’);

// This is for handing the control form submission.
if ( $_POST['mywidget-submit'] ) {
// Clean up control form submission options
$newoptions['title'] = strip_tags(stripslashes($_POST['mywidget-title']));
$newoptions['text'] = strip_tags(stripslashes($_POST['mywidget-text']));
}

New code that will ensure saved options are loaded:
// Collect our widget’s options.
$options = $newoptions = get_option(‘widget_artistofthemonth’);

// This is for handing the control form submission.
if ( $_POST['mywidget-submit'] ) {
// Clean up control form submission options
$newoptions['title'] = strip_tags(stripslashes($_POST['mywidget-title']));
$newoptions['text'] = strip_tags(stripslashes($_POST['mywidget-text']));
}

The only change is in the ‘Collect our widgets options’ section. It looks like all that was needed was to make $options and $newoptions to equal the options currently stored for the widget.

Thanks again though for the sample. Now that I’ve got it working it’s very nice…

Andy Bailey
Comment » August 29, 2007 @ 1:21 pm

OMG! thanks Jonah! I made my first widget based on this code and although it worked like I wanted (finally!) , it would lose the options when I reloaded the widgets page. aha! the end of hours of head scratching!

Bruno
Comment » September 6, 2007 @ 1:11 pm

This plugin is not working for wordpress 2.3 beta 2. I can’t figure out why though. It’s not retaining the saved options :-)

Paul Buchhorn - Online Marketing News
Comment » October 2, 2007 @ 4:58 am

i love this tool in my wp-blog. its realy simple to handle this one.

Tony
Comment » October 30, 2007 @ 5:04 pm

Thank you so much for a simple example! I was having a very hard time finding a simple example that I could build on.

Duncan
Comment » November 27, 2007 @ 7:26 pm

I just want to echo Tony’s comment. Thanks very much for the easy-to-follow example, and well-commented code. Makes it a snap for a relative beginner to pick up.

John Hunter
Comment » November 28, 2007 @ 1:39 pm

Thanks for a great example. I too had the problem with options being lost when the widget admin page was loaded. The problem is that options are saved even when there has been no submission. The code that checks for changed settings should be in the block that is called when the form is submitted.

Change this:

// This is for handing the control form submission.
if ( $_POST['mywidget-submit'] ) {
    // Clean up control form submission options
    $newoptions['title'] = strip_tags(stripslashes($_POST['mywidget-title']));
    $newoptions['text'] = strip_tags(stripslashes($_POST['mywidget-text']));
}

// If original widget options do not match control form
// submission options, update them.
if ( $options != $newoptions ) {
    $options = $newoptions;
    update_option('widget_mywidget', $options);
}

To this:

// This is for handing the control form submission.
if ( $_POST['mywidget-submit'] ) {
    // Clean up control form submission options
    $newoptions['title'] = strip_tags(stripslashes($_POST['mywidget-title']));
    $newoptions['text'] = strip_tags(stripslashes($_POST['mywidget-text']));

    // If original widget options do not match control form
    // submission options, update them.
    if ( $options != $newoptions ) {
        $options = $newoptions;
        update_option('widget_mywidget', $options);
    }

}

DM
Comment » April 30, 2008 @ 8:17 am

Dear all,

I am searching a widget that can do this: for-single-category draw an area with the latest post with icon-image and a n char of text + “more…” link. Under this main for-single-category news, the list of other news with title and link.

Variable width to fit the sidebar, 2 config options (selected from a drop-down menu the existing category; select the number of chars to show; the number of latest title post for that category to show).

Any tips? Name? Link?

Thank you in advance (please, answer me by mail)

Jens Erat
Comment » June 12, 2008 @ 3:00 pm

Works great and the comments helped me a lot. First widget (and it’s even working!) created in less then an hour.

Thanks a lot,
Jens

PS: John Hunters solution should be really included in the original code ;)

Hendry Lee
Comment » December 16, 2008 @ 4:39 am

Thanks, I am currently developing a plugin and I’d like the add a widget. This helps me get started easily.

Marilyn
Comment » February 5, 2009 @ 2:35 pm

Thank you for this tutorial, it helped me get started quickly!

Robert
Comment » March 2, 2009 @ 8:24 pm

This is a very helpful tutorial. I’ve been able to do some interesting things with it after just a couple of hours.

But one thing I hope you can help with. Is it possible to put a widget like this on to the Dashboard? There are some plugins to manage Dashboard widgets, but they don’t work with 2.7.

I’ve been looking around to find how the widgets get put into the pull-down box where you can check which ones should be displayed. But I can’t find that either.

Any help?

Nick
Comment » April 22, 2009 @ 10:18 am

Thanks a lot! The source code was very helpful!

 

* Required field (e-mail is not published). Breaks and paragraphs are automatic. HTML allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>