Widgets API
wordpress.org.cn
includeonlydiv style=clear:both; background-color:#EEEEFF; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;This article is marked as in need of editing. You can help Codex by editing it./div/includeonlynoinclude
目录
Description
This Template is used by Codex:Template Messages.
Usage
pre 检查到模板循环:模板:Message /pre
Result
检查到模板循环:模板:Message
/noinclude
Widgets API
This page contains the technical documentation for the WordPress Widgets API and is written for developers. If you're not a developer you may want to review the Widgets page.
In technical terms: a WordPress Widget is a PHP object that echoes string data to STDOUT when its widget() method is called. It's located in onlyincludecodewp-includes/widgets.php/code/onlyinclude
div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9
Template Description
Link to the source code on http://core.trac.wordpress.org/browser/.
Parameters
- filename
- (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.
Usage
Link to the stable version: pre检查到模板循环:模板:Trac/pre
Link to trunk: pre检查到模板循环:模板:Trac/pre
/div
wordpress.org.cn.
Function Reference
|
|
Developing Widgets
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 onlyincludecodewp-includes/widgets.php/code/onlyinclude
div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9
Template Description
Link to the source code on http://core.trac.wordpress.org/browser/.
Parameters
- filename
- (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.
Usage
Link to the stable version: pre检查到模板循环:模板:Trac/pre
Link to trunk: pre检查到模板循环:模板:Trac/pre
/div
wordpress.org.cn.
Default Usage
class My_Widget extends WP_Widget { /** * Sets up the widgets name etc */ public function __construct() { $widget_ops = array( 'classname' => 'my_widget', 'description' => 'My Widget is awesome', ); parent::__construct( 'my_widget', 'My Widget', $widget_ops ); } /** * Outputs the content of the widget * * @param array $args * @param array $instance */ public function widget( $args, $instance ) { // outputs the content of the widget } /** * Outputs the options form on admin * * @param array $instance The widget options */ public function form( $instance ) { // outputs the options form on admin } /** * Processing widget options on save * * @param array $new_instance The new options * @param array $old_instance The previous options */ public function update( $new_instance, $old_instance ) { // processes widget options to be saved } }
The widget can then be registered using the widgets_init
hook:
PHP 5.3+ only:
add_action( 'widgets_init', function(){ register_widget( 'My_Widget' ); });
PHP 5.2+:
add_action('widgets_init', create_function('', 'return register_widget("My_Widget");') );
Example
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. */ function __construct() { parent::__construct( 'foo_widget', // Base ID __( 'Widget Title', 'text_domain' ), // 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 ) { echo $args['before_widget']; if ( ! empty( $instance['title'] ) ) { echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ). $args['after_title']; } echo __( 'Hello, World!', 'text_domain' ); echo $args['after_widget']; } /** * Back-end widget form. * * @see WP_Widget::form() * * @param array $instance Previously saved values from database. */ public function form( $instance ) { $title = ! empty( $instance['title'] ) ? $instance['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 } /** * 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'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : ''; return $instance; } } // class Foo_Widget
This sample widget can then be registered in the 'widgets_init' hook:
// register Foo_Widget widget function register_foo_widget() { register_widget( 'Foo_Widget' ); } add_action( 'widgets_init', 'register_foo_widget' );
Note : You must use get_field_name() and get_field_id() function to generate form element name and id.
Example With Namespaces
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.
Displaying Widgets and Widget Areas
There are at least 3 ways that Widgets can be displayed:
Widget Areas
The first, and most common, is by adding the desired Widget to a Widget Area via the Appearance -> Widgets menu in the Administration Screens.
WordPress comes with some predefined Widget Areas that each have unique identifiers (view the source of the Widgets page to see them) that you'll need to know in order to display the Widget Area. If the predefined Widget Areas are insufficient for your needs you may register a custom Widget Areas.
When you're ready you can display that Widget Area by inserting the following code into whichever Theme file you desire:
<?php if ( dynamic_sidebar('example_widget_area_name') ) : else : endif; ?>
That code displays all of the Widgets added to that Widget Area.
Display Widget Area Only If Active
Here's the code used in the sidebar.php file of the Twenty Fourteen Theme.
<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?> <div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary"> <?php dynamic_sidebar( 'sidebar-1' ); ?> </div><!-- #primary-sidebar --> <?php endif; ?>
This code checks to see if the new widget area is populated otherwise doesn't execute.
Independent Widgets
The second, and more technical, is via the_widget() method.
Tags: how do i display widgets, how do i display widget areas
Resources
- Deprecating PHP4 style constructors in WordPress 4.3.
- Notice: The called constructor method for WP_Widget is deprecated since version 4.3.0! Use __construct()
- WordPress Sidebar Generator