Render API Concepts in Drupal

The Render API consists of two parts: structured arrays that provide data and hints about how that data should be rendered, and a rendering pipeline that can be used to render these arrays into various output formats. Understanding at least the basics of how the Render API works, the difference between elements and properties, and the concept of callback functions is an integral part of learning Drupal.

In this tutorial we'll:

• Look at the fundamentals of the Drupal Render API
• Point to additional material to provide more detail about the inner workings of the Render API and how content is output in Drupal

The core structure of Drupal's Render API is the render array, which is a hierarchical associative array containing data to be rendered and properties describing how the data should be rendered. As a module developer you'll use render arrays to describe the content your module controls in order to output it on a page as HTML, or as part of a response in another format like JSON. As a theme developer, you'll manipulate render arrays in order to affect the way content is output on the page.

In this tutorial we'll learn:

• What render arrays are and why they exist
• The basic format of a render array
• What "properties" and "elements" signify in the context of a render array
• Where to find more information about how to create a render array to describe your own content

By the end of this tutorial you should be able to understand when you need to use a render array, recognize one when you see it, and know where to get more detailed information about render array formatting specifics.

One of the central components of Drupal's Render API is render elements. You can think of them as prepackaged render arrays or shortcuts you can use to describe common things, like tables, links, and form elements, in a consistent way. In this tutorial we'll take a more in-depth look at the use of the #type property in render arrays in order to answer questions like:

• What are render elements, and what is their use case?
• Where can I find more information about available element types?

By the end of this tutorial you should be able to identify individual render element types within a larger render array, find the relevant documentation for specific types of render elements, and explain the use case for render elements.

Modules can provide new render element types -- a powerful way to encapsulate complex logic into a reusable component. This can help to cut down on code repetition, and allow other module developers to build on your work. In this tutorial we'll:

• Define a recipe for creating a new render element type
• Look at the code for the marquee element type from the render_example module in the Examples for Developers project.

By the end of this tutorial you should be able to implement a new render element type in your own module and make use of it when defining content as part of a render array.

This tutorial looks at the steps that Drupal goes through to obtain a render array for an incoming HTTP request, transform the render array into HTML, and then return it to your browser. We provide an outline of the process and links to resources for more in-depth information. We also take a more thorough look at the HtmlRenderer which converts a render array into HTML. Knowing how the render arrays you write in your code are ultimately used can help you optimize Drupal's Render API to describe your module's content.

Renderers are the services that take a render array and convert it to HTML (or JSON, or any other format). As a module developer, understanding how they work will help you gain a better understanding of what happens behind the scenes when Drupal links an incoming request to your custom controller and then handles the data you return.

In this tutorial we'll:

• Define renderers
• List the renderers available in Drupal core
• Demonstrate how you can create a link that forces the use of a different renderer

By the end of this tutorial, you should understand the role that renderers play in the Drupal render pipeline and when you might want to use one other than the default.

Some Render API properties, like #pre_render, #element_validate, and #lazy_builder are considered callable. Rather than receiving a static value, they contain a pointer to code that should be called at a specific time during the process of rendering a render element. Callbacks are used in some cases to return a value that can be substituted into the render array, and in other cases given the opportunity to manipulate the current element in the array directly.

In this tutorial, we'll:

• Look at what callbacks are
• List some common callback properties
• Show various ways that callback code can be defined
• Discuss how to choose which method to use

By the end of this tutorial, you should be able to define an appropriate value for any Render API property that expects a callback, and define the logic that is executed when the callback is triggered.