aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Render/BareHtmlPageRendererInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Render;
   4
   5 /**
   6  * Bare HTML page renderer.
   7  *
   8  * By "bare HTML page", we mean that the following hooks that allow for "normal"
   9  * pages are not invoked:
  10  * - hook_page_attachments()
  11  * - hook_page_attachments_alter()
  12  * - hook_page_top()
  13  * - hook_page_bottom()
  14  *
  15  * Examples of bare HTML pages are:
  16  * - install.php
  17  * - update.php
  18  * - authorize.php
  19  * - maintenance mode
  20  * - exception handlers
  21  *
  22  * i.e. use this when rendering HTML pages in limited environments. Otherwise,
  23  * use a @code _controller @endcode route, and return a render array.
  24  * This will cause a main content renderer
  25  * (\Drupal\Core\Render\MainContent\MainContentRendererInterface) to be
  26  * used, and in case of a HTML request that will be
  27  * \Drupal\Core\Render\MainContent\HtmlRenderer.
  28  *
  29  * In fact, this is not only *typically* used in a limited environment, it even
  30  * *must* be used in a limited environment: when using the bare HTML page
  31  * renderer, use as little state/additional services as possible, because the
  32  * same safeguards aren't present (precisely because this is intended to be used
  33  * in a limited environment).
  34  *
  35  * Currently, there are two types of bare pages available:
  36  * - Install (hook_preprocess_install_page(), install-page.html.twig).
  37  * - Maintenance (hook_preprocess_maintenance_page(),
  38  *   maintenance-page.html.twig).
  39  *
  40  * @see \Drupal\Core\Render\MainContent\HtmlRenderer
  41  */
  42 interface BareHtmlPageRendererInterface {
  43
  44   /**
  45    * Renders a bare page.
  46    *
  47    * @param array $content
  48    *   The main content to render in the 'content' region.
  49    * @param string $title
  50    *   The title for this maintenance page.
  51    * @param string $page_theme_property
  52    *   The #theme property to set on #type 'page'.
  53    * @param array $page_additions
  54    *   Additional regions to add to the page. May also be used to pass the
  55    *   #show_messages property for #type 'page'.
  56    *
  57    * @return \Drupal\Core\Render\HtmlResponse
  58    *   The rendered HTML response, ready to be sent.
  59    */
  60   public function renderBarePage(array $content, $title, $page_theme_property, array $page_additions = []);
  61
  62 }