3.2 Editing the Dashboard Widgets

Hello, and welcome back to this Tuts+ course on WordPress plugin development. In this part of the course, we're going to start working on our second plugin, which will customise the dashboard screens. So let's start by activating it. So I'm going to deactivate my section menus plugin which I created earlier in the course. And then I'm going to activate my customised admin plugin. Now, at the moment, that doesn't do anything, because I haven't added any functions to it. So let's go to the dashboard so we can see what it will do. So here's my plugin file, and I've created a file called tutsplus-customize-admin.php within a folder called tutsplus-customize-admin in my plugins menu in wp-content. Now, even for a plugin that only has one file, I prefer to add a folder and then put my plugin file in that folder. And the reason for this is that if I should choose to add other files within my plugin, such as include files or styling or scripts, I can do so easily without having to then create that folder and start doing that from scratch. But it will still work if you just create that file and you put it in your plugins folder. I prefer having folders in my plugins folder for neatness and consistency. So I'm gonna start by editing the dashboard widgets. So I'll create a function to remove some of the dashboard widgets that we don't want. So there's my function, tutsplus_remove_dashboard_widgets. And that needs to be hooked to a very specific hook, Which is the wp_dashboard_setup hook. So I hook my function here to wp_dashboard_setup. And once you hook your function to that, it will automatically be run by WordPress at the right time. So I'll save that, and at the moment if I refresh my dashboard, it doesn't actually do anything cuz I haven't added any code in there. So let's start by removing a dashboard widget. Now I'm gonna start with this activity widget here, because I want to clean up my dashboard and make it really minimal. So to do that, I use the remove_meta_box function. So here I've added remove_meta_box and its got three parameters. First is the ID of the widget, second is which screen its from and the third is which place in the screen it is. And you can either find out the unique IDs of the metaboxes from the Dashboard Widgets API, or alternatively, you can inspect the code. So if I inspect this, so if we look at this dashboard-widgets-wrap div, which contains all those widgets, and we keep on going right now you can see here you've got a div id dashboard_right_now, dashboard_activity, and that's the one that we need. So this is the div with the ID dashboard activity. And the CSS ID that it's got will be the same as the WordPress ID and what you need to use in your function. So let's just close down that inspect window. I'll save my plugin and I'll refresh the dashboard screen. And you can see the activities disappeared. So there's a lot less content on my dashboard now. I'm going to copy this with some more dashboard widgets. And instead of typing all that out again, I'm gonna add the remove_meta_box function, and I'm going to edit. So the next one I'm removing is dashboard_quick_press. Again, that's in the dashboard. And this time, it's on the side. By side, it means that it's over here on the right hand side. And dashboard_quick_press is the ID of the Quick Draft widget over here. And I don't know about you, but I never ever use this widget. So I'll save that, refresh my dashboard screen, and there it is, even more minimal. Now, this is another widget I never use, and I certainly don't think it's useful for clients. My clients, they're business people, they're not web developers, they're not the slightest bit interested in WordPress Events and News. So I'm gonna remove that one too. Again, I'll copy and paste, and instead of dashboard_quick_press, this one is called dashboard_primary. I'm not quite sure why it's called primary instead of being called events, news, or something like that, but that's what it's called. It's on the dashboard screen, and again, it's on the right hand side. So we'll save that and refresh and it's gone. So I now have a really clean amenable dashboard screen with hardly any widgets on it. So now let's go on to add a widget to my dashboard screen. So I'll create another function. So I'll call it tutsplus_add_welcome_widget and that will need to be hooked to the same wp_dashboard_setup action. So I'm going to copy that, and I'm going to copy the end of my function, and again if I was to save that it wouldn't do anything yet. What I'll do here is I'll use the add_metabox function. Now you have two options for the dashboard for adding metaboxes, and I'll show you them in the APIs. The default is wp_add_dashboard_widget. And this will only add widgets to the dashboard. But if you want more control over where your widget appears, you use add_meta_box instead. So you can see here in the codex it gives it as an advanced tip. And the add_meta_box function, which we'll be using later on in the next part of the course, will add a meta box to any page in the admin screens, not just the dashboard. But because we're including dashboard as a parameter, WordPress will add it to the dashboard. So let's do that. So it has a number of parameters. The first one is the ID of the meta box. Which we'll call, tutsplus_welcome_widget. The next parameter is the title. So this will be seen by users. The third parameter is a callback function, which we'll then use to add content to our widget. And I'll call that tutsplus_welcome_widget_content or, alternatively, you could call it callback, so you know that's a callback function. The fourth parameter is the screen on which it will appear, which is the dashboard, and the fifth parameter is where on the screen it will be. Now I want it, let's go back to our dashboard, I want you it to over here on the right hand side, so it's next to the At a Glance widget. So I'm putting side here. And then finally, we can specify how high up it is. Now there's nothing else there so it'll be at the top by default, but I'm gonna add that just in case any other meta boxes get added later on. Now, if I was to save this, it would throw an error, because with the callback function that's not then used later on in the plugin, and that's not populated, that gives WordPress an error. So let's create that callback function. And I'm going to copy that. So now I can save it. And if I go back and refresh my dashboard screen, you can see we've now got an empty widget called Welcome. So this add_meta_box function will populate the title from this parameter here, Welcome, but I need to also add the HTML for the content using my callback function. Now, rather than make you watch me type out a whole load of HTML, I've created an HTML file called callback. So I'm going to copy the contents of that into my function. It doesn't look right, and that's because I need to close php and then open php again at the end. So that's my callback function, and it has some paragraphs, heading, a list, and lots of information about how to update your site. Now in this one, I've included some information about products and WooCommerce, because I'm imagining that this is for a site where there's a WooCommerce store installed. I haven't actually installed one yet on the site, but it's just to show you that you can add whatever you want. So I'll save that and then go back to my dashboard, and refresh the screen, and there's my Welcome Widget. So that has all of the HTML within it that I've added. So that's how you customize the dashboard screen in the WordPress Admin. In the next part of the course, we'll move on to creating our final plugin, which will display the most recent post in each three categories along with their featured image, and then that will be hooked into the side so we can display it wherever we want. See you next time and thanks for watching.