Codex Wordpress Org Widgets API

8/22/2019 Codex Wordpress Org Widgets API

1/7

pdfcrowd comopen in browser PRO version Are you a developer? Try out the HTML to PDF API

Search WordPress.org

Codex

Contents

[hide]

1 Widgets API

2 Function Reference

3 Developing Widgets

3.1 Default Usage

3.2 Example

3.3 Example With Namespaces

4 Displaying Widgets and Widget Areas

5 Widget Areas

6 Independent Widgets

6.1 Resources

6.2 Related

Widgets API

Languages: English Espaol () (Add your language)

This article is marked as inneed of editing. You can help Codex by editing it.

Widgets APIThis 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 Widgetis a PHP object that echoes string datato

STDOUT when its widget() method is called. It'slocated in wp-includes/widgets.php.

Function Reference

Home Page

WordPress Less ons

Getting Started

Working with

WordPress

Design and Layout

Advanced Topics

Troubleshooting

Developer Docs

About WordPress

Codex Resources

Community portal

Current events

Recent changes

Random page

Help

Have you taken the WordPress 2013 Survey yet?

Showcase Themes Plugins Mobile Support Get Involved About Blog Hosting Download WordPress

Codex tools: Log in
http://codex.wordpress.org/Special:Randomhttp://codex.wordpress.org/Multilingual_Codexhttp://codex.wordpress.org/es:API_de_Widgethttp://codex.wordpress.org/es:API_de_Widgethttp://wpdocs.sourceforge.jp/WordPress_%E3%82%A6%E3%82%A3%E3%82%B8%E3%82%A7%E3%83%83%E3%83%88_APIhttp://codex.wordpress.org/zh-cn:%E5%B0%8F%E5%B7%A5%E5%85%B7%E6%8E%A5%E5%8F%A3http://codex.wordpress.org/Multilingual_Codex#Language_Cross_Referencehttp://codex.wordpress.org/Multilingual_Codex#Language_Cross_Referencehttp://codex.wordpress.org/Multilingual_Codex#Language_Cross_Referencehttp://wordpress.org/showcase/http://wordpress.org/themes/http://wordpress.org/plugins/http://wordpress.org/mobile/http://wordpress.org/support/http://wordpress.org/support/http://make.wordpress.org/http://make.wordpress.org/http://wordpress.org/about/http://wordpress.org/news/http://wordpress.org/hosting/http://wordpress.org/http://wordpress.org/http://wordpress.org/http://wordpress.org/http://wordpress.org/support/http://make.wordpress.org/http://make.wordpress.org/http://wordpress.org/about/http://wordpress.org/news/http://wordpress.org/hosting/http://wordpress.org/hosting/http://wordpress.org/http://codex.wordpress.org/Current_eventshttp://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdfhttp://wordpress.org/http://toggletoc%28%29/http://codex.wordpress.org/Multilingual_Codexhttp://codex.wordpress.org/es:API_de_Widgethttp://wpdocs.sourceforge.jp/WordPress_%E3%82%A6%E3%82%A3%E3%82%B8%E3%82%A7%E3%83%83%E3%83%88_APIhttp://codex.wordpress.org/zh-cn:%E5%B0%8F%E5%B7%A5%E5%85%B7%E6%8E%A5%E5%8F%A3http://codex.wordpress.org/Multilingual_Codex#Language_Cross_Referencehttp://codex.wordpress.org/Category:Copyeditshttp://codex.wordpress.org/Codex:Contributinghttp://codex.wordpress.org/index.php?title=Widgets_API&action=edithttp://codex.wordpress.org/WordPress_Widgetshttp://php.net/manual/en/language.oop5.phphttp://en.wikipedia.org/wiki/Stdout#Standard_output_.28stdout.29http://core.trac.wordpress.org/browser/tags/3.5.2/wp-includes/widgets.php#L0http://codex.wordpress.org/Main_Pagehttp://codex.wordpress.org/WordPress_Lessonshttp://codex.wordpress.org/Getting_Started_with_WordPresshttp://codex.wordpress.org/Working_with_WordPresshttp://codex.wordpress.org/Blog_Design_and_Layouthttp://codex.wordpress.org/Advanced_Topicshttp://codex.wordpress.org/Troubleshootinghttp://codex.wordpress.org/Developer_Documentationhttp://codex.wordpress.org/About_WordPresshttp://codex.wordpress.org/Codex:Community_Portalhttp://codex.wordpress.org/Current_eventshttp://codex.wordpress.org/Special:RecentChangeshttp://codex.wordpress.org/Special:Randomhttp://codex.wordpress.org/Help:Contentshttp://wp-survey.polldaddy.com/s/wp-2013http://wordpress.org/showcase/http://wordpress.org/themes/http://wordpress.org/plugins/http://wordpress.org/mobile/http://wordpress.org/support/http://make.wordpress.org/http://wordpress.org/about/http://wordpress.org/news/http://wordpress.org/hosting/http://wordpress.org/download/http://codex.wordpress.org/index.php?title=Special:UserLogin&returnto=Widgets_API


2/7


Widget Functions

is_active_widget()

the_widget()

register_widget()

unregister_widget()

internal Functions

wp_register_widget_control()

wp_unregister_widget_control()

wp_convert_widget_settings()

wp_get_widget_defaults()

wp_widget_description()

Developing WidgetsTo 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.

Default Usage

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

}
http://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdfhttp://codex.wordpress.org/Function_Reference/is_active_widgethttp://codex.wordpress.org/Function_Reference/the_widgethttp://codex.wordpress.org/Function_Reference/register_widgethttp://codex.wordpress.org/Function_Reference/unregister_widgethttp://codex.wordpress.org/Function_Reference/wp_register_widget_controlhttp://codex.wordpress.org/Function_Reference/wp_unregister_widget_controlhttp://codex.wordpress.org/Function_Reference/wp_convert_widget_settingshttp://codex.wordpress.org/Function_Reference/wp_get_widget_defaultshttp://codex.wordpress.org/Function_Reference/wp_widget_descriptionhttp://core.trac.wordpress.org/browser/tags/3.5.2/wp-includes/widgets.php#L0


3/7


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' );

});

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

'Foo_Widget', // Namearray( 'description' => __( 'A Foo Widget', 'text_domain' ), ) // Args

);

}

/**

* Front-end display of widget.

*

* @see WP_Widget::widget()

*

* @param array $args Widget arguments.
http://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdf


4/7


* @param array $instance Saved values from database.

*/

public function widget( $args, $instance ) {

$title = apply_filters( 'widget_title', $instance['title'] );

echo $args['before_widget'];

if ( ! empty( $title ) )

echo $args['before_title'] . $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 ) {

if ( isset( $instance[ 'title' ] ) ) {

$title = $instance[ 'title' ];

}else {

$title = __( 'New title', 'text_domain' );

}

?>


5/7


* @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' );

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:
http://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdf


6/7


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 AreasThere are two 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.

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:

That code displays all of the Widgets added to that Widget Area.

Independent Widgets
http://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdfhttp://stackoverflow.com/questions/5247302/php-namespace-5-3-and-wordpress-widget/5247436#5247436http://codex.wordpress.org/Version_2.8#New_Widgets_APIhttp://codex.wordpress.org/Glossary#Widgethttp://codex.wordpress.org/Widgetizing_Themes#How_to_Register_a_Widget_Areahttp://codex.wordpress.org/Appearance_Widgets_Screenhttp://codex.wordpress.org/Glossary#registerhttp://codex.wordpress.org/Widgetizing_Themes#How_to_Register_a_Widget_Area


7/7

df d mi b PRO i Are you a developer? Try out the HTML to PDF API

Privacy | License / GPLv2 See also: Hosted WordPress.com | WordPress.TV Videos | WordCamp Events | BuddyPress Social Layer | bbPress Forums | WP Jobs | Matt

The second, and more technical, is via the_widget() method.

Tags: how do i display widgets, how do i display widget areas

Resources

The complete guide to creating widgets in WordPress 2.8

WordPress 2.8+ Multi-Widgets

Build A WordPress 2.8 Widget With The New Widget API

WordPress Sidebar Generator

RelatedTheme 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

Categories: Copyedit | Widgets | Advanced Topics | WordPress Development | API

Like 731k

Follow
http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/http://pdfcrowd.com/redirect/?url=http%3a%2f%2fcodex.wordpress.org%2fWidgets_API&id=ma-130801085149-2eec9b19http://pdfcrowd.com/customize/http://pdfcrowd.com/html-to-pdf-api/?ref=pdfhttp://wordpress.org/about/privacy/http://wordpress.org/about/license/http://wordpress.com/?ref=wporg-footerhttp://wordpress.tv/http://central.wordcamp.org/http://buddypress.org/http://bbpress.org/http://jobs.wordpress.net/http://ma.tt/http://codex.wordpress.org/Function_Reference/the_widgethttp://justintadlock.com/archives/2009/05/26/the-complete-guide-to-creating-widgets-in-wordpress-28http://justcoded.com/implementation/wordpress-28-multi-widgets/http://wpengineer.com/wordpress-built-a-widget/http://generatewp.com/sidebar/http://codex.wordpress.org/Theme_Featureshttp://codex.wordpress.org/Function_Reference/add_theme_supporthttp://codex.wordpress.org/Function_Reference/remove_theme_supporthttp://codex.wordpress.org/Function_Reference/current_theme_supportshttp://codex.wordpress.org/Theme_Featureshttp://codex.wordpress.org/Sidebarshttp://codex.wordpress.org/Navigation_Menushttp://codex.wordpress.org/Post_Formatshttp://codex.wordpress.org/Post_Thumbnailshttp://codex.wordpress.org/Custom_Backgroundshttp://codex.wordpress.org/Custom_Headershttp://codex.wordpress.org/Automatic_Feed_Linkshttp://codex.wordpress.org/Content_Widthhttp://codex.wordpress.org/Editor_Stylehttp://codex.wordpress.org/Special:Categorieshttp://codex.wordpress.org/Category:Copyedithttp://codex.wordpress.org/Category:Widgetshttp://codex.wordpress.org/Category:Advanced_Topicshttp://codex.wordpress.org/Category:WordPress_Developmenthttp://codex.wordpress.org/Category:APIhttps://twitter.com/intent/follow?original_referer=http%3A%2F%2Fcodex.wordpress.org%2FWidgets_API&region=follow_link&screen_name=WordPress&tw_p=followbutton&variant=2.0

Documents

Codex Wordpress Org Widgets API