Persisted WordPress Admin Notices: Part 1

WordPress admin notices provide a convenient way to display messages to users in the admin area, e.g. after a post has been updated or a plugin has been activated. They’re also used by many themes and plugins to display notifications about anything from new features or security warnings to details about ongoing promotions or upgrade prompts.

WordPress core provides four different admin notices which can be used contextually to alert a user to a specific type of notice. This is achieved by displaying a unique accent color for each type of admin notice.

Admin notices are usually displayed at the top of every admin page to stand out from the main page content and be clearly noticeable. They are elegantly designed so as to not be too visually distracting.

WordPress also reuses admin notices in other locations throughout the admin interface, such as when a theme or plugin update is available. Core usage of admin notices isn’t limited to just being displayed at the top of the admin screen.

Displaying an admin notice in a custom plugin or theme is relatively easy, requiring just a few lines of code, as we’ll discover shortly. However, WordPress doesn’t provide a way by default to dismiss a persisted admin notice.

Even though you can add a dismiss button to any admin notice, this doesn’t prevent it from reappearing when the page is reloaded. Also, admin notices appear on every admin page, which is far from ideal.

If you want to have granular control over exactly when and where admin notices are displayed and to be able to dismiss them effectively, you’ll need to add custom code to modify the default behavior.

What We’ll Be Covering

We’ll start at the beginning and explore the basics of implementing admin notices via a custom plugin, including displaying them only on specific pages in the WordPress admin.

Admin notices appear on every page by default, which isn’t always what you want. For instance, you may only want to display a notification on a plugin options page. So our next port of call will be to conditionally display admin notices depending on the current admin screen.

Building on this, we’ll introduce ways to further manage admin notices by controlling when they appear too. Rather than appearing as soon as the page loads, they will only appear if certain triggering conditions are met. This could be useful, for example, if you wanted to display an admin notice on a plugin options page, but only after settings had been saved.

As mentioned above, there’s no easy way to dismiss persisted admin notices between page loads. So the remainder of the tutorial series will focus mainly on various methods you can employ to dismiss admin notices so they won’t reappear unexpectedly.

Finally, for a bit of fun, we’ll see how you can create your own custom admin notice types and add additional decoration such as icons to your admin notices.

By the end of this tutorial series, you’ll be able to display any type of admin notice anywhere within the WordPress admin. Plus, you’ll be able to decide whether to show them on page load or via a custom action, and you’ll also be able to dismiss them in a variety of different ways, depending on your needs.

Want to Follow Along?

You’ll get most out of this tutorial series if you follow along as we build out each admin notice example. The code is presented in a step-by-step approach to allow you to build a working plugin on your own as we progress through the tutorial. However, if you don’t wish to type in all the code yourself, the finished plugin will be available for download in part four.

It’s assumed that you have at least a rudimentary working knowledge of WordPress plugin development, including how hooks work. If not, then I’d recommend reading up on these topics via the official WordPress documentation before continuing:

• Introduction to Plugin Development
• Writing a Plugin
• WordPress Hooks

In order to test the plugin code for each example, you’ll need a working WordPress site. The easiest way to do this is to install WordPress locally so you have easy access to edit files. 

There are many choices for developing locally with WordPress, including:

• Local by Flywheel
• DesktopServer
• MAMP (and MAMP PRO)
• Vagrant

If you’re new to WordPress development then Local or DesktopServer are probably easiest to set up. Local is free to use (they have a premium version in the works), and DesktopServer has a limited (free) version plus a premium version available.

Also, some previous experience of PHP and JavaScript is recommended, as is some experience of implementing Ajax requests. However, everything will be explained along the way, so in-depth knowledge isn’t required.

A Closer Look at Admin Notices

Let’s take a look at the most basic implementation of an admin notice and the code required to render a success type notice.

function display_admin_notice() {
  ?>
  
The secret to success is to know something nobody else knows ~ Aristotle Onassis
  

All we did here was to register the display_admin_notice() function that will be run when the admin_notices hook fires. It doesn't matter what the registered function is called—it won't affect how the admin notice is rendered.
Don't worry about entering the code above yourself right now; just focus on how the admin notice is generated as we'll be building on this in later tutorials.
You can use any markup you like to display an admin notice; however, the recommended format is as follows:
{message}
Replace {class} with a list of CSS class names. You should include the class notice plus any one of the following classes to determine the type of admin notice:



notice-error (red)



notice-warning (yellow/orange)



notice-success (green)



notice-info (blue)



The {message} block can be any text or valid HTML which will be displayed inside the admin notice.
The example above shows admin notices on all admin pages, which isn't always ideal, so in part two we'll look at how you can control exactly what pages they appear on.
There is another built-in CSS class you can add to div.notice that adds a dismiss button to the admin notice. Let's see what happens when the same success admin notice has the is-dismissible class added to it.
function display_admin_notice() {
  ?>
  
The secret to success is to know something nobody else knows ~ Aristotle Onassis
  

We now have an easy way to dismiss an admin notice. However, before you get too excited, there's a problem with using this method. If you refresh the page, the admin notice reappears! So, even though you can set an admin notice to be dismissible, it's persistent, and the dismissed status is forgotten between page loads.
We'll be covering persistent admin notices in detail later on and exploring various ways you can dismiss them without them reappearing.
But Admin Notices Are Bad! Aren't They?

If you're at all familiar with admin notices in WordPress and/or keep up with WordPress news in general then you may be aware of a certain amount of negativity regarding using admin notices in custom plugins and themes.
This stems from some plugins overusing admin notices in an attempt to get their 'important' messages across. If you have a lot of plugins installed and just a few of them abuse the admin notice system then you can quickly end up with admin notice 'soup', where a whole tangle of notices are displayed at the top of every admin page.
Overloading admin screens with unnecessary notices can cause chaos (and headaches) and is understandably annoying for users as it makes managing a site more difficult.
Ideally, only important admin notices, such as critical security updates, should be displayed on every page load. If you're displaying global admin notices to tell users a plugin has just been updated, and prompt to click a link for more information, then you should really ask yourself whether this needs to be on every admin page.
Also, a typical favorite is to display a non-critical admin notice that can't easily be permanently dismissed. I guarantee you there is no easier way to alienate your plugin users than by doing this!
However, there are use cases for persistent notices that aren't dismissible, such as database updates. Plugins that use custom tables may need to run database update routines once in a while to keep the plugin running correctly. So, in this case, it's reasonable to add a non-dismissible admin notice.
A good rule of thumb is to just employ common sense. Would the admin notice you're about to add to your plugin annoy you as a user? If so, you might want to rethink adding the notice, or consider if it would be better displayed in an alternative location.
Conclusion
In this tutorial, we've covered what admin notices are and the various built-in types provided by WordPress, including a dismissible admin notice. As we've seen, there are some drawbacks to the default implementation of admin notices, such as not being dismissible and the fact they are rendered on every admin page.
WordPress has an incredibly active economy. There are themes, plugins, libraries, and many other products that help you build out your site and project. The open-source nature of the platform also makes it a great option from which you can better your programming skills. Whatever the case, you can see what we have available Envato Market.
The rest of the tutorials in this series will focus on how we can extend admin notices to be more practical when used in your own plugins and themes.