function drupal_set_message

You are here

7 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE)
4.6 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
4.7 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
5 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
6 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE)
8 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE)

Set a message which reflects the status of the performed operation.

If the function is called with no arguments, this function returns all set messages without clearing them.

Parameters

$message: The message should begin with a capital letter and always ends with a period '.'.

$type: The type of the message. One of the following values are possible:

  • 'status'
  • 'warning'
  • 'error'

$repeat: If this is FALSE and the message is already set, then the message won't be repeated.

169 calls to drupal_set_message()
aggregator_categorize_items_submit in modules/aggregator/aggregator.pages.inc
Process aggregator_categorize_items form submissions.
aggregator_form_category_submit in modules/aggregator/aggregator.admin.inc
Process aggregator_form_category form submissions.
aggregator_form_feed_submit in modules/aggregator/aggregator.admin.inc
Process aggregator_form_feed form submissions.
aggregator_parse_feed in modules/aggregator/aggregator.module
Parse a feed and store its items.
aggregator_refresh in modules/aggregator/aggregator.module
Checks a news feed for new items.

... See full list

File

includes/bootstrap.inc, line 991
Functions that need to be loaded on every Drupal request.

Code

function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) {
  if ($message) {
    if (!isset($_SESSION['messages'])) {
      $_SESSION['messages'] = array();
    }

    if (!isset($_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type] = array();
    }

    if ($repeat || !in_array($message, $_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type][] = $message;
    }
  }

  // messages not set when DB connection fails
  return isset($_SESSION['messages']) ? $_SESSION['messages'] : NULL;
}

Comments

Note that $message is interpreted as HTML. If you have plaintext strings such as for example node titles or user names, you must convert them to HTML with check_plain or use the correct placeholder in t(). If you don't, the message might be malformed and users can execute a cross site scripting attack against your site.

<?php
// Incorrect:
drupal_set_message("Saved $node->title.");
drupal_set_message(t("Saved $node->title."));
drupal_set_message(t('Saved !title.', array('!title' => $node->title)));

// Correct:
drupal_set_message(t('Saved @title.', array('@title' => $node->title)));
drupal_set_message(t('Saved %title.', array('%title' => $node->title)));
?>

If you have user supplied HTML that must be passed to drupal_set_message, filter it so it contains only harmless tags:

<?php
// Incorrect:
drupal_set_message($user_supplied_html);

// Correct:
drupal_set_message(filter_xss($user_supplied_html));
?>

While the documentation says that $type should be either status, error or warning - this isn't actually enforced

It is possible to use alternative types and this will result in a different CSS class being used

<?php
drupal_set_message
('test', 'test');
?>

Outputs

<div class="messages test">
<ul>
  <li>test</li>
</ul>
</div>

If you provide the CSS for class 'test' then you are able to add an additional type of message which could be styled differently.

You can use

drupal_get_messages('status');

to clear all status messages and leave errors intact.

It would be Really Nifty (tm) if some sort of standard, or even vague descriptive prose, were included defining what constitutes an 'error', 'warning' or 'status'...

While I totally agree with you about this page needing a bit more info, like what color text, how big padding is, etc., you can find out all this info by examining one of Drupal's CSS sheets. This is all for Drupal 6, not sure how it goes in 7 (I imagine it's very similar).

The sheet you want is: system.css

It can be found in: drupal_install_path/modules/system

Where drupal_install_path is the root folder Drupal is installed in (it's called drupal for me and I'm not sure if that's default). So my css is found here:

/drupal/modules/system/system.css

Going in here you can look for the elements named warning and error. In Drupal 6, at least, there is an additional type called 'ok'. It just prints messages in a green background instead of red (error) or yellow (warning). The info for the 'status' type doesn't appear to be in this CSS, but using the status type merely prints the message like a Devel dpm print (that may be because Devel is installed though), in other words in a large green box with a white background and as a bullet-ed list.

You can also add your own custom CSS classes that can be used with drupal_set_message to this file, though this does count as hacking core and is never recommended and generally frowned upon. If you follow the syntax already found in the core, it's easy to make your own custom class. If you wanted to make your own 'testing' class to use with drupal_set_message, you could use some code like this (the colors I picked are terribly ugly):

.testing {
    color: #00CC00;
}

div.testing {
   border: 1px solid #200;
}

div.testing, tr.testing {
   background: #FF0066;
   color: #FFFFFF;
   padding: 2px;
}

Which would be invoked with:

drupal_set_message('Testing warning', 'testing');

Now you can, technically, add this class to the system.css file, but you really shouldn't. A better idea is to make your own custom CSS file. So make one, place it somewhere (somewhere within your module folder would be best) and then you need to add it to the function or page you want to use it on. You do that through: drupal_add_css. Let's say our module is named: my_module and our custom CSS sheet is named my_css.css. This custom CSS sheet is located within the themes folder which is in the root folder for my_module (path would be: /drupal/sites/all/modules/my_module/themes/my_css.css). So, to add that particular CSS sheet to your function/page, you would use this command:

drupal_add_css(drupal_get_path('module', 'my_module') . '/themes/my_css.css');

This adds the CSS sheet to wherever you need it to. In adding this sheet you need to be concerned with pre-processing. To learn more about it and when it should be used, follow the link above to the documentation on drupal_add_css(). You can then use this to create your testing message:

drupal_set_message('test message', 'testing');

However, even if you forget to add/move your CSS to your release server, it's not catastrophic. Specifying a type that doesn't exist just formats the message into a plain white box with black text and a black border. The spacing, however, is actually better if you specify a type that doesn't exist.

Not specifying a type defaults to status. You will have the message printed like a Devel dpm.

I thought it might be a good idea to include the CSS code, so here are all three elements found in the Drupal 6 system.css file that correspond with drupal_set_message:

.error {
  color: #e55;
}
div.error {
  border: 1px solid #d77;
}
div.error, tr.error {
  background: #fcc;
  color: #200;
  padding: 2px;
}
.warning {
  color: #e09010;
}
div.warning {
  border: 1px solid #f0c020;
}
div.warning, tr.warning {
  background: #ffd;
  color: #220;
  padding: 2px;
}
.ok {
  color: #008000;
}
div.ok {
  border: 1px solid #00aa00;
}
div.ok, tr.ok {
  background: #dfd;
  color: #020;
  padding: 2px;
}

Hope this helps!