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

Issue #3451136 by quietone, gapple, ghost of drupal past: Improve documentation of AttachmentsInterface methods 

(cherry picked from commit d820d8ed3e)
merge-requests/9339/head
Dave Long 2024-08-22 22:46:38 +01:00
parent 73ced19530
commit db4e4e5426
No known key found for this signature in database
GPG Key ID: ED52AE211E142771
2 changed files with 32 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
core/lib/Drupal/Core/Render/AttachmentsInterface.php
View File

@ -3,7 +3,31 @@
namespace Drupal\Core\Render; namespace Drupal\Core\Render;
/** /**
* Defines an interface for responses that can expose #attached metadata. * The attached metadata collection for a renderable element.
*
* Libraries, JavaScript settings, feeds, HTML <head> tags, HTML <head> links,
* HTTP headers, and the HTTP status code are attached to render arrays using
* the #attached property. The #attached property is an associative array, where
* the keys are the attachment types and the values are the attached data. For
* example:
*
* @code
* $build['#attached']['library'][] = 'core/jquery';
* $build['#attached']['http_header'] = [
* ['Content-Type', 'application/rss+xml; charset=utf-8'],
* ];
* @endcode
*
* The keys used by core are:
* - drupalSettings: (optional) JavaScript settings.
* - feed: (optional) RSS feeds.
* - html_head: (optional) Tags used in HTML <head>.
* - html_head_link: (optional) The <link> tags in HTML <head>.
* - http_header: (optional) HTTP headers and status code.
* - html_response_attachment_placeholders: (optional) Placeholders used in a
* response attachment
* - library: (optional) Asset libraries.
* - placeholders: (optional) Any placeholders.
* *
* @todo If in Drupal 9, we remove attachments other than assets (libraries + * @todo If in Drupal 9, we remove attachments other than assets (libraries +
* drupalSettings), then we can look into unifying this with * drupalSettings), then we can look into unifying this with
@ -14,15 +38,15 @@ namespace Drupal\Core\Render;
interface AttachmentsInterface { interface AttachmentsInterface {
/** /**
* Gets attachments. * Gets this object's attached collection.
* *
* @return array * @return array
* The attachments. * The attachments array.
*/ */
public function getAttachments(); public function getAttachments();
/** /**
* Adds attachments. * Merges an array of attached data into this object's collection.
* *
* @param array $attachments * @param array $attachments
* The attachments to add. * The attachments to add.
@ -32,7 +56,7 @@ interface AttachmentsInterface {
public function addAttachments(array $attachments); public function addAttachments(array $attachments);
/** /**
* Sets attachments. * Replaces this object's attached data with the provided array.
* *
* @param array $attachments * @param array $attachments
* The attachments to set. * The attachments to set.

26
core/lib/Drupal/Core/Render/AttachmentsResponseProcessorInterface.php
View File

@ -7,6 +7,7 @@ namespace Drupal\Core\Render;
* *
* @see \Drupal\Core\Ajax\AjaxResponse * @see \Drupal\Core\Ajax\AjaxResponse
* @see \Drupal\Core\Ajax\AjaxResponseAttachmentsProcessor * @see \Drupal\Core\Ajax\AjaxResponseAttachmentsProcessor
* @see \Drupal\Core\Render\AttachmentsInterface
* @see \Drupal\Core\Render\HtmlResponse * @see \Drupal\Core\Render\HtmlResponse
* @see \Drupal\Core\Render\HtmlResponseAttachmentsProcessor * @see \Drupal\Core\Render\HtmlResponseAttachmentsProcessor
*/ */
@ -15,29 +16,6 @@ interface AttachmentsResponseProcessorInterface {
/** /**
* Processes the attachments of a response that has attachments. * Processes the attachments of a response that has attachments.
* *
* Libraries, JavaScript settings, feeds, HTML <head> tags, HTML <head> links,
* HTTP headers, and the HTTP status code are attached to render arrays using
* the #attached property. The #attached property is an associative array,
* where the keys are the attachment types and the values are the attached
* data. For example:
*
* @code
* $build['#attached']['library'][] = [
* 'library' => ['core/jquery']
* ];
* $build['#attached']['http_header'] = [
* ['Content-Type', 'application/rss+xml; charset=utf-8'],
* ];
* @endcode
*
* The available keys are:
* - 'library' (asset libraries)
* - 'drupalSettings' (JavaScript settings)
* - 'feed' (RSS feeds)
* - 'html_head' (tags in HTML <head>)
* - 'html_head_link' (<link> tags in HTML <head>)
* - 'http_header' (HTTP headers and status code)
*
* Placeholders need to be rendered first in order to have all attachments * Placeholders need to be rendered first in order to have all attachments
* available for processing. For an example, see * available for processing. For an example, see
* \Drupal\Core\Render\HtmlResponseAttachmentsProcessor::renderPlaceholders() * \Drupal\Core\Render\HtmlResponseAttachmentsProcessor::renderPlaceholders()
@ -52,6 +30,8 @@ interface AttachmentsResponseProcessorInterface {
* @throws \InvalidArgumentException * @throws \InvalidArgumentException
* Thrown when the $response parameter is not the type of response object * Thrown when the $response parameter is not the type of response object
* the processor expects. * the processor expects.
*
* @see \Drupal\Core\Render\AttachmentsInterface
*/ */
public function processAttachments(AttachmentsInterface $response); public function processAttachments(AttachmentsInterface $response);