From 505e39393b9a28d411d1a5d805db1a43c2c43e8b Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Sun, 22 Mar 2015 15:38:27 +0000
Subject: [PATCH] Issue #2373741 by Wim Leers, hussainweb: Move bulk of render
 pipeline documentation to d.o handbooks

---
 core/modules/system/theme.api.php | 111 +++++++++++-------------------
 1 file changed, 40 insertions(+), 71 deletions(-)

diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index a70f47fd64ca..79334e086413 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -209,6 +209,7 @@
  *
  * For further information on the Theme and Render APIs, see:
  * - https://drupal.org/documentation/theme
+ * - https://www.drupal.org/developing/api/8/render
  * - https://drupal.org/node/722174
  * - https://drupal.org/node/933976
  * - https://drupal.org/node/930760
@@ -355,79 +356,47 @@
  *
  * See drupal_process_attached() for additional information.
  *
- * @section render_pipeline The Render Pipeline (or: how Drupal renders pages)
- * First, you need to know the general routing concepts: please read
- * @ref sec_controller first.
- *
- * Any route that returns the "main content" as a render array automatically has
- * the ability to be requested in multiple ways: it can be rendered in a certain
- * format (HTML, JSON …) and/or in a certain decorated manner (e.g. with blocks
- * around the main content).
- *
- * After the controller returned a render array, the @code VIEW @endcode event
- * (\Symfony\Component\HttpKernel\KernelEvents::VIEW) will be triggered, because
- * the controller result is not a Response, but a render array.
- *
- * \Drupal\Core\EventSubscriber\MainContentViewSubscriber is subscribed to the
- * @code VIEW @endcode event. It checks whether the controller result is an
- * array, and if so, guarantees to generate a Response.
- *
- * Next, it checks whether the negotiated request format is supported. Any
- * format for which a main content renderer service exists (an implementation of
- * \Drupal\Core\Render\MainContent\MainContentRendererInterface) is supported.
- *
- * If the negotiated request format is not supported, a 406 JSON response is
- * generated, which lists the supported formats in a machine-readable way(as per
- * RFC 2616, section 10.4.7).
- *
- * Otherwise, when the negotiated request format is supported, the corresponding
- * main content renderer service is initialized. A response is generated by
- * calling \Drupal\Core\Render\MainContent\MainContentRendererInterface::renderResponse()
- * on the service. That's it!
- *
- * Each main content renderer service can choose how to implement its
- * renderResponse() method. It may of course choose to add protected helper
- * methods to provide more structure, if it's a complex main content renderer.
- *
- * The above is the general flow. But let's take a look at the HTML main content
- * renderer (\Drupal\Core\Render\MainContent\HtmlRenderer), because that will be
- * used most often.
- *
- * \Drupal\Core\Render\MainContent\HtmlRenderer::renderResponse() first calls a
- * helper method, @code prepare() @endcode, which takes the main content render
- * array and returns a #type 'page' render array. A #type 'page' render array
- * represents the final <body> for the HTML document (page.html.twig). The
- * remaining task for @code renderResponse() @endcode is to wrap the #type
- * 'page' render array in a #type 'html' render array, which then represents the
- * entire HTML document (html.html.twig).
- * Hence the steps are:
- * 1. \Drupal\Core\Render\MainContent\HtmlRenderer::prepare() takes the main
- *    content render array; if it already is #type 'page', then most of the work
- *    it must do is already done. In the other case, we need to build that #type
- *    'page' render array still. The RenderEvents::SELECT_PAGE_DISPLAY_VARIANT
- *    event is dispatched, to select a page display variant. By default,
- *    \Drupal\Core\Render\Plugin\DisplayVariant\SimplePageVariant is used, which
- *    doesn't apply any decorations. But, when Block module is enabled,
- *    \Drupal\block\Plugin\DisplayVariant\BlockPageVariant is used, which allows
- *    the site builder to place blocks in any of the page regions, and hence
- *    "decorate" the main content.
- * 2. \Drupal\Core\Render\MainContent\HtmlRenderer::prepare() now is guaranteed
- *    to be working on a #type 'page' render array. hook_page_attachments() and
- *    hook_page_attachments_alter() are invoked.
- * 3. \Drupal\Core\Render\MainContent\HtmlRenderer::renderResponse() uses the
- *    #type 'page' render array returned by the previous step and wraps it in
- *    #type 'html'. hook_page_top() and hook_page_bottom() are invoked.
- * 4. drupal_render() is called on the #type 'html' render array, which uses
- *    the html.html.twig template and the return value is a HTML document as a
- *    string.
- * 5. This string of HTML is returned as the Response.
- *
- * For HTML pages to be rendered in limited environments, such as when you are
- * installing or updating Drupal, or when you put it in maintenance mode, or
- * when an error occurs, a simpler HTML page renderer is used for rendering
- * these bare pages: \Drupal\Core\Render\BareHtmlPageRenderer
+ * @section render_pipeline The Render Pipeline
+ * The term "render pipeline" refers to the process Drupal uses to take
+ * information provided by modules and render it into a response. For more
+ * details on this process, see https://www.drupal.org/developing/api/8/render;
+ * for background on routing concepts, see @ref sec_controller.
+ *
+ * There are in fact multiple render pipelines:
+ * - Drupal always uses the Symfony render pipeline. See
+ *   http://symfony.com/doc/2.7/components/http_kernel/introduction.html
+ * - Within the Symfony render pipeline, there is a Drupal render pipeline,
+ *   which handles controllers that return render arrays. (Symfony's render
+ *   pipeline only knows how to deal with Response objects; this pipeline
+ *   converts render arrays into Response objects.) These render arrays are
+ *   considered the main content, and can be rendered into multiple formats:
+ *   HTML, Ajax, dialog, and modal. Modules can add support for more formats, by
+ *   implementing a main content renderer, which is a service tagged with
+ *   'render.main_content_renderer'.
+ * - Finally, within the HTML main content renderer, there is another pipeline,
+ *   to allow for rendering the page containing the main content in multiple
+ *   ways: no decoration at all (just a page showing the main content) or blocks
+ *   (a page with regions, with blocks positioned in regions around the main
+ *   content). Modules can provide additional options, by implementing a page
+ *   variant, which is a plugin annotated with
+ *   \Drupal\Core\Display\Annotation\PageDisplayVariant.
+ *
+ * Routes whose controllers return a \Symfony\Component\HttpFoundation\Response
+ * object are fully handled by the Symfony render pipeline.
+ *
+ * Routes whose controllers return the "main content" as a render array can be
+ * requested in multiple formats (HTML, JSON, etc.) and/or in a "decorated"
+ * manner, as described above.
  *
  * @see themeable
+ * @see \Symfony\Component\HttpKernel\KernelEvents::VIEW
+ * @see \Drupal\Core\EventSubscriber\MainContentViewSubscriber
+ * @see \Drupal\Core\Render\MainContent\MainContentRendererInterface
+ * @see \Drupal\Core\Render\MainContent\HtmlRenderer
+ * @see \Drupal\Core\Render\RenderEvents::SELECT_PAGE_DISPLAY_VARIANT
+ * @see \Drupal\Core\Render\Plugin\DisplayVariant\SimplePageVariant
+ * @see \Drupal\block\Plugin\DisplayVariant\BlockPageVariant
+ * @see \Drupal\Core\Render\BareHtmlPageRenderer
  *
  * @}
  */
-- 
GitLab