2.4 Adding Help
Having great documentation is an important aspect of any WordPress theme. But you can take documentation a step further and add help sections inside the WordPress admin area itself.
Let’s find out how.
1.Introduction3 lessons, 06:23
2.Customization: Smaller Tasks6 lessons, 38:49
3.Customization: Bigger Tasks5 lessons, 24:53
4.Conclusion1 lesson, 00:40
2.4 Adding Help
Having a great documentation is an important aspect of any WordPress theme. But you can take this a step further and add help sections directly into the admin UI. Let's find out how. In the WordPress admin, you can add help in two ways. First of all, you can add meta boxes in editing pages, for example. Or you can add help tabs right here on the top. So let's see about meta boxes first. And the function we're gonna use here is called add meta box. And as you can see it takes a few parameters. First of all, the id of the edit screen of the meta box. The title which is gonna be the text displayed in the meta box. And let me actually go to articles. Let's add an article here, so I can show you. So this Publish here, this box is a meta box. And this is the title. And then, you need a callback, which is the function used to display the content of the meta box, and then the screen will basically be the page where you want to add the meta box. You can see, you can choose from post, page, dashboard and so on. And then the context, which you can choose normal, advanced or side. Basically, this determines the position of the meta box. And then the priority. The priority determines how high on the page the meta box will be displayed. So, for our example, let's say we wanna add a meta box in both post end page. So, when we add a post or when we add a page, we need a meta box. Let's say that's on this side right here. So, let's start with this function. We're gonna call it add_help_metaboxes(). And we're gonna tie it into add_meta_boxes, add_help_metaboxes. First, we're gonna define a variable called screens. And that's gonna be basically an array with two items. So we want this meta box to show up in posts and pages. And the we're gonna do a foreach ( $screens as $screen ), we don't need that. We're gonna do the following function add_meta_box. The first parameter is the id. So let's call this helping-metabox. Then it's the title, let's call it Helpful Metabox. Then it's the callback and here we're just gonna say add_help_metaboxes_callback. And then for the screen, we're gonna use our variable $screens, or screen actually because we're in foreach. And then for the context, we're gonna choose advanced. So it's gonna be on the left side. And then for priority, let's go with high, all right. Then let's write the callback function. And then side, we're just gonna echo a symbol paragraph that says, hello, this is a very helpful message. All right, so now, let's check it out. Let's refresh this page and if we scroll down, you're gonna see the Helpful Metabox here, and I just made a typo there. All right, there we go, so our very Helpful Metabox. Now, what if I want to put this on the side here. So for the side, let's actually create another meta box and we're gonna call this helping-metabox-side, Another Helpful Metabox. This one is gonna be add_side_help_metaboxes_callback. It's gonna use the screen, because we also want it in both post and pages, side and priority high, and then let's create the callback function and let's refresh our page. And as you can see, because we set the priority high, it's actually the very first one here, but if I set it to low, it's gonna be pushed all the way down. All right, and that's how you add meta boxes inside these pages. Now let's see about the Help tabs. And Help tabs will show up right here. So for that, we're gonna write a function called add_help_tabs(), which will be tied to in_admin_header. And inside that function, we're gonna start with an if, so if, we're gonna define our variable called '$screen = get_current_screen. And get_current_screen basically gives us the page we're on. We're gonna do this, screen and we're gonna use the function add_help_tab. And this function receives an array as a parameter. So we're gonna say array and we're gonna start with an id. And that's gonna be new_help_tab, and then we're gonna give it a title. It's gonna be Custom Help Tab. And then we're gonna give it a content. And the content, well let's just put in a simple paragraph here that says, this is some very helpful content. All right, so now let's actually refresh this page and let's see. I said, add_hello_tab, no, it's actually add_help_tab, not hello. Let's refresh again and then here we go. In Help, we have our Custom Help Tab. Now this is actually positioned as you see at the very bottom. If you wanna move it to the top, you gotta do something different. So you would do something like this. First of all, you would need to save the current help tabs. And you would do that in a new variable, it's gonna be $help_tabs. It's gonna be equal to $screen->get_help_tabs. Then, you gotta remove the current help tabs from the screen. So you would do $screen->remove_help_tabs. So currently, you don't have any help tabs. Then, you would add the help tab and then, if you do have some help tabs saved. So we can do that with the count functions. So if ( count ( $help_tabs)). So if we had help tabs before, add them back to the screen. So you would do a foreach ( $help_tabs as $help_tab). And you would do $screen->add_help_tab. All right, so now if we refresh, let's see. We have a property at line 196, which is right here. Oh okay, sorry, I forgot the parentheses there. All right, so help. And now, as you can see the custom tab we made is on the very top and we have the rest as well. So, very quickly, let's go over this again. We save the current help tabs in this variable. Then we remove them from the screen, we add our own help tab and then we count the ones we had before. If we have at least one, then we do a foreach to go over every item inside help tabs, and for each of those, we'll add it back to the screen. It's as simple as that. And that's how you add help in the WordPress admin. And that's it for adding admin help areas. Now, we've done quite a bit in terms of customization, but the stuff we did mostly applies on a global level. What if we wanna make specific changes for specific users, well, we'll find out how in the next lesson.