DISCLAIMER: this post is older than one year and may not be up to date with latest WordPress version.

When writing custom WordPress theme or plugins, you might want to inform users that something important needs doing, perhaps due to an upgrade. e.g. You need the user to update a setting, or check that their settings have been transposed correctly. This is a very short guide that shows you how to add a error or status message using the correct WordPress hooks.

The following is a snippet of my custom function that shows a message to the user. This be used from anywhere in your theme or plugin if you wanted to give the user a standard message. e.g. “Settings successfully updated” or something similar.

/**
 * Generic function to show a message to the user using WP's 
 * standard CSS classes to make use of the already-defined
 * message colour scheme.
 *
 * @param $message The message you want to tell the user.
 * @param $errormsg If true, the message is an error, so use 
 * the red message style. If false, the message is a status 
  * message, so use the yellow information message style.
 */
function showMessage($message, $errormsg = false)
{
	if ($errormsg) {
		echo '<div id="message" class="error">';
	}
	else {
		echo '<div id="message" class="updated fade">';
	}

	echo "<p><strong>$message</strong></p></div>";
}    

Now we just add a hook to the admin notices function to show our custom message.

/**
 * Just show our message (with possible checking if we only want
 * to show message to certain users.
 */
function showAdminMessages()
{
    // Shows as an error message. You could add a link to the right page if you wanted.
    showMessage("You need to upgrade your database as soon as possible...", true);

    // Only show to admins
    if (user_can('manage_options') {
       showMessage("Hello admins!");
    }
}

/** 
  * Call showAdminMessages() when showing other admin 
  * messages. The message only gets shown in the admin
  * area, but not on the frontend of your WordPress site. 
  */
add_action('admin_notices', 'showAdminMessages');     

And that’s all there is to it!

Thanks to Dan Harrison of WordPress Doctors for the tip!

Tags

9 Comments

  1. This is a really good post, because when you have multiple people logging into the back end of wordpress updating and making changes is not always what you want them to do as it can create more work. Warnings like this would be great for clients so they know what to make use of and what to leave well alone!

  2. Nice I have implemented as given. And feeling glad to see my notice on my dashboard. 😀 😛

  3. Thanks for this – just what I needed for my plugin.

    Minor point, but shouldn’t it be:

    if (current_user_can(‘manage_options’)) {. . .

    Or it won’t be able to show the “Hello Admins” message.

  4. /**
    * allow you to send the messages without any functon creation and add_action add only this block and use the showMessage()
    * it will return false if the message is invalide or the messages are already printed
    * $message could also be a array it will be returned nicely in a pre and formated via print_r
    */
    $custom_error_messages = array();
    function showMessage($message, $error = false){
    global $custom_error_messages;
    if($custom_error_messages === false) return false;
    if(is_array($message)) $message = ”.print_r($message,true).”;
    if(!is_string($message) || $message == ”) return null;
    $msg = “”;
    if ($error) $msg = ”;
    else $msg = ”;
    $msg .= “$message”;
    $custom_error_messages[] = $msg;
    return true;
    }
    function render_showMessage(){
    global $custom_error_messages;
    echo implode(”, $custom_error_messages);
    $custom_error_messages = false;
    }
    add_action(‘admin_notices’, ‘render_showMessage’);

  5. please check the code for bad replacements of the comment system (” should be two single’ in some cases)
    also
    if(is_array($message)) $message = ”.print_r($message,true).”;
    should be
    if(is_array($message)) $message = “<pre>”.print_r($message,true).”</pre>”;

  6. I implemented a message-class in my plugin. Every time I call $msgHandler->add(…, …) it will store the message in an message-array. So it is possible to show multiple messages by calling $msgHandler->show() – if desired.

  7. I have implemented this, using a singleton class so I can use this one everywhere. It works like a charm, but (there always is a but) sometimes wordpress redirects the browser, which removes the messages.

    for example, I am hooking into the post save, and all the messages I set there are removed, as the browser is redirected.

    Any solutions for that inside wordpress (I could use a session of course, but If WP already has a solution I would prefer that)?

  8. This is poorly explained and doesn’t work as-is. You forgot a bracket here:
    if (user_can(‘manage_options’)) {

    How can I show a message within a function that uses the publish_post hook? Saying showMessage( $message ) just shows the message and does not return to the dashboard.

  9. Thanks for the code. It was a little confusing due to one of the functions being provided separately, the bracket being missing and the user permissions check being incorrect, but I figured it out and now have a nice error message showing up :)

Leave a Comment

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