The Render API is capable of detecting poorly-cacheable (highly dynamic) parts of a page and rendering them later using a process called auto-placeholdering. This works by using #lazy_builder
callbacks to lazy load certain very dynamic subtrees of a render array. The place in the array where that very dynamic content would appear is first assigned a placeholder. At the very last moment it is replaced with the actual content.
This allows Drupal to do things like cache the overall page in the Dynamic Page Cache despite parts of the page being too dynamic to be worth caching. It also allows the Render API to assemble a page using cache fragments combined with non-cacheable elements.
In this tutorial we'll:
- Discuss what lazy builders are and how they work in conjunction with placeholders to speed up the rendering pipeline
- Cover some common gotchas for lazy builders
- Look at some example code that implements a lazy builder callback
By the end of this tutorial, you should know how and when to use the #lazy_builder
property of a render array and how Drupal uses placeholders to increase the cacheability of content and speed up the rendering process.
Linking to things is probably one of the first things you learned how to do as a web developer. Anchor tags are the framework of how the world wide web works. So it's important to know how to create them in Drupal. Chances are you'll be doing a lot of it.
Creating links to things in Drupal, however, is a bit more complicated than just typing out an HTML anchor tag. It requires understanding how URLs are generated from routes, and how to define links as renderable arrays. It can also be tricky because of the multitude of deprecated, but still functioning, ways of creating links.
In this tutorial we'll:
- Use the
\Drupal\Core\Url
class to generate URL objects from routes and external URIs. - Use the
\Drupal\Core\Link
class to create HTML links within a Drupal module. - Examine best practices for working with URLs and links in a Drupal module in order to ensure that your code continues to work into the future.
By the end of this tutorial you should be able to link to anything, either internal to your application or external, using Drupal best practices.
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.
Strings of simple HTML and plain text can be defined in a render array using the #markup
and #plain_text
element types. In this tutorial we'll look at:
- Adding simple strings to a render array so they appear as HTML on the page
- When to use
#markup
and#plain_text
in your code
By the end of this tutorial, you should be able to add simple strings of HTML and plain text to a render array.
#prefix
and #suffix
are two commonly used examples of standard properties. That is, they are available for use on any element in a render array regardless of the element #type
or #theme
property's value. They are a great way to add additional layout markup to an element in a theme-agnostic way.
In this tutorial we'll:
- Use the
#prefix
and#suffix
Render API properties to wrap an element - Look at some possible use cases for using
#prefix
and#suffix
in your own code
By the end of this tutorial you should know how, and when, to use the #prefix
and #suffix
properties in a render array.
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.
Render API Overview
FreeThe 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.
The individual items that make up the content of a page impact the cacheability of that page. In order for Drupal's cache and external caches to better understand how the content varies on a page, module developers use the #cache
render element property. The #cache
property defines cacheability metadata for individual elements in a render array.
Additionally, these Render API elements can become fairly complex. The calculation of what the final HTML output should look like often involves looking up content in the database, checking multiple conditions, maybe querying an external API, and various other tasks. This can cause turning a render array into HTML to become quite expensive. In order to speed up this process, the Render API will cache the generated HTML for each element and reuse it on future requests whenever possible -- but only if you tell it to do so.
In this tutorial, we'll look at:
- How render caching impacts the performance of a page
- Defining the cacheability of an item with cache tags, cache contexts, and cache max-age
- Examples of using the
#cache
property in a render array
By the end of this tutorial you should know how, and when, to use the #cache
property when defining render arrays.
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.
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.
The #table
render element type is a powerful way to output an array of rows and columns as an HTML table. It supports all the features of a standard HTML <table>
element like headers, captions, and column groups. Data to be displayed in the table can be an array of simple string values, or an array of render arrays where each sub element is a row with columns as child elements. In addition, when used in the context of a form, tables can be made into a multiple select widget, or have drag-and-drop reordering of rows enabled. Whether you just want to display a set of tabular data, or you provide your users with a complex form element for reordering and nesting items inside a menu tree, it can all be done with the #table
element.
In this tutorial we'll:
- Look at outputting simple strings as a table
- Provide definitions for all the various properties that can be used to define a table element
- Demonstrate how to use the
#tableselect
and#tabledrag
options to create complex form widgets
By the end of this tutorial you should be able to create HTML tables in all their various permutations as part of a render array.
In this tutorial we'll look at how you can use the #theme
property of a render array to define custom HTML. With this information, module developers can use render arrays to define content, and theme developers can understand how elements in a render array are converted to HTML and which templates they can override to change the output for a specific element.
Learn how to:
- Use
hook_theme()
to define a new theme hook and define default values for variables - Create a corresponding Twig template file that outputs the variables and any custom HTML markup
- Use a preprocess function to add additional variables for the Twig template file you created
- Use the new theme hook in conjunction with a
#theme
property in a render array to link your Twig template file to actual content
By the end of this tutorial you should know how to define new templates to output content as HTML. You should also have a better understanding of how Twig template files are linked to elements in a render array.
There are a bunch of existing render elements, most commonly Form API elements. You need to know how to discover and make use of existing elements. In this tutorial, we'll learn how to:
- Locate a list of elements provided by Drupal core
- Figure out what properties apply to each element
- Use any render element type when defining content or forms in our code
By the end of this tutorial you should know what render element types are available for you to use, and how to find the details you'll need in order to implement them in your own render arrays.
It's best practice to access any of the services provided by Drupal via the service container to ensure the decoupled nature of these systems is respected. In order to do so, you need to know what services exists, and then, where possible, use dependency injection to use them in your code.
This tutorial walks through the process of:
- Discovering existing services and learn their machine name
- Using the machine name of service to request a copy from the service container
Drupal's Entity system provides several hooks that allow custom code to interact with various parts of the entity life cycle.
In this tutorial we'll:
- Examine the available hooks
- Learn how to make use of them to act on several different types of operations on individual entities
By the end if this tutorial you should have a better understanding of the hooks available to developers who want to respond to entity lifecycle operations and how to use them to customize the way specific entity types work.
On occasion you may need to modify the behavior of entity types defined by another module. Thankfully Drupal includes several alter hooks that can be used to override the behavior of another entity.
In this tutorial we will:
- Walk through the common Entity API hooks
- Look at example implementations of each
- And discuss the use cases for each
By the end of this tutorial you will have a better understanding of how to override the default behavior of an entity type provided by Drupal core (or another contributed module) within your custom code.
The Typed Data API in Drupal helps add additional functionality to PHP's built-in data types that make working with data in Drupal much more predictable. It allows code to make intelligent guesses about the type of data that a field on an entity contains. For example differentiating between a string of text, and a string of text that represents a URL.
In this tutorial we'll:
- Look at the 3 main types of typed data in Drupal: primitives, complex data, and lists.
- See how different data types and definitions are defined and show how to define your own data type.
- Look at the interfaces provided by each data type to see some of the benefits to adding this abstraction layer.
By the end of this tutorial you should have a better understanding of what the Typed Data API is, where you'll most likely encounter it, and how to use it in your code.
Entity CRUD (Create, Read, Update, and Delete) operations are handled via the EntityTypeManager
service.
In this tutorial we'll:
- Learn how to use the
EntityTypeManager
service to perform basic CRUD operations with examples you can copy/paste - Access both property and field values of an entity
- Update entities by setting new field values and then saving the object
By the end of this tutorial, you'll be able to understand Entity CRUD operations and be well on your way to becoming comfortable with accessing and manipulating entity values in code.
Field formatters are responsible for taking the data stored by a field and transforming it into what a vistor sees. We can define new field formatters to output data for new field types or to provide alternative formatting options for existing field types. Creating a field formatter plugin is a common task for Drupal developers.
In this tutorial we'll:
- Define a new background color field formatter that uses the string stored by our field_example_rgb field type as the background color of the output.
- Make it possible for site builders to toggle on or off a feature that automatically adjusts the foreground text color of the output.
By the end of this tutorial you should be able to define a new custom field formatter plugin with settings that a site administrator can configure.