BareHtmlPageRendererInterface.php 2.08 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
<?php

namespace Drupal\Core\Render;

/**
 * Bare HTML page renderer.
 *
 * By "bare HTML page", we mean that the following hooks that allow for "normal"
 * pages are not invoked:
 * - hook_page_attachments()
 * - hook_page_attachments_alter()
 * - hook_page_top()
 * - hook_page_bottom()
 *
 * Examples of bare HTML pages are:
 * - install.php
 * - update.php
 * - authorize.php
 * - maintenance mode
 * - exception handlers
 *
 * i.e. use this when rendering HTML pages in limited environments. Otherwise,
23 24 25 26
 * use a @code _controller @endcode route, and return a render array.
 * This will cause a main content renderer
 * (\Drupal\Core\Render\MainContent\MainContentRendererInterface) to be
 * used, and in case of a HTML request that will be
27 28 29 30 31 32 33 34 35
 * \Drupal\Core\Render\MainContent\HtmlRenderer.
 *
 * In fact, this is not only *typically* used in a limited environment, it even
 * *must* be used in a limited environment: when using the bare HTML page
 * renderer, use as little state/additional services as possible, because the
 * same safeguards aren't present (precisely because this is intended to be used
 * in a limited environment).
 *
 * Currently, there are two types of bare pages available:
36 37 38
 * - Install (hook_preprocess_install_page(), install-page.html.twig).
 * - Maintenance (hook_preprocess_maintenance_page(),
 *   maintenance-page.html.twig).
39 40 41 42 43 44
 *
 * @see \Drupal\Core\Render\MainContent\HtmlRenderer
 */
interface BareHtmlPageRendererInterface {

  /**
45
   * Renders a bare page.
46
   *
47
   * @param array $content
48 49 50
   *   The main content to render in the 'content' region.
   * @param string $title
   *   The title for this maintenance page.
51 52
   * @param string $page_theme_property
   *   The #theme property to set on #type 'page'.
53 54 55 56
   * @param array $page_additions
   *   Additional regions to add to the page. May also be used to pass the
   *   #show_messages property for #type 'page'.
   *
57 58
   * @return \Drupal\Core\Render\HtmlResponse
   *   The rendered HTML response, ready to be sent.
59
   */
60
  public function renderBarePage(array $content, $title, $page_theme_property, array $page_additions = []);
61 62

}