Developer's Roundtable Notes

What are widgets?

Basically, they are containers for content that can be placed – and moved around – in your site without coding.

And, perhaps one of the more non-intuitive parts of WordPress.

Sidebars don’t have to be sidebars. They can be placed anywhere in a template.

More accurately, they are “widget areas”.

Sidebars are specific to your theme, while widgets are content, and so will survive a theme change.

Some themes come with one sidebar, some come with many.

If you want to add a new one, it’s pretty easy.

add_action( 'widgets_init', 'register_my_special_sidebar' );

function register_my_special_sidebar() {
$args = array(
	'name'             => __( 'My Special Sidebar', 'my_text_domain' ), // The name that will show on the Widgets screen
	'id'               => 'my-special-sidebar', // a unique ID for the widget
       // all of the parameters below are optional
	'description'  	   => 'This area appears on my special page.',
        'class'            => 'myclass',
	'before_widget'    => '<aside id="%1$s" class="widget %2$s">',
	'after_widget'     => '</aside>',
	'before_title'     => '<h2 class="widgettitle">',
	'after_title'      => '</h2>' 
); 

register_sidebar( $args );
}

Unlike  many custom functions, this one belongs in your functions.php file rather than a plugin – because it is theme specific.

Now that you have a new sidebar (widget area), how do you get it to display on your site?

There are many ways to do this within the WordPress template hierarchy.

Choose whichever method makes the most sense to you.

If you want the contents of “My Special Sidebar” to replace the normal sidebar on just one page, you can make a copy of page.php, and change the code that calls the sidebar like this:

Replace this:

<?php get_sidebar(); ?>

With this:

<?php if (is_active_sidebar('my-special-sidebar') ) { 
     dynamic_sidebar('my-special-sidebar');
} ?>

Then, save the file as: page-my-special-page.php. (In this case, the slug of your page would be “my-special-page”. By adding “page-” to the file name, WordPress will automagically use this template for only that page.

For more information on using special templates, take a look at the Template Hierarchy.

Alternately, you can simply change your page.php file like this:

Replace this:

<?php get_sidebar(); ?>

With this:

<?php if ( is_page('my-special-page')) {
	if (is_active_sidebar('my-special-sidebar') ) { 
		dynamic_sidebar('my-special-sidebar');
	        } 	
	} else {
	if ( is_active_sidebar( 'sidebar-1' ) ) {
		dynamic_sidebar( 'sidebar-1' ); 
		}
	}
	?>

This is another way to replace the default sidebar with your special one on just one page.

If you want to replace the sidebar on multiple pages, it may be easier to create a template.

Simply copy page.php, replace the sidebar as in example 1 above, and add this line to the top of the file:

<?php
/**
 * Template Name: My Special Sidebar
 */

This tells WordPress that this is a page template. It will then appear in the page edit screen as an option under Page Attributes->Template.

You can then use this template for as many pages as you like.

There are also other ways to replace sidebars, for example, with custom sidebar pages, or conditionals in sidebar.php.

And, there are probably others that I’ve never tried.

Check the codex if you’re interested.

What if you want to add a widget area somewhere else on your page, or in the header or footer?

It’s the same logic. Simply pick the spot in your template, and add the code:

<?php if (is_active_sidebar('my-special-sidebar') ) { 
	dynamic_sidebar('my-special-sidebar');
	} ?>

You can add it to the beginning or the end of your blog posts, place it in the header or footer template… the possibilities are endless.

Let’s say you want to add just one widget somewhere on your site.

No need to create a special widget area, just include this in your template where you want the widget. (Just use the name of the widget.)

<?php if ( function_exists('the_widget') ) {
	the_widget( 'Silly_Widget' ); 
	}
?>

This, for example, outputs the content of the WordPress calendar widget:

<?php the_widget( 'WP_Widget_Calendar' ); ?>

You can also add arguments to the_widget – here’s the reference: https://codex.wordpress.org/Function_Reference/the_widget

For a more complete tutorial on creating widgets, please see my previous Roundtable.

A simpler way to create a widget if you only need to use it once.

For example, you want to print a welcome message to visitors on your home page.

Simply add this code to your functions.php file:

add_action( 'widgets_init', 'register_my_welcome_widget' );

function my_welcome_widget_display($args) {	
	if (is_user_logged_in) {
		global $current_user;
		get_currentuserinfo();
		$fname= $current_user->first_name;
	} else {
		$fname= 'Guest';
	}
	echo $args['before_widget'];
	echo $args['before_title'] . 'My Welcome Widget' .  $args['after_title'];
	echo '<p>Welcome, ' . $current_user->first_name . '</p>';
	echo $args['after_widget'];
}
function register_my_welcome_widget() {
	wp_register_sidebar_widget(
		'my-welcome-widget',        		
		'My Welcome Widget',         		
		'my_welcome_widget_display',  		
		array(                  				
			'description' => 'Welcome text widget.'
		)
	);
}

The widget will show up on the Widgets page, and you can drag it into any available sidebar, if you like.

You can also display it on your site using the_widget, as above.

You can only use this type of widget once, though. After you put it into a sidebar, you will notice it disappears from the available widgets.