src/Render/BigPipeInterface.php | 34 ++++++++++++++++++++++++++--------
1 file changed, 26 insertions(+), 8 deletions(-)
diff --git a/src/Render/BigPipeInterface.php b/src/Render/BigPipeInterface.php
index c583c30..55a5a3d 100644
--- a/src/Render/BigPipeInterface.php
+++ b/src/Render/BigPipeInterface.php
@@ -55,6 +55,11 @@ namespace Drupal\big_pipe\Render;
* Finally, a closer look at the implementation, and how it supports and reuses
* existing Drupal concepts:
* 1. BigPipe placeholders: 1 HtmlResponse + N embedded AjaxResponses.
+ * - Before a BigPipe response is sent, it is just a HTML response that
+ * contains BigPipe placeholders. Those placeholders look like
+ * . JavaScript is used to
+ * replace those placeholders.
+ * Therefore these placeholders are actually sent to the client.
* - The Skeleton of course has attachments, including most notably asset
* libraries. And those we track in drupalSettings.ajaxPageState.libraries —
* so that when we load new content through AJAX, we don't load the same
@@ -76,7 +81,20 @@ namespace Drupal\big_pipe\Render;
* AJAX page state of the HTML document and all preceding Embedded AJAX
* responses.
* 2. No-JS BigPipe placeholders: 1 HtmlResponse + N embedded HtmlResponses.
- * - See first bullet of point 1.
+ * - Before a BigPipe response is sent, it is just a HTML response that
+ * contains no-JS BigPipe placeholders. Those placeholders can take two
+ * different forms:
+ * 1. if it's a
+ * placeholder that will be replaced by HTML
+ * 2. big_pipe_nojs_placeholder_attribute_safe:… if it's a placeholder
+ * inside a HTML attribute, in which 1. would be invalid (angle brackets
+ * are not allowed inside HTML attributes)
+ * No-JS BigPipe placeholders are not replaced using JavaScript, they must
+ * be replaced upon sending the BigPipe response. So, while the response is
+ * being sent, upon encountering these placeholders, their corresponding
+ * placeholder replacements are sent instead.
+ * Therefore these placeholders are never actually sent to the client.
+ * - See second bullet of point 1.
* - No-JS BigPipe does not use multiple AJAX requests/responses. It uses a
* single HTML response. But it is a more long-lived one: The Skeleton is
* split into multiple parts, the separators are where the no-JS BigPipe
@@ -99,17 +117,17 @@ namespace Drupal\big_pipe\Render;
* Combining all of the above, when using both BigPipe placeholders and no-JS
* BigPipe placeholders, we therefore send: 1 HtmlResponse + M Embedded HTML
* Responses + N Embedded AJAX Responses. Schematically, we send these chunks:
- * 1. Byte zero until no-JS placeholder: headers +