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.
Field API Overview
FreeIf you've ever created or edited a piece of content on a Drupal site you have already interacted with the Field API. The Field module (along with its user interface counterpart) is responsible for providing the forms and data components used to build up the content model that make up a Drupal site. Understanding how Drupal fields work and how they're constructed via the Field API is an important part of understanding how Drupal works.
In this tutorial, we're going to look at the main components that make up the Field API at a high level. We'll see how the Field UI module exposes the field types included in core. We'll also look at the three main pieces that compose fields: types, widgets and formatters.
Drupal's Field API specifies the implementation details for field types, widgets and formatters. It also provides several hooks that allow custom code to alter these implementation details. In this tutorial we'll take a look at these Field API hooks and see how they can be used to change field types, widgets and formatters.
By the end of this lesson, you should be able to:
- Idenfity existing Field API hooks for manipulating field behavior
- Understand the proper method for changing the behavior of a field type, widget or formatter
- Know where to find the documentation for these API functions, and how to find their implementations
Of the 3 main components of the field system -- types, widgets and formatters -- only 1 has an impact on the actual display of content for end users: field formatters. Field formatters are responsible for taking the data stored by a field and transforming it into the markup that is sent to the browser when an end user views your site.
In this tutorial we'll:
- Look at the role field formatters play in the Field API
- Identify the main components that make up a field formatter
By the end of this tutorial you should be able to define the role of a field formatter plugin.
Drupal's field system provides us with a flexible system of adding different types of discrete data to content types. This enables us to create rich content models. The Field API allows us to define these distinct field types by creating a new plugin. These plugins specify a FieldType
annotation. In this tutorial, we'll look at these annotations in detail. We'll look at the implementations of field types from Drupal core. Also, we'll see what a new custom field type would look like.
By the end of this tutorial, you should be able to:
- Understand how field type definitions are created and exposed to Drupal
- Identify the various field types provided by Drupal core
- Understand the requirements for providing a specification for a new field type
Once we've explored the various field types provided by Drupal core, the next component of the Field API to explore is field widgets. Field widgets define how the data structure of the field is displayed on an edit form. When content editors interact with your field type they will be doing so via the field widget you provide. In this tutorial, we'll take a look at the field widgets provided by Drupal core, the plugin type required to define our own custom widget and how we can define multiple widget options for a single field type.
By the end of this tutorial, you should be able to:
- Understand where field widgets fit into the overall Field API
- Implement a custom field widget to support a particular field type
In their simplest form layout plugins in Drupal Layout Builder define the part of the content output that can't be changed. For example a three column layout will consist of three equal columns every time an editor decides to use it as the layout section. The editor can place whatever they want into the three columns. But they can not change the overall layout. This restricts editorial capabilities of using layout plugins since in real life a three column layout may need to consist of a wider middle column and narrower side columns, allow for column headings, or other customizations.
This flexibility is accomplished by creating, and exposing, configuration options for layout plugins in Drupal's Layout Builder. In more advanced cases, the we can take this flexibility further by exposing an interface editors to dynamically define layout plugins.
In this tutorial we'll:
- Learn how to use custom PHP classes in the layout plugin annotation
- Learn what annotations properties can be used for custom layout declaration
- Define the concept of derivatives and outline scenarios for using them
- How to declare static single layouts using YAML format
By the end of this tutorial you'll learn advanced ways of declaring configurable custom layout plugins.
Layout plugins can be dynamically generated based on configuration using plugin derivatives. This allows developers to provide Drupal site administrators with a UI for creating new layout plugins, or to automatically register layout plugins based on the environment.
This is useful in situations where it's not enough to define a set of pre-configured layouts to use in the Layout Builder. Instead, you need to empower editors to declare their own new layout plugins without writing any code. Derivatives could also be used in scenarios where the layouts that should be made available depend on configuration set elsewhere in the module. Or, you might have a scenario where you want to have multiple different 2-column layouts, and for those layouts to have different names, so that they can be themed differently depending on which one is used.
In this tutorial we'll:
- Create a user interface that allows editors to dynamically define layouts via configuration.
- Learn how to set up a plugin deriver that creates layout plugins based on configuration.
- Create custom dynamic layout plugins with variable numbers of columns.
By the end of this tutorial you'll know how to declare dynamic custom layout plugins using derivatives.
When building a site using Drupal's Layout Builder, it's a good idea to keep the number of layout plugins manageable. In many cases it's better to create a single layout plugin that can be re-used rather than duplicate a layout multiple times to accommodate minor variations. One way to do this is provide editors with configuration options that will change the output when a layout is used.
For example, imagine you need to provide variations of a 3-column layout where the columns are different widths. You could define a new layout for each variation. Or you could define a single layout with a configuration option that allows a user to choose the column widths. The latter approach reduces code duplication, and makes the codebase easier to maintain.
In this tutorial we'll:
- Learn how to declare advance layout plugins with configurable settings in the Drupal Layout Builder
- Extend the
LayoutDefault
class and create a custom settings form that editors will see when using a layout - Use the provided configuration values in the layout's Twig template file to modify the layout when it is rendered
By the end of this tutorial you should be able to expose layout-related settings to editors, allowing for more flexibility in custom layout plugins.
Drupal site administrators can create new media entity types, with their own unique configurations and sets of associated fields. Different media types can be configured with different field names, permissions, moderation workflows, and display settings, making it possible to create truly custom content administration experiences. The process is similar to creating a node content type like articles or events with one major distinction: every media type inherits from a specific media source plugin. The source plugin provides domain-specific knowledge about the kind of resource being represented. For example, the Remote video source plugin used with the default Remote video media type knows how to consume and display videos from YouTube and Vimeo given only their URL.
Drupal core comes with a couple of common media source plugins, and contributed modules and custom code can add to this list, increasing the different media providers with which Drupal can integrate.
In this tutorial we'll learn how to:
- Install a contributed module that provides a new media source plugin.
- Create a new media type.
By the end of this tutorial you should be able to explain how source plugins relate to media types, and create a new media type.
The Drupal Media Library and Media ecosystem can be integrated with any third-party media provider by defining new media source plugins. Media types (Media entity bundles) have an important distinction compared to other content entity types like nodes. Every media type inherits from a specific media source plugin. The source plugin provides domain-specific knowledge about the kind of resource being represented. For example, media types dealing with images know how to validate file extensions and render <img>
tags. Media types dealing with remotely hosted videos might know how to retrieve thumbnails from a remote API, and display an HTML video player and transcript.
In this tutorial we'll learn how to:
- Define a new source plugin
- Integrate a third-party API via its existing PHP library
By the end of this tutorial you should be able to create a new source plugin that exposes any third-party media resources you want to integrate with Drupal.