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 widgets@wordpress.com 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 widgets@wordpress.com for review. We might put them up for everyone to use on WordPress.com. You could be internet famous!
Follow

Get every new post delivered to your Inbox.

Join 7,750 other followers