sidebars_widgets │ filter-hook │ WP 2.7.0

Allows you to change the list of sidebars and the widgets assigned to them.

Usage

add_filter( 'sidebars_widgets', 'wp_kama_sidebars_widgets_filter' );

/**
 * Function for `sidebars_widgets` filter-hook.
 * 
 * @param array $sidebars_widgets An associative array of sidebars and their widgets.
 *
 * @return array
 */
function wp_kama_sidebars_widgets_filter( $sidebars_widgets ){

	// filter...
	return $sidebars_widgets;
}

$sidebars_widgets(array)

Associative array of sidebars and their widgets.

Example data passed through the filter hook for the TownPress theme:

Array
(
	[wp_inactive_widgets] => Array
		(
			[0] => lsvr_directory_listing_list-3
			[1] => lsvr_townpress_post_list-4
			[2] => lsvr_townpress_post_featured-3
			[3] => archives-2
			[4] => meta-2
			[5] => categories-2
			[6] => recent-comments-2
		)

	[lsvr-townpress-default-sidebar-left] => Array
		(
			[0] => search-2
			[1] => recent-posts-2
		)

	[lsvr-townpress-default-sidebar-right] => Array
		(
			[0] => custom_html-2
			[1] => cherry_widget_trending_posts-2
		)

	[lsvr-townpress-footer-widgets] => Array
		(
			[0] => text-2
			[1] => tag_cloud-2
		)

	[lsvr-townpress-custom-sidebar-1] => Array
		(
		)

)

As the example shows, the first array level is the list of sidebars. Each key is a sidebar ID specified when it is registered with register_sidebar(). The second array level contains the IDs of widgets assigned to each sidebar.

Examples

#1 Replace the widgets in one sidebar with those from another

Suppose the site has a Reviews category (taxonomy=category, slug=reviews) containing Posts (post_type=post). On review posts, the theme's left sidebar (id=sidebar-left) should display different widgets from those shown throughout the rest of the site. One option is to change the theme's sidebar output logic and template, but the sidebars_widgets filter hook avoids modifying the theme. This code can be used in either a theme or a plugin.

// Step 1: Register a new sidebar with id=reviews-sidebar.

add_action( 'widgets_init', 'cr_register_sidebars' );

function cr_register_sidebars() {
	register_sidebar( array(
		'name'          => 'Reviews Sidebar',
		'id'            => 'reviews-sidebar',
		'description'   => 'Sidebar for Reviews',
		'class'         => '',
		'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="widget__inner">',
		'after_widget'  => '</div></div>',
		'before_title'  => '<h3 class="widget__title">',
		'after_title'   => '</h3>',
	) );
}

// Step 2: Replace the sidebar-left widgets with the reviews-sidebar widgets.

add_action( 'wp', 'cr_main_actions' );

function cr_main_actions() {

	// Check whether the current Post belongs to the Reviews category.
	if ( is_singular( 'post' ) && in_category( 'reviews' ) ) {
		add_filter( 'sidebars_widgets', 'cr_sidebars_widgets' );
	}

}

// Replace the widgets.
function cr_sidebars_widgets( $sidebars_widgets ) {
	$sidebars_widgets['sidebar-left'] = $sidebars_widgets['reviews-sidebar'];

	return $sidebars_widgets;
}