Plugin Planet

This tutorial provides code snippets to customize the USP Pro Dashboard Widget. These are all plug-&-play functions that can be added to your theme’s functions.php file, or added via your own custom plugin.

About the Dashboard Widget

By default, for USP Pro 3.7 and beyond:

• The Dashboard Widget is displayed to all admins and editors
• For admins and editors, the widget displays posts from all users
• For all other roles, the widget will display any posts from the current logged in user

To customize this behavior, check out the techniques provided below.

Customize the Dashboard Widget

Here are some simple code techniques for customizing the default widget display.

Display draft/pending posts only

Prior to USP Pro version 3.7, the Dashboard Widget displayed only posts that were not yet published (e.g., posts with Draft or Pending status). To restore that functionality, add the following code to your WordPress functions or simple plugin:

// usp pro dashboard widget display drafts only
function usp_widget_drafts_display($display) {
	
	return false;
	
}
add_filter('usp_widget_drafts_display', 'usp_widget_drafts_display');

No edits are required, simply copy/paste save changes and done.

Display posts to other user roles

By default, all posts are displayed to admin and editor-level users. To add more roles to that list, add the following code to your WordPress functions or simple plugin:

// usp pro dashboard widget add roles
function usp_widget_display_all_posts($roles) {
	
	return array('administrator', 'editor'); // add roles to this array
	
}
add_filter('usp_widget_display_all_posts', 'usp_widget_display_all_posts');

Then add the role name to the return array. For example, to add the author and contributor roles, the return line would look like this:

return array('administrator', 'editor', 'author', 'contributor');

And so forth, for whichever roles are required. Also you can remove either of the default roles, if necessary.

Display widget to any specific user(s)

Here is how to customize the user(s) for which the Dashboard Widget should be displayed. First, to display the Dashboard Widget to all logged-in users, add the following code snippet to your (child) theme’s functions.php file or simple plugin:

// usp pro dashboard widget all users
function usp_widget_drafts_user($users) {
	
	return '';
	
}
add_filter('usp_widget_drafts_user', 'usp_widget_drafts_user');

No modifications are required, simply upload and done. Notice that this function returns an empty string to the usp_widget_drafts_user filter, which then will query submitted posts for all users. By changing the return value, it would be possible to display the widget to any user or set of users. Check out the WP_Query Author Parameters for more possibilities.

Include posts from any post type

To include posts from additional post type(s), add the following code snippet to your (child) theme’s functions.php file or simple plugin:

// usp pro dashboard widget include post types
function usp_widget_drafts_type($types) {
	
	return array('post', 'page', 'usp_post', 'my-post-type'); // add CPTs to this array
	
}
add_filter('usp_widget_drafts_type', 'usp_widget_drafts_type');

Before uploading this code, make sure to edit the returned array, replacing my-post-type with the name of the post type that you would like to add. Check out the Custom Post Types tutorial for more information. Also check out the WP_Query Type Parameters for more ideas.

Include posts of any post status

To include posts of any post status, add the following code snippet to your (child) theme’s functions.php file or simple plugin:

// usp pro dashboard widget include post status
function usp_widget_drafts_status($status) {
	
	return array('draft', 'future', 'pending', 'publish'); // add status to this array
	
}
add_filter('usp_widget_drafts_status', 'usp_widget_drafts_status');

Before uploading this code, make sure to edit the returned array, replacing publish with the name of the post status that you would like to add. Check out the Custom Post Status tutorial for more information. Also check out the WP_Query Status Parameters for more ideas.

Change number of displayed posts

By default the dashboard widget displays all drafts. To change that to any number, use the following code:

// usp pro dashboard widget drafts number
function usp_widget_drafts_number($number) {
	
	return -1; // default is -1 = display all draft posts
	
}
add_filter('usp_widget_drafts_number', 'usp_widget_drafts_number');

Replace the -1 (display all posts) with whatever number of posts you would like to display.

Further customization

Further customization is possible using any of the filter hooks provided for the USP Dashboard Widget. Here is a complete list:

usp_widget_drafts_display
usp_widget_drafts_message_none
usp_widget_drafts_message_some
usp_widget_drafts_user
usp_widget_drafts_number
usp_widget_drafts_type
usp_widget_drafts_status
usp_widget_drafts_time

To view these hooks within their code context, visit the plugin file /inc/usp-dashboard.php.