Learn how to integrate admin notices into your WordPress plugins. Using the techniques provided in this tutorial, you can display the default WordPress admin notices or create your own, using any markup that's desired.
- [Instructor] If you've used WordPress for any length of time, you're familiar with admin notices. For example, on just about any screen in the admin area, admin notices are displayed near the top of the page. So whenever you save your changes, or if there is an error, warning or whatever, WordPress displays an admin notice like this one here. Admin notices are important because they help the user understand what is happening behind the scenes, when they click to update options, make changes and so forth.
You can see admin notices in action with the plugin that we've created from Chapter Three of this course. So how do we do this? That's what this video is all about. In general, there are two scenarios for admin notices. First, if the plugin has its settings page located under the Settings menu, then WordPress takes care of all the admin notices automatically. Otherwise, if the plugin settings are located in any other location, the admin notices are not displayed automatically.
To see an example, let's change the location of our plugin settings page. Using the plugin demo that we built in Chapter Three, we can change the location of the menu item by editing the admin-menu.php file, located in the admin directory. As explained in Chapter Three, this file includes the code required to display our plugin in the WordPress administrative menu. This first function displays the plugin's menu item under the Settings menu.
It does so using the add_submenu_page function. Then the second function displays the plugin on its own top-level menu using the add_menu_page function. Currently this function is disabled and this function is enabled. So we could easily swap these two functions by commenting out the hook for the first function, like so, and enabling the hook for the second function.
Then we save changes and return to the admin area. Now we can see that the plugin menu has moved and is now positioned as a top-level menu. Now let's try the admin notices again by clicking Save Changes. Notice how the admin notices are not displayed automatically. This is because our plugin no longer is included under the Settings menu. So to enable admin notices, in this case, we need to add a function named settings_errors. There are two ways to add the settings_errors function.
To see the first way, let's open up the settings-page.php file. As explained in Chapter Three, this file contains the code required to display the plugin settings page. There is only one function in this file. This function is called from the function that adds the plugin's menu page, right here in admin-menu.php.
So to add the admin notices, we need to add the WordPress function settings_errors, which we can add right after the h1 tag. That's all there is to it. Let's check the results. Here on the plugin page, we click Save Changes again, and presto, admin notices are once again displayed.
So if adding the settings_errors function is too easy for you, there is an alternate way to add admin notices. To save some time, we can grab the complete code from the exercise files. Now we can add the code at the end of the settings-page.php file, like so. With this function in place, we want to remove the settings_errors function that we added previously.
This way, there aren't two sets of admin notices. In our new function, we are adding settings_errors via the admin_notices hook. It is very straightforward. Now let's save the changes and check the results. Back in the admin area, we refresh the page and then click Save Changes, and we see that the admin notices also work great when implemented via our custom function and the admin notices hook. Before wrapping up this tutorial, let's look at how to add a custom admin notice.
To see how it's done, let's replace this function with a complete custom function from the exercise files. We copy the code, and then replace the previous function, like so. This new code does several things. First, it uses the get_current_screen function to get the current screen, which we check in the next line. This is to make sure that our custom admin notice is displayed only on our plugin page.
Then, we grab the GET variable and check if the settings were updated successfully. If so, we display a custom success notice. Otherwise, if there is an error, then we display a custom error notice. As before, we are registering our function with the admin notices hook. Now let's check the results of our custom admin notice on the plugin page. We reload the page, and then click to save changes, and now we see our custom notice displayed as expected.
See, here we display our custom message instead of the default WordPress message. Let's take a closer look at the HTML that's used to display the custom admin notice. This is the standard recommended markup used to display admin notices. This markup is the same for any notice that we want to display. The only difference is the message itself and this part of the class attribute.
Notice that this second class name is notice-success to specify a success message. And for the error message, the class name is notice-error. These classes determines the color of the notice which is red for errors and green for successful results. Here is a summary of the class names that you can use to display different types of notices. Try experimenting with them to see how they work. Note that technically, you can use whatever markup is desired to display your custom messages, but keep in mind that good plugins integrate tightly with the admin interface.
So don't go too crazy. Here is a good article that explains some reasons why this is important. There are lots of good ideas in the comments of this post as well. For more information about creating admin notices, check out these free resources.
- WordPress APIs
- Action and filter hooks
- Activating and deactivating plugins
- Plugin security
- Creating the directory and files
- Adding menus and the settings page
- Inserting custom functionality
- Testing and debugging WordPress plugins
- Creating widgets
- Managing users and roles
- Adding custom post types and taxonomies
- Working with custom fields and database queries
- Using APIs: Transients, HTTP, and REST