Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Issue #3455342 by vladimiraus, bharath-kondeti, smustgrave: Improve Drupal\Core\Ajax\MessageCommand API documentation

merge-requests/8968/head
catch 2024-08-30 16:33:52 +09:00
parent 143acfe4bc
commit ca51d6e99c
1 changed files with 44 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
core/lib/Drupal/Core/Ajax/MessageCommand.php
View File

@ -7,21 +7,59 @@ use Drupal\Core\Asset\AttachedAssets;
/**
* AJAX command for a JavaScript Drupal.message() call.
*
* Developers should be extra careful if this command and
* \Drupal\Core\Ajax\AnnounceCommand are included in the same 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.
* 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
*/