4.4-essential-apis-render.md

Render API

Make sure you understand the Routing System before continuing.

From Render API:

Drupal 8's Render API roughly consists of two parts:

1. The render pipeline — which is format-agnostic (HTML, JSON, anything)
2. Render arrays, which are a representation of a HTML page. They allow nesting (like HTML) and altering (necessary for Drupal's flexibility)

Render Pipeline

For easier viewing, download the Render Pipeline diagram below:

• PDF: https://www.drupal.org/files/d8_render_pipeline_0.pdf
• PNG: https://www.drupal.org/files/d8_render_pipeline_1.png
• SVG: https://www.drupal.org/files/d8_render_pipeline.svg__0.txt

1. If a route controller returns a Response object, the response is sent back to the browser and the remaining steps are bypassed. Otherwise, the VIEW event is triggered.
2. MainContentViewSubscriber subscribes to the VIEW event. Upon event fire, it checks to see if the controller result is a render array. If not the request dies, otherwise it guarantees to generate a Response.
3. MainContentViewSubscriber checks to see if a main content renderer service exists for the requested format. If not, a 406 Not Acceptable response is generated and the remaining steps are bypassed.
4. Otherwise, a response is generated by calling MainContentRendererInterface::renderResponse() on the service.

Main Content Renderers

Drupal 8 comes with the following main content renderers:

• HTML: HtmlRenderer (text/html)
• AJAX: AjaxRenderer (application/vnd.drupal-ajax)
• Dialog: DialogRenderer (application/vnd.drupal-dialog)
• Modal: ModalRenderer (application/vnd.drupal-modal)

Render arrays

From Render arrays:

"Render Arrays" or "Renderable Arrays" are the building blocks of a Drupal page. A render array is an associative array which conforms to the standards and data structures used in Drupal's Render API. The Render API is also integrated with the Theme API.

In many cases, the data used to build a page (and all parts of it) is kept as structured arrays until the final stage of generating a response. This provides enormous flexibility in extending, slightly altering or completely overriding parts of the page.

Example Render Array:

<?php
$page = [
  '#type' => 'page',
  'content' => [
    'system_main' => [
      // ...
    ],
    'another_block' => [
      // ...
    ],
    '#sorted' => TRUE,
  ],
  'sidebar_first' => [
    // ...
  ],
];
?>

Render Array Properties

• #type - Element type
• #cache - Mark the array as cacheable
• #markup - Provides HTML markup directly, which is passed through \Drupal\Component\Utility\Xss::filterAdmin()
• #plain_text - Provides text needing escaping (has precedence over #markup)
• #prefix - String prepended to the element being rendered
• #suffix - String appended to the element being rendered
• #pre_render - Functions that may alter render array before being rendered
• #post_render - Functions that operate on rendered HTML
• #theme - Single function that will be responsible for rendering the element
• #theme_wrappers - Array of theme hooks that add to the rendering after children have been rendered and placed into #children.

Additional Resources

• drupal.org: Render API

---

<< Previous Page | Next Page >>