Example: Render API

The Render API consists of two parts: one, structured arrays that provide data, and hints about how that data should be rendered, and two, a rendering pipeline that can be used to render these arrays into various output formats. This example module looks at how to define content using render arrays, as well as how to use alter hooks to manipulate render arrays created by other modules.

For more on the rendering pipeline see The Drupal 8 Render Pipeline.

In order to ensure that a theme can completely customize the markup output by Drupal, module developers should avoid directly writing HTML markup for pages, blocks, and other user-visible output in their modules, and should instead return structured "render arrays". Checkout the example code in \Drupal\render_example\Controller\RenderExampleController::arrays() for an explanation of how to define new renderable arrays. The output from that code can be viewed at examples/render_example/arrays.

One of the primary benefits of using arrays to define content instead of strings of HTML is that arrays are easier to manipulate. There are dozens of hooks, and other ways to gain access to and manipulate existing render arrays during the rendering process both from within a module, and via a theme. As a rule of thumb the process of rendering an array into HTML is delayed for as long as possible. In most cases it's not until the variable containing the content to be rendered is printed out in a Twig template file that it is finally rendered.

For examples of altering render arrays checkout the code in render_example_preprocess_page() and render_example_preprocess_block(). There is a form at examples/render_example/altering that can be used to turn these features on and off if you would like to see the results of the array altering code on your site.

This module contains code that can display the render array used to build each page, and/or block, as you navigate through a site as a way to show some examples of real render arrays being used. This functionality requires that the Devel module be installed in order to work.

Modules can also provide new render element types. A powerful way to encapsulate complex display logic into a reusable widget. This can help to cut down on code repetition, and allow other module developers to build off of your work. See an example of a new render element definition by looking at \Drupal\render_example\Element\Marquee.

Forms are generated using a superset of the Render API. You can see examples of how the Render API is used when creating forms in the fapi_example module.

See also

Render API overview

\Drupal\Core\Render\RendererInterface::render()

\Drupal\Core\Template\TwigExtension::renderVar()

Parent topics

File

modules/render_example/render_example.module, line 8

Functions

Classes

Files