Commit 505e3939 authored by alexpott's avatar alexpott

Issue #2373741 by Wim Leers, hussainweb: Move bulk of render pipeline...

Issue #2373741 by Wim Leers, hussainweb: Move bulk of render pipeline documentation to d.o handbooks
parent 1c72fda1
...@@ -209,6 +209,7 @@ ...@@ -209,6 +209,7 @@
* *
* For further information on the Theme and Render APIs, see: * For further information on the Theme and Render APIs, see:
* - * -
* -
* - * -
* - * -
* - * -
...@@ -355,79 +356,47 @@ ...@@ -355,79 +356,47 @@
* *
* See drupal_process_attached() for additional information. * See drupal_process_attached() for additional information.
* *
* @section render_pipeline The Render Pipeline (or: how Drupal renders pages) * @section render_pipeline The Render Pipeline
* First, you need to know the general routing concepts: please read * The term "render pipeline" refers to the process Drupal uses to take
* @ref sec_controller first. * information provided by modules and render it into a response. For more
* * details on this process, see;
* Any route that returns the "main content" as a render array automatically has * for background on routing concepts, see @ref sec_controller.
* 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 * There are in fact multiple render pipelines:
* around the main content). * - Drupal always uses the Symfony render pipeline. See
* *
* After the controller returned a render array, the @code VIEW @endcode event * - Within the Symfony render pipeline, there is a Drupal render pipeline,
* (\Symfony\Component\HttpKernel\KernelEvents::VIEW) will be triggered, because * which handles controllers that return render arrays. (Symfony's render
* the controller result is not a Response, but a render array. * pipeline only knows how to deal with Response objects; this pipeline
* * converts render arrays into Response objects.) These render arrays are
* \Drupal\Core\EventSubscriber\MainContentViewSubscriber is subscribed to the * considered the main content, and can be rendered into multiple formats:
* @code VIEW @endcode event. It checks whether the controller result is an * HTML, Ajax, dialog, and modal. Modules can add support for more formats, by
* array, and if so, guarantees to generate a Response. * implementing a main content renderer, which is a service tagged with
* * 'render.main_content_renderer'.
* Next, it checks whether the negotiated request format is supported. Any * - Finally, within the HTML main content renderer, there is another pipeline,
* format for which a main content renderer service exists (an implementation of * to allow for rendering the page containing the main content in multiple
* \Drupal\Core\Render\MainContent\MainContentRendererInterface) is supported. * 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
* If the negotiated request format is not supported, a 406 JSON response is * content). Modules can provide additional options, by implementing a page
* generated, which lists the supported formats in a machine-readable way(as per * variant, which is a plugin annotated with
* RFC 2616, section 10.4.7). * \Drupal\Core\Display\Annotation\PageDisplayVariant.
* *
* Otherwise, when the negotiated request format is supported, the corresponding * Routes whose controllers return a \Symfony\Component\HttpFoundation\Response
* main content renderer service is initialized. A response is generated by * object are fully handled by the Symfony render pipeline.
* calling \Drupal\Core\Render\MainContent\MainContentRendererInterface::renderResponse() *
* on the service. That's it! * 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"
* Each main content renderer service can choose how to implement its * manner, as described above.
* 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
* *
* @see themeable * @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
* *
* @} * @}
*/ */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment