Knowing which plugin types exist and the use case for each is important when it comes to writing modules that extend Drupal's existing functionality. If you want to add additional functionality, you need to first know which plugin type provides that functionality.
In this tutorial, we'll list some of the more commonly-used plugin types and their use case, show where you can find a more complete list of plugin types provided by core, and provide several methods for discovering existing plugins in your Drupal codebase.
Drupal uses plugins for a lot of different scenarios. Blocks, field types, menu items, breakpoints, and migrations are all examples of plugins. There are a couple of different types of plugins. Before you can create a new plugin of any type, you'll need to figure out where the plugin implementation and its metadata should live in the code base, so that the plugin manager can find plugins, and examine what functionality instances of the plugin type are expected to provide.
In this tutorial we'll:
- Demonstrate how to figure out what type of plugin you're dealing with.
- Point to additional resources showing how to implement the specific plugin type once it has been determined.
By the end of this tutorial you should have a better understanding of how to figure out the details required to implement any given plugin type.
Plugin derivatives allow a single plugin to dynamically generate multiple plugin instances based on configuration or other data. This is useful for situations where user-entered data, or other dynamic configuration, might have an impact on available plugins. Or, put another way, any time you need to be able to dynamically generate plugin definitions.
In this tutorial we'll:
- Define what plugin derivatives are
- Understand the use case for derivatives
- Examine how core uses derivatives in order to demonstrate how you could write your own plugin deriver class
In order for a plugin manager to locate instances of individual plugins within the Drupal code base it needs to know where to look, and how to interpret the data that it finds. This process is called plugin discovery and can be accomplished in several ways.
In this tutorial, we'll look at what plugin discovery is doing at a high level, and then talk about the plugin discovery methods you can choose from when defining a new plugin type.
Learn how the Plugin API takes a given plugin ID and uses it to instantiate and return a fully configured plugin object. In this tutorial we'll look at:
- What factories are, and the role they serve in the Plugin API
- The factories available in core
- Using mappers to dynamically load a plugin when you don't know the ID of the specific plugin you need.
A plugin manager is responsible for both the definition of a new plugin type, and for listing and instantiating instances of plugins of the defined type.
In this tutorial we'll:
- Define what a plugin manager is.
- Create a list of all plugins of a specific type.
- Load and instantiate specific plugin instances, so we can use them in our code.
The term plugin type is used as a way to provide a generic name for all plugins managed by the same plugin manager. Example plugin types include block, field widget, and image effect. A plugin type doesn't consist of any code that provides specific functionality. Instead, it provides a way to refer to the system and it describes the central purpose of all plugins of that type.
In this tutorial, we'll cover what the term plugin type means and how it is used when talking about Drupal's plugin system. By the end of this tutorial, you'll understand what a plugin type is and be ready to learn how to define a plugin type in a module.
What Are Plugins?
FreeThe Drupal plugin system allows a particular module or subsystem to provide functionality in an extensible, object-oriented way. The controlling module defines the basic framework (interface) for the functionality, and other modules can create plugins (implementing the interface) with particular behaviors. Plugins are grouped into plugin types. Each plugin type is managed by a plugin manager service, which uses a plugin discovery method to discover provided plugins of that type and instantiate them using a plugin factory.
The system aims to make it easy for developers to allow for management of these components via the user interface, giving more flexibility and control to site administrators.
In this tutorial we'll take a high-level look at the problem the Plugin API is solving and provide a starting point for diving deeper into the various components that make up the Plugin API.
The #access
property can be used with any element in a render array, including form elements, to control the visibility of that element and its children. This is an effective way to limit access to specific parts of a page's content to only those users with the required permissions, and to show or hide material based on other conditional logic.
In this tutorial we'll:
- Review the
#access
Render API property - Demonstrate using the
#access
property to show/hide a field on a node depending on the current user's permissions
By the end of this tutorial you should be able to limit access to any element on the page via logic that returns a Boolean value.
We often need to add code to an alter hook or preprocess function that adds additional HTML attributes to items in a render array. Maybe you're developing a module that adds conditional classes to elements on the page under certain circumstances. Or perhaps your theme needs to add some data attributes to certain links, or form elements, in order to enable some custom JavaScript functionality.
Adding HTML attributes like class
, id
, or data-*
to render array elements involves:
- Adding the desired values to the element in a render array as an array of key/value pairs
- Converting the values in the render array to an
Attribute
object - Outputting the
Attribute
object inside a template file
In this tutorial, we'll cover all of these steps. By the end of this tutorial, you should be able to add new HTML attributes to elements in a render array and discover which property those values should be added to, depending on the element in question.
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.
Drupal makes it easy to convert an array of strings to an ordered or unordered HTML list using '#theme' => 'item_list'
elements in a render array. This is commonly done by module developers to display a list such as links to content, the values of settings in a module, or the names of everyone who has viewed a page. Displaying lists is a super common task for a content management system.
In this tutorial we'll look at:
- Outputting an array of items as an unordered
<ul>
list - Properties specific to
'#theme' => 'item_list'
in a render array
By the end of this tutorial you should be able to output unordered lists.
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.