Epic Alex | WordPress Tutorials

Theme and Plugin Authors: Easily Add an RSS Widget to the Dashboard

I’ve been working on a project lately, and needed to add an RSS widget to the Dashboard via a theme or plugin, and was surprised to find that there were no tutorials offering all the code, just tutorials on how to add a widget, but with no content. So here goes, how to create and add an RSS dashboard widget from a theme or plugin.

The Scenario

Say for example you are a plugin author, and you wanted to be able to let your users know the latest news from your plugin development blog, but you don’t have an options page to display that information, we’ll here is the perfect place. Some people might say that this doesn’t allow users any control over whether they see this information or not, but by using the Dashboard Widget API, we are automatically offered the option to remove the widget via the ‘Screen Options’ tab.

Creating the Widget

The WordPress Codex, as usual, is both useful and frustrating at the same time. By looking at the Dashboard Widget API we see that there is a very simple method for creating a widget, but it doesn’t do anything. Let’s take a look at that code

1
2
3

function example_dashboard_widget_function() {
	echo "Hello World, I'm a great Dashboard Widget";
}

• Quite simply, this is the function that creates the output of our widget, we’ll reference that function name later.
• Then, inside the widget, we add whatever it is we want to output. We’ll look at the RSS part lower down.

Telling WordPress about the Widget

Now that we’ve created the widget, we need to tell WordPress that it is there and that we want it shown.

4
5
6

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');	
}

• We create a function that will be used in our action hook
• Then use the ‘main tool’ in adding widgets, wp_add_dashboard_widget
• This function takes up to 4 parameters
• • The identifying name for your widget. It is important to make this unique, as it will be used in the CSS and as the widget’s key when stored in the array in the database
  • Then we add the title of our widget
  • The third parameter is where we reference the function we created above that outputs the widget’s content
  • The last parameter (not used here) is the name of a function you create that will deal with any options you want in your widget. We’ll look at using this below in our RSS example

Hooking in our Function

Now that we have built our widget and told WordPress it exists, we need to make sure it get put in with all the other widgets, to do this, we make use of WordPress’ action hooks, in this case wp_dashboard_setup

7

add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

• Not much explanation needed here, simply hook example_add_dashboard_widgets into wp_dashboard_setup

And we’re done creating our widget.

Adding an RSS Feed

You’re going to be in for a surprise here, it’s soo easy!

Looking at the Default Widgets file on line 752, we can see that the function wp_widget_rss_output is there, and accepts arguments in an array, which then builds our RSS output for us, excellent!

The default arguments that we can use to tell WordPress what to do with the feed are defined on line 777.

1

$default_args = array( 'show_author' => 0, 'show_date' => 0, 'show_summary' => 0 );

There is also a variable set up on line 781 for the amount of items to show.

So essentially we only need to call one function and pass it some args and we have our RSS widget. Let’s see that code in use.

1

wp_widget_rss_output('http://feeds.feedburner.com/epicalex', array('items' => 5, 'show_author' => 1, 'show_date' => 1, 'show_summary' => 0));

• First of all we pass the feed we want to parse
• Then we pass our arguments
• For show_author, show_date and show_summary a 0 means off and a 1 means on

All the Code

I say all the code, there’s not really that much!

1
2
3
4
5
6
7
8
9

function example_dashboard_widget_function() {
	wp_widget_rss_output('http://feeds.feedburner.com/epicalex', array('items' => 5, 'show_author' => 1, 'show_date' => 1, 'show_summary' => 0));
} 
 
function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');	
} 
 
add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

And there we are, done!

Next Steps

I decided not to add in controls for the RSS like the built in Dashboard widgets have for two reasons. As a theme or plugin author, you’re not going to want your users changing the feed address to another site. As well as that, what else is there they’d want to change that desperately; it’s minimal information, can be hidden or removed, revealed and re-added.

Have fun!