The easiest way to customize your Dashboard

For many WordPress sites, you can achieve complete Dashboard nirvana by simply selecting a few options in the Dashboard’s Screen Options panel. On the Dashboard, click the tab in the upper-right corner to toggle open your Dashboard configuration options. There you can choose your Dashboard preferences:

• Choose the widgets you want to show on the Dashboard
• Choose how many columns to use for the screen layout

Here is a screenshot illustrating this awesome functionality:

The ability to hide or show any default widgets makes it easy to set things up on the fly. Maybe your client doesn’t need the community news feed? Disable it. Maybe you’re getting some fatal errors (e.g., “Allowed memory size of 33554432 bytes exhausted”) for the Incoming Links and Plugins widgets? You could spend time on the issue or you could just disable any widgets giving you grief. For my personal sites, I like to disable everything except for Right Now, Recent Comments, and Incoming Links, and display them in two columns. Keeps the Dashboard clean and fast. But to each their own! That’s the beauty of WordPress :)

Customizing and disabling the Dashboard using plugins

Most of the time, the built-in Screen Options are all you need to customize your WordPress Dashboard. For more control over which users actually see the dashboard and its widgets, here are two great plugins (among many):

• KP Design’s WP Hide Dashboard
• sant0sk1’s Clean WP Dashboard

The WP Hide Dashboard plugin really cleans things up by removing the Dashboard and Tools menu, the Screen Options section, and even the Help button on the Profile page. It also prevents Dashboard access to users assigned to the Subscriber role. It’s also a breeze to use: just install and it works – no configuration necessary.

The Clean WP Dashboard plugin doesn’t remove any of the Dashboard menus, Screen Options, or Help button, but it does enable you to remove any of the following Dashboard widgets for all users:

• Right Now
• Incoming Links
• Plugins
• Recent Comments
• QuickPress
• Recent Drafts
• WP Dev Blog
• Other WP News

With this plugin, disabling any of these default widgets also removes their corresponding display option from the Screen Options menu, but leaves all the settings and menus in place for other widgets. This also is a very simple plugin to use: just enable, pick your widgets, and done. Here is another screenshot to help illustrate how this plugin is useful for customizing your dashboard:

Even with WordPress’ default Screen Options and helpful plugins such as these, there are times when you’ll want to do even more with the customization of your Dashboard. Fortunately, with WordPress you’re not limited to default functionality and widgets – by adding a few lines of code to your theme’s functions.php file, you can make just about anything happen.

Customizing your Dashboard with the functions.php file

There are many cool ways to customize your WordPress site using your theme’s functions.php file. The benefits of using functions.php include:

• Direct control over site functionality
• Follows your theme to other sites (portability)
• You don’t need to rely on a plugin
• Set it and forget – no upgrades or fiddling

I would argue that in some cases, it’s actually easier to use functions.php than it is to hunt down, install, configure, and manage a plugin. Just grab a code snippet (or write your own) and paste it anywhere into your theme’s functions.php file. Test well and you’re done. Let’s check out some functions.php snippets useful for customizing the WordPress Dashboard.

Create your own Dashboard widget

You can display just about anything in your Dashboard. If default tools and other plugins aren’t getting you there, WordPress makes it easy to create your own. The easiest way to get started is to add the following to functions.php:

// example custom dashboard widget
function custom_dashboard_widget() {
	echo "<p>Dearest Client, Here&rsquo;s how to do that thing I told you about yesterday...</p>";
}
function add_custom_dashboard_widget() {
	wp_add_dashboard_widget('custom_dashboard_widget', 'How to Do Something in WordPress', 'custom_dashboard_widget');
}
add_action('wp_dashboard_setup', 'add_custom_dashboard_widget');

Here we are using two functions to do the job. The first one contains the content of the custom widget. The second one turns the output of the first function into a widget. And finally, we run the second function when the Dashboard is set up. Once this code is in place, visit your Dashboard. You should see your custom widget displayed like so:

Once you see how things work, it’s just a matter of adding the content and functionality. You could add a calendar, list recent subscribers, import feeds, display images, post tutorials, and just about anything else imaginable.

Disable default widgets

You can also use functions.php to disable default Dashboard widgets without a plugin. Using the code found in the WordPress Codex, you would add this to your functions.php file:

// disable default dashboard widgets
function remove_dashboard_widgets() {

	global $wp_meta_boxes;

	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']);
	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']);
	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']);
	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']);

	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']);
	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']);
	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']);
	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']);
}
add_action('wp_dashboard_setup', 'remove_dashboard_widgets');

This works fine, but it seems better to use the WordPress API:

// disable default dashboard widgets
function disable_default_dashboard_widgets() {

	remove_meta_box('dashboard_right_now', 'dashboard', 'core');
	remove_meta_box('dashboard_recent_comments', 'dashboard', 'core');
	remove_meta_box('dashboard_incoming_links', 'dashboard', 'core');
	remove_meta_box('dashboard_plugins', 'dashboard', 'core');

	remove_meta_box('dashboard_quick_press', 'dashboard', 'core');
	remove_meta_box('dashboard_recent_drafts', 'dashboard', 'core');
	remove_meta_box('dashboard_primary', 'dashboard', 'core');
	remove_meta_box('dashboard_secondary', 'dashboard', 'core');
}
add_action('admin_menu', 'disable_default_dashboard_widgets');

I’m using this code to clean up the Dashboard of my eChunks site, and it works like a dream. You can also set the code to display the default widgets only for Admins by replacing the last line with this conditional snippet:

if (!current_user_can('manage_options')) {
        add_action('wp_dashboard_setup', 'disable_default_dashboard_widgets');
}

This code basically says, “disable the default Dashboard widgets only if the user can’t manage options. So Admins will see the widgets but everyone else will not.

Disable plugin and other non-default widgets

If you recall from the second screenshot in this article, only the Simple:Press widget was displayed in the Dashboard. Even with the default widgets disabled, widgets from plugins and the functions.php file are displayed. As with the default widgets, you can simply hide these widgets using the Screen Options panel, or you can completely disable them using a few lines code in your functions.php file.

To disable a non-default Dashboard widget, you first need the name of the widget, which is available in the source code as one of the <div> ids. For example, the Simple:Press widget is wrapped in the following markup:

<div id="sf_announce" class="postbox">

And so the name of the widget is “sf_announce”. Likewise, our custom Dashboard widget is wrapped with this:

<div id="custom_dashboard_widget" class="postbox">

Once you have the name of the widget you would like to remove, just add another line to the disable_default_dashboard_widgets() function provided above:

// disable default dashboard widgets
function disable_default_dashboard_widgets() {

	// disable default dashboard widgets
	remove_meta_box('dashboard_right_now', 'dashboard', 'core');
	remove_meta_box('dashboard_recent_comments', 'dashboard', 'core');
	remove_meta_box('dashboard_incoming_links', 'dashboard', 'core');
	remove_meta_box('dashboard_plugins', 'dashboard', 'core');

	remove_meta_box('dashboard_quick_press', 'dashboard', 'core');
	remove_meta_box('dashboard_recent_drafts', 'dashboard', 'core');
	remove_meta_box('dashboard_primary', 'dashboard', 'core');
	remove_meta_box('dashboard_secondary', 'dashboard', 'core');

	// disable Simple:Press dashboard widget
	remove_meta_box('sf_announce', 'dashboard', 'normal');
}
add_action('admin_menu', 'disable_default_dashboard_widgets');

Other Dashboard widgets may be disabled in the same way. Just replace sf_announce with the name of your widget. If you have a lot of widgets to disable, you may not feel like digging through source code to decipher their names. Fortunately, there’s an easier way to get that information.

List all Dashboard widgets

To get a list of all active Dashboard widgets, add the following snippet to your theme’s functions.php file:

// list active dashboard widgets
function list_active_dashboard_widgets() {
	global $wp_meta_boxes;
	foreach (array_keys($wp_meta_boxes['dashboard']['normal']['core']) as $name) {
		echo '<div>' . $name . '</div>';
	}
}
add_action('wp_dashboard_setup', 'list_active_dashboard_widgets');

Then go to your Admin and hit refresh. At the top of the page, you will see a list of all active widgets. Note that this method is a little rough because the list is basically spit out before all of the content, so make sure you’re not executing on a production site. Or be quick about it. Or use the conditional current_user_can code from above. Either way, this is the easiest way to grab a list of all active Dashboard widgets.

Wrap up

What’s the take-home message from all of this? WordPress makes it easy to customize your Dashboard in three ways: default Screen Options, plugins, and functions.php code. Using any combination of these three methods, you have complete control over the appearance and functionality of your WordPress Dashboard.

© 2010 Digging into WordPress | Permalink | 14 comments | Add to del.icio.us | Post tags: dashboard, widgets

The answer was creating a custom function for the functions.php file which would output any widget by name. There is a function just for that: the_widget() (incomplete codex page).

The logic

1. Test if widget exists
2. If it does…
   1. Start capturing output
   2. Output widget
   3. End capturing output
   4. Return captured output
3. If it doesn’t exist…
   1. Output fail message

The code for functions.php

function widget($atts) {
    
    global $wp_widget_factory;
    
    extract(shortcode_atts(array(
        'widget_name' => FALSE
    ), $atts));
    
    $widget_name = wp_specialchars($widget_name);
    
    if (!is_a($wp_widget_factory->widgets[$widget_name], 'WP_Widget')):
        $wp_class = 'WP_Widget_'.ucwords(strtolower($class));
        
        if (!is_a($wp_widget_factory->widgets[$wp_class], 'WP_Widget')):
            return '<p>'.sprintf(__("%s: Widget class not found. Make sure this widget exists and the class name is correct"),'<strong>'.$class.'</strong>').'</p>';
        else:
            $class = $wp_class;
        endif;
    endif;
    
    ob_start();
    the_widget($widget_name, $instance, array('widget_id'=>'arbitrary-instance-'.$id,
        'before_widget' => '',
        'after_widget' => '',
        'before_title' => '',
        'after_title' => ''
    ));
    $output = ob_get_contents();
    ob_end_clean();
    return $output;
    
}
add_shortcode('widget','widget'); 

Usage

Now in Post/Page content, you can use the widget just by referencing it by name:

[widget widget_name="Your_Custom_Widget"]

© 2010 Digging into WordPress | Permalink | 15 comments | Add to del.icio.us | Post tags: functions, Theme, widgets

if ( function_exists('register_sidebar') ) {

    $allWidgetizedAreas = array("Homepage Left", "Homepage Right", "Sidebar One", "Movies", "Admin");
    
    foreach ($allWidgetizedAreas as $WidgetAreaName) {
    
        register_sidebar(array(
           'name'=> $WidgetAreaName,
           'before_widget' => '<div id="%1$s" class="widget %2$s left half">',
           'after_widget' => '</div>',
           'before_title' => '<h3 class="widgettitle">',
           'after_title' => '</h3>',
        ));
    
    }

}

© 2010 Digging into WordPress | Permalink | 7 comments | Add to del.icio.us | Post tags: functions, PHP, widgets

But alas…

This ain’t gonna work “out-of-the-box”

After tinkering with some far-too-complicated solutions, someone on Twitter helped me with a deliciously simple solution: Just add this to your functions.php file:

add_filter('widget_text', 'do_shortcode');

This will ensure that the text content of widgets is parsed for shortcodes and those shortcodes are ran. Awesome.

Stephanie Leary wrote a great article on Using Shortcodes Everywhere, which covers this as well as using shortcodes in a bunch of other places: Comments, templates, excerpts, etc.

© 2010 Digging into WordPress | Permalink | 4 comments | Add to del.icio.us | Post tags: shortcode, widgets

Widgetize Your WordPress Theme: Step 1

Make a fist and howl at the monitor. Then place this code into your active theme’s functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Widgetized Area',
		'id'   => 'widgetized-area',
		'description'   => 'This is a widgetized area.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

This is all that is needed for the first step. Once this widgetizing code is placed in your functions.php file, proceed to Step 2. The remainder of this section is explanation.

This code checks to make sure that the current version of WordPress supports widgets, and then declares an array of values that will be used to create the widgetized area in your theme. Here are the different values:

• name – the name of the widgetized area as displayed in the WP Admin
• id – a unique identifier for your widgetized area
• description – description of the widgetized area
• before_widget – the markup generated before any user-added widgets
• after_widget – the markup generated after any user-added widgets
• before_title – the markup generated before the title of any user-added widgets
• after_title – the markup generated after the title of any user-added widgets

So, given these parameters, our widgetizing code would result in the following output, say, if the built-in Search widget were added to our widgetized area:

<div id="search-3" class="widget widget_search">
	<h4>Search</h4>
	<form role="search" method="get" id="searchform" action="http://localhost/283/" >
		<div>
			<label class="screen-reader-text" for="s">Search for:</label>
			<input type="text" value="" name="s" id="s" />
			<input type="submit" id="searchsubmit" value="Search" />
		</div>
	</form>
</div>

Note the markup created for the opening <div>, which gets its attribute information based on the wild-card matching specified in our widgetizing array. To see this more clearly, examine the following side-by-side comparison of the sprintf directives and the resulting (X)HTML source code:

'before_widget' => '<div id="%1$s" class="widget %2$s">',
<div id="search-3" class="widget widget_search">

Hopefully the relationship is clear. This is a powerful way to ensure that all widgets have a similar class names and unique IDs, which are important for easy CSS styles.

Let’s continue with Step 2..

Widgetize Your WordPress Theme: Step 2

Finally, add the following code to the location in your theme’s template file(s) where you would like the widgetized area to appear:

<div id="widgetized-area">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('widgetized-area')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Area</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

With both steps complete, your theme should now feature a widgetized area in the location of your choosing. Nothing else needs to be done at this point. If you get it, then get to it and continue developing your theme. For more information and some juicy tips and tricks, continue reading.

Let’s examine the code used in this second step. Everything located between the if/endif statements will be output to the browser when no widgets have been activated. This is a good place to inform the user that the area is widgetized and may be customized via the Widgets area in the WordPress Admin. I also include a “pre-widget” class to help style the pre-widget area. With multiple widgetized areas on a page, having a class name to hang styles on is super nice.

Also, note that we are using the id specified in the widgetizing array (refer to Step 1) as the parameter value for the specific dynamic_sidebar() check in the third line.

Multiple widgetized areas

So we now have a nice, widgetized sidebar. But why stop there? Implementing additional widgetized areas is as simple as replicating the code in Step 1 and Step 2. For example, let’s say we wanted to widgetize the header, sidebar, and footer areas of our theme. We would be put this in our functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Header',
		'id'   => 'header',
		'description'   => 'This is the widgetized header.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Sidebar',
		'id'   => 'sidebar',
		'description'   => 'This is the widgetized sidebar.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Footer',
		'id'   => 'footer',
		'description'   => 'This is the widgetized footer.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

..and then we would place the following code chunks into their respective locations within our theme template files:

<div id="widgetized-header">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('header')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Header</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-sidebar">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('sidebar')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Sidebar</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-footer">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('footer')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Footer</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

That’s all there is to it. Of course, you’ll probably want to tweak the details to suit your specific needs, but these two steps are all you need to widgetize your WordPress theme. Now let’s wrap things up with some juicy widgetizing tricks..

Some Juicy Widgetizing Tricks

Here are some sweet little tips for widgetizing your theme:

Streamline & organize custom widgets

The first thing that I do after widgetizing a new theme is to include a separate “widgets.php” that contains all of the custom widgets. A simple line of code is all that is required to acheive this functionality:

if ($wp_version >= 2.8) require_once(TEMPLATEPATH.'/widgets.php');

Place that code into your functions.php file and place all of your widgets into a file called widgets.php. Once in place, this method will ensure that your widgets are loaded and available for all supportive versions of WordPress. This is a great way to keep your theme files nice and organized.

Replace WordPress’ default widgets

Many of the default WordPress widgets leave something to be desired. Fortunately, it’s super-easy to override any of the default widgets with your own creations. For example, here is one way to replace the default Search Widget with your own version:

<?php function custom_search_widget() { ?>

<form action="http://localhost/283/index.php" method="get">
	<div>
		<label for="s">Site Search</label>
		<input id="s" name="s" alt="Search" type="text" />
	</div>
</form>

<?php } if (function_exists('register_sidebar_widget'))

register_sidebar_widget(__('Search'), 'custom_search_widget'); ?>

Hide unused widget areas

An empty widgetized area of your theme can look strange, especially when CSS styles are applied to the container element. To prevent this from happening, we can wrap each of our widgetized areas with the following code:

<?php if (function_exists('is_sidebar_active') && is_sidebar_active('sidebar')) { ?>

<!-- code from Step 2 or whatever you want -->

<?php } ?>

With this conditional code, widgetized areas will only be displayed if they contain at least one active widget. Nice :) Also note that this conditional technique works for displaying things other than widgets.

More..?

Hopefully this easy two-step widgetizing guide will be useful for you during your next round of theme development. As always, if you know of any other sweet widgetizing tricks, please share them in the comments!

© 2010 Digging into WordPress | Permalink | 24 comments | Add to del.icio.us | Post tags: PHP, Theme, widgets

Widgetize!

If you are looking to add text to your sidebar, and your sidebar is already widgetized, this becomes trivially easy. In your Admin, go to Appearance > Widgets and drag the “text” widget into the your sidebar area on the right. You can then open up that widget and give it a title and text and save it.

Adding Multiple Regions

There is a good chance that if your theme is widgetized, the only widgetable area is the sidebar. But you are by no means limited to having only one widgetized area. In order to add another, open your functions.php file and add another chunk of code like this:

if ( function_exists('register_sidebar') ) {
   register_sidebar(array(
       'name'=>'Footer Widgets',
       'before_widget' => '<div id="%1$s" class="widget %2$s">',
       'after_widget' => '</div>',
       'before_title' => '<h4 class="widgettitle">',
       'after_title' => '</h4>',
   ));
}

The ‘name’ part is important, because we’ll be referencing that in a sec when we drop in the widgetization code. Most of the rest of this should be pretty self-explanatory. You provide the HTML code for what wraps the text you provide for a title and body of the widget. Those weird characters as part of the ID and class actually provide some nice useful hooks for each widget. The ID is literally a unique ID for the widget, and the classes designate the type of widget being used. The end result markup for a simple text widget will be something like this:

<div class="widget widget_text" id="text-4">
   <div class="textwidget">
       <p>©2009 Digging into WordPress</p>
   </div>
</div>

As you may have gathered, we are making an editable region in our footer to house the copyright information. In our footer.php file, we’ll drop in this code in an appropriate place to widgetize the area:

<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Footer Widgets') ) : ?>
<?php endif; ?>

All goes well, we now have a new widget area showing up in our Admin, in which to drag in widgets. Drag in a text widget, and you should be all set. It should be noted that while text widgets have a title and text area, you don’t have to use both, you can use one or the other if you want.

Fairly basic stuff, but this is great stuff for allowing users to be in more complete command of their sites!

© 2009 Digging into WordPress | Permalink | 21 comments | Add to del.icio.us | Post tags: HTML, maintenance, template, Theme, widgets