Skip to content

Adding WordPress Admin notices with your WordPress Plugin

When you develop a plugin sometimes you need a communication channel with the users that installed the plugin, one easy way to achieve this is showing a WordPress Admin notification on top of pages.

The WordPress admin notifications Plugin API

WordPress has a clear defined API to handle admin notifications, https://codex.wordpress.org/Plugin_API/Action_Reference/admin_notices , adding a notification on the admin is simple as:

function sample_admin_notice__success() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p><?php _e( 'Done!', 'sample-text-domain' ); ?></p>
    </div>
    <?php
}
add_action( 'admin_notices', 'sample_admin_notice__success' );

This will result on the following notification on the top of every of your admin pages.

We can improve the logic behind showing a notice to the user

Improvement 1: Format the message and provide easy action button

In order to make the notification more relevant, we can add some more content into it, a header message would be useful also an action button, that either takes the user to your plugin settings page or even and outside website page.

 <div class="notice notice-success is-dismissible">
 <h4><?php _e("Plugin notice header message"); ?></h4>
 <p><?php _e( 'Humonade Playground plugin as a PRO version, check all PRO version features you are losing!', 'sample-text-domain' ); ?> <a class="button-primary" href="#" title="Check PRO">Check PRO</a></p>
 </div>

On this small change i added the bold areas, a simple header and a button to make it easier for the user to handle the notification.

Improvement 2: Show the notification only on certain admin pages

WordPress has a global variable that provides the page the user is seeing, by using this content you can easily filter on which page(s) you want to show the notification, for instance, only on the dashboard page or maybe only on the plugins list page.

The global $pagenow is the answer for this, on the WordPress documentation for global variables you can find the a more complete definition for this variable.

Let’s suppose we want only to show this notice on top of our plugins listing page, our function would look like:

 function sample_admin_notice__success() {
   global $pagenow;
   
   // Do nothing if we aren't on the page we want to show the notice
   if( 'plugins.php' !== $pagenow )
      return;
    // .... all the other code
 }

Improvement 3: Show the notice only during a period of time

One of the approaches you can take is to show the notice for X days only to the user, after which, it would simply not show anymore. This can be simply achievable by marking when was the notice show to the user for the first time and discard if outside our interval.

We’ll use an options  variable to store and retrieve the notice show time.

// See when was the notice shown
 $get_shown = get_option("myplugin_message_shown");
 
 // Mark message as shown on current date
 if( empty($get_shown) ) {
   $get_shown = date("Y-m-d H:i:s");
   $update_shown = update_option( "myplugin_message_shown", $get_shown );
 }

By doing this, we are storing the current time when was shown the notice to the user.

We only need to perform the validation before adding the notice to the user.

 // Show only for the X days
 $show_interval = "+2 days";
 if( date("Y-m-d H:i:s") > date("Y-m-d H:i:s", strtotime($get_shown." +".$show_interval)) )
     return; // Leave the function if we are outside the interval

The complete code would be something like:

function sample_admin_notice__success() {
 global $pagenow;

if( 'plugins.php' !== $pagenow )
 return;

// See when was the notice shown
 $get_shown = get_option("myplugin_message_shown");

// Mark message as shown on current date
 if( empty($get_shown) ) {
 $get_shown = date("Y-m-d H:i:s");
 $update_shown = update_option( "myplugin_message_shown", $get_shown );
 }

// Show only for the X days
 $show_interval = "+2 days";
 if( date("Y-m-d H:i:s") > date("Y-m-d H:i:s", strtotime($get_shown." +".$show_interval)) )
 return; // Leave the function if we are outside the interval

?>
 <div class="notice notice-success is-dismissible">
 <h4><?php _e("Plugin notice header message"); ?></h4>
 <p><?php _e( 'Humonade Playground plugin as a PRO version, check all PRO version features you are losing!', 'sample-text-domain' ); ?> <a class="button-primary" href="#" title="Check PRO">Check PRO</a></p>
 </div>
 <?php
 }
 add_action( 'admin_notices', 'sample_admin_notice__success' );

 

Hope it helps to understand on how to manage plugin admin notices with WordPress.

Published inRandom Thoughts

One Comment

  1. I built an easy to use PHP Package for displaying admin notices in WordPress without having to remember/write all this boilerplate over and over.

    Maybe it could help someone out: https://github.com/a7/admin-notices

    Enjoy!

    Aaron

Leave a Reply

Your email address will not be published. Required fields are marked *