Automattic

Widgetizing Plugins

How do I develop new widgets?

We included the Google Search and del.icio.us plugins as samples to show you what a widget plugin might look like. The Google Search widget is commented within inches of its life, so consider that your tutorial. Additionally, there are a few guidelines to follow:

  • Don’t execute any code while the plugin is loaded. Use the plugins_loaded hook or you risk fatal errors due to undefined functions, or missing the boat completely because your plugin loaded before the one it depends on.
  • Use register_sidebar_widget($name, $callback) to add your widget to the admin interface.
  • Follow this template: 
    function widget_myuniquewidget($args) {
    extract($args);
?>
        <?php echo $before_widget; ?>
            <?php echo $before_title
                . 'My Unique Widget'
                . $after_title; ?>
            Hello, World!
        <?php echo $after_widget; ?>
<?php
}
register_sidebar_widget('My Unique Widget',
    'widget_myuniquewidget');
  • Don’t leave out $before_widget, $after_widget, $before_title, or $after_title by accident. They are required for compatibility with various themes.
  • Name your widget and its functions carefully. Those strings will be used as HTML attributes and you don’t want to cause identical id’s in a single HTML document.
  • Localization is done internally to preserve the HTML id attribute. If you want your widget name localized with a textdomain, pass array($name, $textdomain) instead of $name.
  • To accommodate multi-widgets (e.g. Text and RSS) you can also pass a replacement value with the name: array($name_as_sprintf_pattern, $textdomain, $replacement). See the source.
  • You may use the variables mentioned above in different ways, or neglect them in some circumstances. Some widgets may not need a title, for example. Some widgets will use the $before_widget and $after_widget several times, or as arguments to tell another template tag how to format its output.
  • Optionally, use the following syntax to add a configuration page to the admin. Your callback will be used within the main form, so you must not include any <form> tags or a form submit button. 
    register_widget_control($name, $callback
        [, $width [, $height ]] );
  • Namespace your form elements so they don’t conflict with other widgets.
  • Each widget must have a unique name. You can replace an already-registered widget by registering another one with the same name, supplying your own callback.
  • Any extra arguments to register_sidebar_widget() or register_widget_control() will be passed to your callback. See the Text and RSS widgets for examples.
  • Any widget or control can be “unregistered” by passing an empty string to the registration function.
  • There are probably some undocumented functions. You are encouraged to read the source code and see how we’ve created the standard widgets using these functions.
  • Please test your widgets with several themes other than Classic and Default (they both use the ul/li/h2 markup).
  • Please audit the security of your widgets before distributing them.
  • If you would like your widget to be considered for use on WordPress.com, send a link (no attachments please) to [email protected] and we’ll have a look.

What else can I do with Widgets?

You have no idea how glad we are that you asked that. Here are a few ideas:

  • Write a theme that includes a special widget to set it apart from the others.
  • How about this for a special widget: a WordPress loop to show asides.
  • Register a replacement widget that buffers the original widget and transforms it somehow.
  • Remember that a “sidebar” is really just a name for a list. It can be displayed vertically or horizontally.
  • Remember that a “widget” is really just a name for a configurable code snippet. It can be invisible or it can be absolutely positioned.
  • Use the id and class attributes of any or all widgets in scripts to animate your sidebar.
  • Heck, use script.aculo.us or dbx (included with WordPress) to make your widgets draggable or even collapsible. Ain’t scripting sweet?
  • Remember that the widget control API is just for convenience. You can always set up your own admin page instead.
  • Support your users and get feedback so you can improve your widget. Put a link to your email or your site at the bottom of your widget control.
  • Send a link to your widgets to [email protected] for review. We might put them up for everyone to use on WordPress.com. You could be internet famous!