Codex tools: Log in / create account
Languages: English • 日本語 • 简体中文 • (Add your language)
Contents |
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.
The Wordpress widget API is located in wp-includes/widgets.php.
|
|
Note: It is advised not to 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().
These functions are used to make a theme work with sidebars.
register_sidebars( $count, $args );
Registers one or more sidebars to be used in the current theme. Most themes have only one sidebar. For this reason, the count parameter is optional and defaults to one.
The $args parameter will be passed to register_sidebar() and follows its format, with the exception of the name, which is treated with sprintf() to insert or append a unique number to each sidebar if count is plural.
For example, the following line will create sidebars name "Foobar 1" and "Foobar 2":
register_sidebars(2, array('name'=>'Foobar %d'));
register_sidebar( $args );
The optional $args parameter is an associative array that will be passed as a first argument to every active widget callback. (If a string is passed instead of an array, it will be passed through parse_str() to generate an associative array.) The basic use for these arguments is to pass theme-specific HTML tags to wrap the widget and its title. Here are the default values:
'before_widget' => '<li id="%1$s" class="widget %2$s">', 'after_widget' => "</li>n", 'before_title' => '<h2 class="widgettitle">', 'after_title' => "</h2>n"
The only times you might need to call this function instead of register_sidebars are when you want to give unique names to sidebars, such as "Right Sidebar" and "Left Sidebar", or when they should be marked up differently. The names only appear in the admin interface but they are also used as an index for saving the sidebar arrangements. Consequently, sidebars can have their arrangements reused and overwritten when another theme is chosen that uses the same names.
The default before/after values are intended for themes that generate a sidebar marked up as a list with "h2" titles. This is the convention we recommend for all themes and any theme built in this way can simply register sidebars without worrying about the before/after tags. If, for some compelling reason, a theme cannot be marked up in this way, these tags must be specified when registering sidebars. It is recommended to copy the id and class attributes verbatim so that an internal sprintf call can work and CSS styles can be applied to individual widgets.
dynamic_sidebar( $sidebar );
This function calls each of the active widget callbacks in order, which prints the markup for the sidebar. If you have more than one sidebar, you should give this function the name or number of the sidebar you want to print. This function returns true on success and false on failure.
The return value should be used to determine whether to display a static sidebar. This ensures that your theme will look good even when the Widgets plug-in is not active. Along with a sanity test to prevent fatal errors, here is the recommended use of this function:
<ul id="sidebar">
<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
<li>{static sidebar item 1}</li>
<li>{static sidebar item 2}</li>
<?php endif; ?>
</ul>
If your sidebars were registered by number, they should be retrieved by number. If they had names when you registered them, use their names to retrieve them.
Widget development has become easier since version 2.8. To create a widget, you only need to extend the standard widget class and some of it's functions.
That base class also contains information about the function that must be extended to get a working widget.
class My_Widget extends WP_Widget {
function My_Widget() {
// widget actual processes
}
function widget($args, $instance) {
// outputs the content of the widget
}
function update($new_instance, $old_instance) {
// processes widget options to be saved
}
function form($instance) {
// outputs the options form on admin
}
}
register_widget('My_Widget');
This sample code creates a Widget named FooWidget that has a settings form to change the display title.
/**
* FooWidget Class
*/
class FooWidget extends WP_Widget {
/** constructor */
function FooWidget() {
parent::WP_Widget(false, $name = 'FooWidget');
}
/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
?>
<?php echo $before_widget; ?>
<?php echo $before_title
. $instance['title']
. $after_title; ?>
Hello, World!
<?php echo $after_widget; ?>
<?php
}
/** @see WP_Widget::update */
function update($new_instance, $old_instance) {
return $new_instance;
}
/** @see WP_Widget::form */
function form($instance) {
$title = esc_attr($instance['title']);
?>
<p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p>
<?php
}
} // class FooWidget
This sample widget can then be registered in the widgets_init hook:
// register FooWidget widget
add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));
That's all. You will automatically get a multi-widget. No special tweaks needed any longer for that.
More information is available in the version information.
The Google Search widget which was included in the deprecated (i.e. not needed since WordPress 2.2) original widget plugin is commented within inches of its life, so consider that your tutorial. Additionally, there are a few guidelines to follow:
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');
Important: To use the above in a plugin, wrap it with:
function widget_myuniquewidget_register() {
--the above goes here--
register_sidebar_widget('My Unique Widget','widget_myuniquewidget');}
add_action('init', widget_myuniquewidget_register);
register_widget_control($name, $callback [, $width [, $height ]] );
You have no idea how glad we are that you asked that. Here are a few ideas:
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.