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;
/**
* 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 +
* drupalSettings), then we can look into unifying this with
@ -14,15 +38,15 @@ namespace Drupal\Core\Render;
interface AttachmentsInterface {
/**
* Gets attachments.
* Gets this object's attached collection.
*
* @return array
* The attachments.
* The attachments array.
*/
public function getAttachments();
/**
* Adds attachments.
* Merges an array of attached data into this object's collection.
*
* @param array $attachments
* The attachments to add.
@ -32,7 +56,7 @@ interface AttachmentsInterface {
public function addAttachments(array $attachments);
/**
* Sets attachments.
* Replaces this object's attached data with the provided array.
*
* @param array $attachments
* 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\AjaxResponseAttachmentsProcessor
* @see \Drupal\Core\Render\AttachmentsInterface
* @see \Drupal\Core\Render\HtmlResponse
* @see \Drupal\Core\Render\HtmlResponseAttachmentsProcessor
*/
@ -15,29 +16,6 @@ interface AttachmentsResponseProcessorInterface {
/**
* 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
* available for processing. For an example, see
* \Drupal\Core\Render\HtmlResponseAttachmentsProcessor::renderPlaceholders()
@ -52,6 +30,8 @@ interface AttachmentsResponseProcessorInterface {
* @throws \InvalidArgumentException
* Thrown when the $response parameter is not the type of response object
* the processor expects.
*
* @see \Drupal\Core\Render\AttachmentsInterface
*/
public function processAttachments(AttachmentsInterface $response);