WordPress:Plugins/WordPress Widgets Api

Widgets API

This page contains the technical documentation of the WordPress Widgets API (Application Programming Interface). The intended audience for this information includes WordPress theme authors, plug-in authors and anyone who would like to write a stand-alone widget. This document assumes a basic understanding of PHP scripting.

A widget is a PHP function that echoes string data to STDOUT when called. To turn such a PHP function into a Wordpress Widget it must be registered as such. This is done using a PHP callback (a Pseudo-Type in PHP documentation) that is registered by a wordpress widget API function.

register_sidebar_widget($callback);

The Wordpress widget API is located in wp-includes/widgets.php. It is advised to not use the functions starting with wp_ as these could change in subsequent releases. This is why we use register_sidebar_widget() instead of wp_register_sidebar_widget().

Function Reference

Sidebar Functions register_sidebars register_sidebar unregister_sidebar dynamic_sidebar is_dynamic_sidebar

Widget Functions register_sidebar_widget unregister_sidebar_widget register_widget_control unregister_widget_control is_active_widget

Developing New Widgets

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!

Widgets - One or many

Widgets can be coded so that they can exist one time or they can exist multiple times. Wordpress is doing the work for you to instantiate your Widget multiple times if you follow some rules.