blog

In part one of this series, we learned how to implement a basic admin notice that appears at the top of every WordPress admin page. In this tutorial, we’ll start to build out a plugin to contain all our custom admin notice code.

We’ll begin by implementing standard admin notices and use them as a base for more flexible and advanced examples.

Setting Up Our Plugin

First, though, let’s set up a new plugin from scratch that we’ll be using for all our admin notices so we’re ready to start entering code.

I’ll assume here that you already have a local WP development site set up. If not then refer back to the links in part one of this tutorial series.

Create a new plugin folder called admin_notices inside /wp-content/plugins/, and then create an admin_notices.php file which will be the main plugin file.

Open up admin_notices.php in your favorite editor and add the basic plugin structure:

<?php

/*
Plugin Name: Admin Notices
Description: Display your own custom admin notices.
Version: 0.1
Author: David Gwyer
Author URI: http://www.wpgoplugins.com
*/

class Gwyer_Admin_Notices {

  /**
  * Register hooks.
  */
  public function init() {
    // Add code here...
  }
}

$gwyer_admin_notices = new Gwyer_Admin_Notices();
$gwyer_admin_notices->init();

We added a basic plugin header so WordPress recognises our plugin. This is followed by a class that will contain methods to display our admin notices.

I named the class Gwyer_Admin_Notices to try and make it as unique as possible. This way, it’s much less likely to conflict with an existing class name.

Let’s start by displaying a basic admin notice, and then add to it to make it more useful. To create an admin notice, add the admin_notices hook to the init() function:

add_action( 'admin_notices', array( $this, 'test_notice' ) );

The hook includes a test_notice callback function which will be used to output the admin notice markup.

Add the following class method to Gwyer_Admin_Notices to display the actual admin notice. For the messages, we’ll be using classic movie quotes from the last 100 years of movies.

/**
* Output a test admin notice.
*/

public function test_notice() {
  ?>
  <div class="notice notice-error"><p>Yoo hoo, big summer blow out.</p></div>
  <?php
}

Activate the plugin to show the test notice.

Let’s also add examples of the other types of admin notice we can display including the dismissible type by adding the is-dismissible CSS class. Add these to the test_notice() method underneath the existing admin notice div:

<div class="notice notice-warning"><p>Toto, I've a feeling we're not in Kansas anymore.</p></div>
<div class="notice notice-success"><p>You had me at "hello".</p></div>
<div class="notice notice-info"><p>Of all the gin joints in all the towns in all the world, she walks into mine.</p></div>
<div class="notice notice-success is-dismissible"><p>Nobody puts Baby in a corner.</p></div>

This is the full array of admin notice types we can display via the WordPress core CSS classes. Remember, though, that the dismissible admin notice will reappear on each page load!

‘Dismissible’ admin notice in this context means only for the current page. Having persistent admin notices isn’t very flexible, so later on we’ll be specifically looking at different ways you can dismiss your admin notices effectively.

Admin Notice Hooks

So far, we’ve only used the admin_notice hook to implement an admin notice. There are in fact four separate admin notice hooks that you can use to display notifications, but admin_notice is the one most commonly used.

The four hooks available are:

• admin_notices (used in most circumstances)
• network_admin_notices
• all_admin_notices^*
• user_admin_notices^*

^*No official documentation currently available for these hooks.

So where would you typically use all_admin_notices, user_admin_notices, and network_admin_notices? And how do they differ from admin_notices?

I said previously that the admin_notices hook displays notifications on all admin pages, but this isn’t strictly true. If you take a look at admin-header.php in WordPress core, you’ll see that admin_notices, network_admin_notices, and user_admin_notices are mutually exclusive. That is, only one of these hooks fires on a WordPress admin page.

A series of conditional expressions evaluates the current admin page and fires just one of them depending on the type of admin page you’re currently on.

Firstly, is_network_admin() checks to see if you’re on a network admin screen (e.g. any admin page based on a /wp-admin/network/ URL). If so, the network_admin_notices hook fires.

Otherwise, is_user_admin() checks to see if you’re on a user admin screen (e.g. any admin page based on a /wp-admin/user/ URL). If so, the user_admin_notices hook fires. 

And, as you might have guessed, if both is_network_admin() and is_user_admin() return false then the admin_notices hook fires.

That just leaves the all_admin_notices hook. This hook isn’t part of the conditional expression discussed above, so this hook is guaranteed to display on all admin pages no matter what, including multisite network admin pages.

To clarify, for any WordPress admin page, only the all_admin_notices hook is guaranteed to always fire. Out of the other three hooks, only one will fire depending on the admin page you’re currently on.

I’d encourage you to take a look at admin-header.php (towards the end of the file) to see for yourself how WordPress evaluates when to use each admin notices hook.

We’ll only be using admin_notices throughout this tutorial series, but you may find you have a need for some of the other hooks in your own project, so it’s well worth checking them out.

Displaying Admin Notices on Specific Pages

Let’s turn our attention now to displaying admin notices on specific pages. First, comment out the call to add_action so our test notices aren’t displayed anymore.

Inside init(), add a new add_action() call that we’ll use to display an admin notice on one specific admin page.

add_action( 'admin_notices', array( $this, 'specific_admin_page' ) );

Then define the specific_admin_page() method as follows:

/**
* Output an admin notice on a specific admin screen.
*/

public function specific_admin_page() {

  $admin_page = get_current_screen();
  ?>
  <div class="notice notice-info"><p>Information: We are currently on the <strong><?php echo $admin_page->base; ?></strong> admin page.</p></div>
  <?php
}

Save your changes and view any page in the WordPress admin. I’ll try the main dashboard page.

As you can see, for any admin page you visit, the (base) name of the page is being displayed in the admin notice.

The get_current_screen() function returns a WP_Screen object with details about the current admin screen. The particular object property we’re interested in is WP_Screen->base, which evaluates to the base type of the current screen. Try loading different WordPress admin pages to see what values are returned for WP_Screen->base.

We can use the base value to conditionally load our admin notice only on the dashboard page. The value we need to check for is dashboard. Let’s also show an alternative admin notice if we aren’t on the admin dashboard page. Replace your definition of specific_admin_page() with:

/**
* Output an admin notice on a specific admin screen.
*/
public function specific_admin_page() {

  $admin_page = get_current_screen();

  if( $admin_page->base == "dashboard" ) :
    ?>
    <div class="notice notice-success"><p>We made it! Welcome to the dashboard.</p></div>
    <?php
  else :
    ?>
    <div class="notice notice-error"><p>Where did you go? This isn't the dashboard!</p></div>
    <?php
  endif;
}

Everything’s fine when we’re on the dashboard page, but try navigating to any other admin page and see what happens.

Using this simple approach gives us quite a bit of flexibility when displaying admin notices on specific admin pages. We can easily extend this to whitelist any number of admin pages we want to show admin notices on.

Once again, replace the specific_admin_pages() function, this time with the following code:

/**
* Output an admin notice on a specific admin screen.
*/
public function specific_admin_page() {

  $whitelist_admin_pages = array( 'dashboard', 'upload', 'edit-comments' );
  $admin_page = get_current_screen();

  if( in_array( $admin_page->base, $whitelist_admin_pages ) ) :
    ?>
    <div class="notice notice-success"><p>We made it! This is the '<?php echo $admin_page->base; ?>' admin page.</p></div>
    <?php
  else :
    ?>
    <div class="notice notice-error"><p>Not on your nelly! This page isn't on my list.</p></div>
    <?php
  endif;
}

Instead of checking for a single admin page, we now check to see if the base name for the current admin page is in the $whitelist_admin_pages array. When we navigate to the dashboard, media library, or comments admin pages, we see our success admin notice.

And when we visit any other admin page (not included in our whitelist array), we see an alternate admin notice.

What about displaying an admin notice on a plugin options page? How would we go about that? Before we get into this, we first need to set up a dummy options page for our plugin.

Create a new file called plugin-options.php inside the admin-notices plugin folder we added earlier, and add the following code:

<?php

class Gwyer_Plugin_Options {
 
    /**
    * Register hooks.
    */
    public function init() {
      add_action( 'admin_init', array( $this, 'register_plugin_settings' ) );
      add_action('admin_menu', array( $this, 'create_admin_menu_page' ) );
    }

    public function create_admin_menu_page() {

        // Create new top-level menu
        add_options_page('Admin Notices', 'Admin Notices', 'manage_options', __FILE__, array( $this, 'render_options_page' ) );
    }

    public function register_plugin_settings() {
        register_setting( 'admin-notices-plugin-settings', 'text-option' );
    }

    public function render_options_page() {
      ?>
      <div class="wrap">
        <h1>Admin Notices Plugin</h1>

        <form method="post" action="options.php">
          <?php settings_fields( 'admin-notices-plugin-settings' ); ?>
          <?php do_settings_sections( 'admin-notices-plugin-settings' ); ?>
          <table class="form-table">
            <tr valign="top">
              <th scope="row">Enter some text</th>
              <td><input type="text" name="text-option" value="<?php echo esc_attr( get_option( 'text-option' ) ); ?>" /></td>
            </tr>
          </table>    
          <?php submit_button(); ?>
        </form>
      </div>
      <?php
    }
}
 
$gwyer_plugin_options = new Gwyer_Plugin_Options();
$gwyer_plugin_options->init();

At the top of admin-notices.php (directly above the class declaration), include the plugin options class into the main plugin file with:

require_once(dirname(__FILE__) . '/plugin-options.php' );

I’m not going into too much detail on how the code in plugin-options.php works as that could be a whole tutorial on its own! If you want a refresher then I’d recommend taking a look at the WordPress Codex page on adding plugin options pages.

Basically, all we’re doing is adding a new Admin Notices subpage to the Settings menu. The plugin options page itself contains a single text field which you can enter a string into. When the Save Changes button is clicked, the contents of the text field are saved to the WordPress database.

This is only a bare-bones example of a plugin settings page just for demonstration. It doesn’t include the necessary sanitization or translation functions recommended for a production plugin intended for general release.

Go to Settings > Admin Notices to view the plugin options page.

As expected, the admin notice we added previously displays on our plugin options page. The error message is displayed because our plugin options page isn’t in the $whitelist_admin_pages array of allowed admin pages. Let’s fix that now.

In order to add our options page to the array, we need to know the base name. Inside specific_admin_page(), change the error admin notice div to the following:

<div class="notice notice-error"><p>Not on your nelly! This '<?php echo $admin_page->base; ?>' page isn't on my list.</p></div>

We still get the same error admin notice as before, but this time it includes the base name we need, which turns out to be settings_page_admin-notices/plugin-options. That’s not a name we could have easily guessed, so it was worth taking the time to output it!

Add the base name to the $whitelist_admin_pages array, which should now look like this:

$whitelist_admin_pages = array(
  'settings_page_admin-notices/plugin-options',
  'dashboard',
  'upload',
  'edit-comments'
);

Refresh the plugin options page to see the updated admin notice.

Now that we know the plugin options page base name, we can easily create an admin notice that only displays on that admin page. Remove settings_page_admin-notices/plugin-options from the $whitelist_admin_pages array and comment out the second add_action function call in init(). Then add a third action we’ll use for our plugin options page only admin notice. Your init() function should now look like this:

/**
* Register hooks.
*/
public function init() {
  //add_action( 'admin_notices', array( $this, 'test_notice' ) );
  //add_action( 'admin_notices', array( $this, 'specific_admin_page' ) );
  add_action( 'admin_notices', array( $this, 'plugin_admin_notice' ) );
}

Let’s flesh out the plugin_admin_notice() callback function now. Add this new method to the Gwyer_Admin_Notices class:

/**
* Output an admin notice on the plugin options page.
*/
public function plugin_admin_notice() {

  $whitelist_admin_pages = array( 'settings_page_admin-notices/plugin-options' );
  $admin_page = get_current_screen();

  if( in_array( $admin_page->base, $whitelist_admin_pages ) ) :
    ?>
    <div class="notice notice-info"><p>Welcome to the Admin Notices plugin page!</p></div>
    <?php
  endif;
}

This is very similar to specific_admin_page() except we’ve removed the conditional expression. We also added a dismissible button by adding the is-dismissible CSS class, so the admin notice can now be closed too.

Try loading other admin pages to confirm that the admin notice only displays on the plugin options page.

Conclusion

In this tutorial, we learned more about admin notices and the various hooks available for displaying them. We also covered how to display admin notices only on specific pages of the WordPress admin. We developed a dedicated plugin to contain all the custom admin notice code.

In part three, we’ll further extend the plugin by showing how to trigger admin notices when certain events occur. Remember, the open-source nature of WordPress makes it easy to learn and extend. To that end, we have much to review and study in Envato Market if you’re curious.

We’ll then turn our attention to finding out how we can solve the persistent admin notice issue so that they don’t reappear when the page is refreshed. We’ll implement several different methods in our custom plugin to allow us to do this.