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()
orregister_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!