From 505e39393b9a28d411d1a5d805db1a43c2c43e8b Mon Sep 17 00:00:00 2001 From: Alex Pott 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 a70f47fd64..79334e0864 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 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