MessageCommand.php
Same filename in other branches
Namespace
Drupal\Core\AjaxFile
-
core/
lib/ Drupal/ Core/ Ajax/ MessageCommand.php
View source
<?php
namespace Drupal\Core\Ajax;
use Drupal\Component\Render\MarkupInterface;
use Drupal\Component\Utility\Xss;
use Drupal\Core\Asset\AttachedAssets;
/**
* AJAX command for a JavaScript Drupal.message() call.
*
* AJAX command that allows you to add messages from an Ajax response. The command will create a new Drupal.Message() object and call its addMessage() method.
*
* Usage examples:
* Here are examples of how to suppress announcements:
* @code
* $response = new AjaxResponse();
*
* // A status message added in the default location.
* $response->addCommand(new MessageCommand('Your changes have been saved.'));
*
* // A warning message added in the default location.
* $response->addCommand(new MessageCommand('There was a problem. Save your work.', NULL, ['type' => 'warning']));
*
* // A status message added an alternate location.
* $response->addCommand(new MessageCommand('Hey look over here!', '#alternate-message-container'));
*
* // An error added in an alternate location.
* $response->addCommand(new MessageCommand('Open the pod bay doors, HAL.', '#alternate-message-container', ['type' => 'error']));
* @endcode
*
* By default, previous messages in a location are cleared before the message
* is added. If you would like to leave the previous messages in a location,
* you may do so by setting the fourth parameter to FALSE:
* Here are examples of how to suppress announcements:
* @code
* $response->addCommand(new MessageCommand('Hey look over here.', NULL, ['type' => 'error'], FALSE));
* @endcode
*
* Developers should take care when using MessageCommand and AnnounceCommand
* together in the same AJAX response. Unless the "announce" option is set to
* an empty string (''), this command will result in the message being
* announced to screen readers. When combined with AnnounceCommand, this may
* result in unexpected behavior. Manual testing with a screen reader is
* strongly recommended.
*
* If you wish to display a message without the text being announced to screen
* readers, add options.announce = '' (i.e. an empty string):
* @code
* $command = new MessageCommand("I won't be announced", NULL, [
* 'announce' => '',
* ]);
* @endcode
*
* If you wish to set the announcement priority to assertive, you can do that
* this way:
* @code
* $response->addCommand(new MessageCommand('You added 3 cat pics.', '.js-media-library-messages', [
* 'priority' => 'assertive',
* ]);
* @endcode
*
* @see \Drupal\Core\Ajax\AnnounceCommand
* @see https://www.drupal.org/docs/develop/drupal-apis/ajax-api/core-ajax-callback-commands#s-messagecommand
*
* @ingroup ajax
*/
class MessageCommand implements CommandInterface, CommandWithAttachedAssetsInterface {
/**
* The message text.
*
* @var string|\Drupal\Component\Render\MarkupInterface
*/
protected $message;
/**
* Whether to clear previous messages.
*
* @var bool
*/
protected $clearPrevious;
/**
* The query selector for the element the message will appear in.
*
* @var string
*/
protected $wrapperQuerySelector;
/**
* The options passed to Drupal.message().add().
*
* @var array
*/
protected $options;
/**
* Constructs a MessageCommand object.
*
* @param string|\Drupal\Component\Render\MarkupInterface $message
* The text of the message.
* @param string|null $wrapper_query_selector
* The query selector of the element to display messages in when they
* should be displayed somewhere other than the default.
* @see Drupal.Message.defaultWrapper()
* @param array $options
* The options passed to Drupal.message().add().
* @param bool $clear_previous
* If TRUE, previous messages will be cleared first.
*/
public function __construct($message, $wrapper_query_selector = NULL, array $options = [], $clear_previous = TRUE) {
$this->message = $message;
$this->wrapperQuerySelector = $wrapper_query_selector;
$this->options = $options;
$this->clearPrevious = $clear_previous;
}
/**
* {@inheritdoc}
*/
public function render() {
return [
'command' => 'message',
'message' => $this->message instanceof MarkupInterface ? (string) $this->message : Xss::filterAdmin($this->message),
'messageWrapperQuerySelector' => $this->wrapperQuerySelector,
'messageOptions' => $this->options,
'clearPrevious' => $this->clearPrevious,
];
}
/**
* {@inheritdoc}
*/
public function getAttachedAssets() {
$assets = new AttachedAssets();
$assets->setLibraries([
'core/drupal.message',
]);
return $assets;
}
}
Classes
Title | Deprecated | Summary |
---|---|---|
MessageCommand | AJAX command for a JavaScript Drupal.message() call. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.