 Hey there, and welcome to Learn WordPress. In this tutorial, you're going to learn about the WordPress Dashboard Widgets API. You will learn what the Dashboard Widgets API is, why you might want to use it, and how to add a Dashboard widget to your WordPress site. The Dashboard Widgets API is a series of functions that allows you to add, remove and modify the widgets that appear in the WordPress dashboard. This can be handy if you want a direct way to interact with your users, either to show them some information, or allow them to perform a specific action. Here are a few examples of some custom Dashboard Widgets in action. The Jetpack plugin adds a widget that shows you your site's stats, top posts and pages. The Seriously Simple Stats add-on plugin for Seriously Simple Podcasting shows your episode's stats, and the Seriously Simple Podcasting plugin also includes an RSS feed widget for Castos News, which is the company that owns and develops Seriously Simple Podcasting. Since WordPress version 2.7, the Dashboard Widgets API makes it straightforward to add new widgets to the WordPress Administration Dashboard. The main function you need to know about is the wp-add-dashboard-widget function. This function takes a number of parameters. The widget ID, which is a unique ID for your widget, and is also used as the ID attribute in the widget's HTML output. The widget name, the name of your widget. And the callback function, which is a function that will be called to output the contents of your widget. This function should echo the contents of the widget. Additionally, there are some optional parameters you can add. The control callback, an optional function that will be called to output controls to configure data for the widget, as well as process any data that has been submitted by the controls. The callback args, an optional array of arguments that will be passed to your callback function. The context, an optional string that defines the column that your widget will be shown in. The default is normal, but other options include side, column 3 and column 4. And finally, priority, an optional string that defines the priority of your widget within the context. The default is call, but other options also include default, high and low. To understand how all this works, let's build an example dashboard widget. To start, create a new plugin directory and plugin PHP file in the wp-content-plugins directory. For this example, you can just call it wp-learn-dashboard-widgets. For this plugin to be recognized as a WordPress plugin, you need to add a plugin header, with at minimum a value for plugin name. I will just call this wp-learn-dashboard-widgets. As with most WordPress APIs, you'll start by hooking into an action. In the case of a dashboard widget, you can use the wp-dashboard-setup action, which is fired when the dashboard is initialized. This is where you'll add your widget. So we'll start by saying add action, wp-dashboard-setup, and then we'll define a callback function, which will allow us to register our widget. Then we can create that function. And inside of that function, we can call the wp-add-dashboard-widget function. And let's give it an id, let's give it a name, and specify the callback function, that will render the widget's content. And then with that in place, we can register that callback function. And for now we can just echo something simple, like hello world. Once you've added this code to the empty plugin file and enabled the plugin, you should see the widget at the bottom of the first column of the dashboard if you refresh the dashboard. So in our dashboard, first we need to enable the plugin, and if we switch back to the dashboard, there is our hello world widget. You have a lot of flexibility with your content callback function, as long as it echoes valid HTML. For example, you could add a list of the most recent posts to your widget using the wp-get-recent-post function. So let's set up some arguments for that function. And we'll say number of posts to display is 5, and we want all posts with the post status of publish to display all published posts. Then we can create a variable called recent posts, and call the wp-get-recent-post function and pass in the arguments we just specified and fix the arguments array because it's missing a comma. And then we could, for example, echo the posts in an unordered list and do something like for each recent posts as recent posts. So looping through that list of posts, and then we could echo a list item with an anchor tag and link of the recent post, passing in the id, we want to close that anchor tag, and then we might want to get the post title, with the anchor tag and the list item. And then finally we should close the unordered list. And then let's take a look at what that does in the dashboard. And if I switch back to my dashboard and hit refresh, scroll right down to the bottom, the widget is showing the last five published posts. You can also add some controls to configure your widget. Let's say you want to control how many posts are displayed. To do that you can configure the control callback function. Start by adding a function called wp-learn-dashboard-widget-control to process the data. So let's scroll down a bit and let's go to function wp-learn-dashboard-widget-control. And here we will just echo a label, give our user some direction, and we'll also echo a field. Make it a text field, give it a name value that we can work with when the form is posted, and then let's close that input field. And then we need to specify this in the control callback parameter, which is the one directly after the display callback. When you refresh the dashboard, nothing appears to happen to the widget, but if you hover over the widget name, you'll see a new link appear that says configure. Clicking on that link will display the form that you just created. So you'll see that by specifying the label and the input in the control callback, it automatically generates a form containing that HTML and a save changes button. Now you need to update the control callback to process the data that is submitted by the form. To save the data in the database, you can use the update option function, which will store the value in the options table. So what we can do is we can check if the number of posts field has been posted in the PHP post array. So it's dollar underscore post, and it'll be the name of the field. So if it's set, then the first thing we should do is get that value and make sure we sanitize it using sanitized text field so that nothing insecure can get sent to that variable. There's an extra bracket there. And then we can use update option, which if it doesn't exist will create this option in the database. We can use the same name as the text field if we want to. And then we want to pass that number of posts value. There we go. Then after that, we want to fetch the number of posts from the database because this is when the widget is rendered the first time or any time it's rendered in the dashboard. We want to fetch that value. So we will say get option, and the option name will be that one. And then we want to pass a default value, which we will leave as five. So what this will do is if the control form has been posted, it'll update that value. If it hasn't been posted and the widget is just being rendered, or even if it has been posted and the widget is being rendered, it'll fetch that value and then use it in the form. So what we can do here is we can say make a default value in the text area and do something like this where we add it as the defaults so that when it's rendering the control, it always fetches it from the database. Then you need to go back to your content callback function and update the args array to use the value you just saw. You can use the getOption function to achieve this. So if we scroll up to rendering callback, here we can use this code getOption to fetch it from the database and then replace that five with the number of posts and the rest should remain the same. So let's test this out. Let us refresh this in the dashboard. There is the default of five. Let's save it to three and hit save. There it's rendering three. Let's configure it with a different value. Let's say seven and it renders one, two, three, four, five, six, seven. For more information on working with dashboard widgets, including examples of how to use the optional callback arguments, context and priority parameters, check out the dashboard widgets API section at developer.wordpress.org. Happy coding!