Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Widgetizing Themes

What is Widgetizing?

Widgetizing is a pseudo word that describes the process of implementing Widgets and Widget Areas into your Theme.

How to Register a Widget Area

The following should be added to your Theme's functions.php file:

<?php
/**
 * Register our sidebars and widgetized areas.
 *
 */
function arphabet_widgets_init() {

	register_sidebar( array(
		'name'          => 'Home right sidebar',
		'id'            => 'home_right_1',
		'before_widget' => '<div>',
		'after_widget'  => '</div>',
		'before_title'  => '<h2 class="rounded">',
		'after_title'   => '</h2>',
	) );

}
add_action( 'widgets_init', 'arphabet_widgets_init' );
?>

How to display new Widget Areas

You can display your new widget area by:

  1. Adding the code directly to a theme file like the sidebar.php file; or
  2. Using a custom function with hook in your functions.php file.

Here's some example code that is a common way to add your new widget area to a parent or child theme:

<?php if ( is_active_sidebar( 'home_right_1' ) ) : ?>
	<div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary">
		<?php dynamic_sidebar( 'home_right_1' ); ?>
	</div><!-- #primary-sidebar -->
<?php endif; ?>

The above code can be added to your sidebar.php file. It checks to see if the widget area is populated (i.e. is active) and then displays the contents of the widget if active.

This is the function which outputs the widget:

<?php dynamic_sidebar( 'home_right_1' ); ?>

The code above will display the widget registered with an ID value of 'home_right_1'. When displaying a widget on your site, remember to replace 'home_right_1' with the ID value you specified when you registered your widget.

For more information, please refer to the Widgets API to learn how to, programmatically, display Widgets and Widget Areas.

If you're not a programmer, you should refer to the WordPress Widgets page.

Create New Widget Area Using Custom Function

You can use WordPress or theme specific hooks to display new widget areas in your theme directly from your parent or child themes functions file.

function wpsites_before_post_widget( $content ) {
	if ( is_singular( array( 'post', 'page' ) ) && is_active_sidebar( 'before-post' ) && is_main_query() ) {
		dynamic_sidebar('before-post');
	}
	return $content;
}
add_filter( 'the_content', 'wpsites_before_post_widget' );

The above code displays a new widget area before all single posts and pages in any theme using the_content [1] filter however it is suggested you use theme specific hooks if your theme includes them.

Note: You will also need to register a new widget area using the same ID as what you use in the dynamic sidebar which in this example is before-post.

register_sidebar( array(
	'id'          => 'before-post',
	'name'        => 'Before Posts Widget',
	'description' => __( 'Your Widget Description.', 'text_domain' ),
) );

Resources

Related

Sidebars: is_active_sidebar(), is_dynamic_sidebar(), dynamic_sidebar(), register_sidebars(), register_sidebar(), unregister_sidebar(), wp_register_sidebar_widget(), wp_unregister_sidebar_widget(), wp_get_sidebars_widgets(), wp_set_sidebars_widgets()

Widgets: is_active_widget(), the_widget(), register_widget(), unregister_widget(), wp_register_widget_control(), wp_unregister_widget_control(), wp_convert_widget_settings(), wp_get_widget_defaults(), wp_widget_description()