WordPress.org

Developing 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. 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 this syntax to add a configuration page to the admin: registerwidgetcontrol($name, $callback [, $width [, $height ] ]); Your callback will be used within the main form, so you don't have to worry about <form> tags or a button to submit the form.
• 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 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.