Skip to content

GitLab

Commit 505e3939 authored by alexpott's avatar alexpott
Browse files

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
Hide whitespace changes
Inline Side-by-side
core/modules/system/theme.api.php
View file @ 505e3939
......@@ -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
*
* @}
*/
......
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