Codex tools: Log in
Languages: English • Español • 日本語 • 中文(简体) • (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 object that echoes string data to STDOUT when its widget() method is called.
The WordPress Widget API is located in wp-includes/widgets.php.
|
|
To create a widget, you only need to extend the standard WP_Widget class and some of its functions.
That base class also contains information about the functions that must be extended to get a working widget.
The WP_Widget class is located in wp-includes/widgets.php.
class My_Widget extends WP_Widget {
public function __construct() {
// widget actual processes
}
public function widget( $args, $instance ) {
// outputs the content of the widget
}
public function form( $instance ) {
// outputs the options form on admin
}
public function update( $new_instance, $old_instance ) {
// processes widget options to be saved
}
}
The widget can then be registered using the widgets_init hook:
add_action( 'widgets_init', function(){
register_widget( 'My_Widget' );
});
This sample code creates a Widget named Foo_Widget that has a settings form to change the display title.
/**
* Adds Foo_Widget widget.
*/
class Foo_Widget extends WP_Widget {
/**
* Register widget with WordPress.
*/
public function __construct() {
parent::__construct(
'foo_widget', // Base ID
'Foo_Widget', // Name
array( 'description' => __( 'A Foo Widget', 'text_domain' ), ) // Args
);
}
/**
* Front-end display of widget.
*
* @see WP_Widget::widget()
*
* @param array $args Widget arguments.
* @param array $instance Saved values from database.
*/
public function widget( $args, $instance ) {
extract( $args );
$title = apply_filters( 'widget_title', $instance['title'] );
echo $before_widget;
if ( ! empty( $title ) )
echo $before_title . $title . $after_title;
echo __( 'Hello, World!', 'text_domain' );
echo $after_widget;
}
/**
* Sanitize widget form values as they are saved.
*
* @see WP_Widget::update()
*
* @param array $new_instance Values just sent to be saved.
* @param array $old_instance Previously saved values from database.
*
* @return array Updated safe values to be saved.
*/
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance['title'] = strip_tags( $new_instance['title'] );
return $instance;
}
/**
* Back-end widget form.
*
* @see WP_Widget::form()
*
* @param array $instance Previously saved values from database.
*/
public function form( $instance ) {
if ( isset( $instance[ 'title' ] ) ) {
$title = $instance[ 'title' ];
}
else {
$title = __( 'New title', 'text_domain' );
}
?>
<p>
<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
</p>
<?php
}
} // class Foo_Widget
This sample widget can then be registered in the widgets_init hook:
// register Foo_Widget widget add_action( 'widgets_init', create_function( '', 'register_widget( "foo_widget" );' ) );
If you use PHP 5.3. with namespaces you should call the constructor directly as in the following example:
namespace a\b\c;
class My_Widget_Class extends \WP_Widget {
function __construct() {
parent::__construct( 'baseID', 'name' );
}
// ... rest of functions
}
and call the register widget with:
add_action( 'widgets_init', function(){
register_widget( 'a\b\c\My_Widget_Class' );
});
(see: http://stackoverflow.com/questions/5247302/php-namespace-5-3-and-wordpress-widget/5247436#5247436)
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 2.8 information.
Theme Support:
add_theme_support(),
remove_theme_support(),
current_theme_supports()
Features:
sidebar,
menus,
post-formats,
post-thumbnails,
custom-background,
custom-header,
automatic-feed-links,
content_width,
editor-style
