Template files are used by modules when they need to add custom HTML to the content they output. The most common example is wrapping your output in one or more <div>
tags to give it additional structure and context. Using custom template files in a Drupal module requires defining a new theme hook, creating the template file, an associating the appropriate data with the template file via a render array.
In this tutorial, we'll:
- Learn how to add a custom Twig template file to a module.
- Update the
WeatherPage
controller to use the new template file.
By the end of this tutorial you should be able to create and use custom template files in a module.
Like most output in Drupal, Views relies on Twig templates for a significant amount of its rendering. In this tutorial we'll identify where you can find the default Views templates within your file system, what the common templates are for, and how to name your templates so that they are applied to specific views.
By the end of this tutorial, you should be able to:
- Identify where to find default views templates
- Understand which templates apply to what part of a view
- Get a sense of the template suggestions and how to use them to limit where your custom templates are applied
- Identify a view's machine name
- Identify a display's machine name
- Identify a field's machine name
If you want to make changes to the HTML markup of any element on the page you need to first figure out the theme hook or base name of the template file used to generate it. This information is required to override the template in your custom theme.
There are other situations in which knowing the theme hook name of a template file is useful. Including determining which preprocess function affects a template, and which template theme hook suggestions can be used.
In this tutorial we'll learn:
- How to figure out the theme hook name for any template
By the end of this tutorial you should be able to use the output from Twig's debugging mode to determine the theme hook name of any template file.
In order to ensure that all user interface strings in your application can be translated using Drupal's localization system, any text you add to templates needs to use either the t
filter or the {% trans %}
tag. Anyone creating themes or editing template files associated with a theme or a module should know how to use these two utilities.
In this tutorial we'll look at:
- How to use the
t
filter and{% trans %}
tag in a Twig template - The differences between the two, and how to determine which one to use
- How to translate strings assigned to variables in preprocess functions using the PHP
t()
function
In Drupal, whenever we output markup it's best practice to use a Twig template or a theme function. But whenever you need to output DOM elements within JavaScript the best practice is to use the Drupal.theme
function. This function ensures that the output can be overridden just like the HTML output by Twig. This tutorial covers how to use the Drupal.theme
function in your JavaScript when inserting DOM elements, as well as how to replace the markup output by other JavaScript code that is using the Drupal.theme
function.
We recommend planning ahead when using Layout Builder, documenting how you intend to use Layout Builder for your specific use-case, and then doing your best to stick to it. One approach that we've found works well for sites that need a maximum amount of flexibility (and have the resources to do the upfront planning and theming required) is using entity view modes.
This approach is similar in concept to component based design systems, where you do the initial work of creating a set of components that all work well together up-front, and then allow them to be mixed and matched in whatever way is necessary.
In this tutorial we'll:
- Create new view modes for the Basic Page content type representing the different components.
- Use the ctools blocks module to allow displaying an entity as a block and choosing which view mode to use when rendering the entity.
- Provide custom HTML and CSS styling for the new components.
By the end of this tutorial you'll know how to use Layout Builder in combination with entity view modes.
Layout Builder module comes with some common layouts that can be used out of the box. The Drupal community has created modules that provide more layout options. However, perhaps your project requires special layouts that cannot be constructed with already existing options. Or you require more precise control over the CSS classes and HTML markup, especially if your website is based on a third-party front-end framework. In these cases you can define custom layouts in a module or theme and make them discoverable by the Layout Builder.
In this tutorial we'll:
- Define a new layout plugin
- Create a corresponding Twig template file for HTML markup
- Use our new layout in the Layout Builder UI
By the end of this tutorial you should know how to define a new layout in code, within a module or a theme.
When defining new layout plugins for Drupal you can add custom CSS and JavaScript via asset libraries. This allows for the creation of layouts with complex structures and interactive elements. Those elements might include grids, tabs, and accordions. Drupal allows you to attach custom CSS and JavaScript directly to a layout plugin, or via the layout's Twig template file.
In this tutorial we'll:
- Define a custom asset library with JavaScript and CSS functionality
- Attach the asset library to the custom layout plugin
- Transform a multicolumn layout into tabs
By the end of this tutorial you should know how to attach custom CSS and JavaScript to a layout plugin to add interactivity and styling.
Develop Forms in Drupal
GuideThe 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.
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 to 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.
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
What Is a Theme?
FreeThemes are the part of Drupal that you, and anyone else visiting your Drupal powered application, see when they view any page in their browser. You can think of a theme as a layer, kind of like a screen, that exists between your Drupal content and the users of your site. Whenever a page is requested Drupal does the work of assembling the content to display into structured data which is then handed off to the presentation layer to determine how to visually represent the data provided.
Drupal themes are created by front-end developer. Frequently referred to as themers, or theme developers. Themes consist of standard web assets like CSS, JavaScript, and images, combined with Drupal-specific templates for generating HTML markup, and YAML files for telling Drupal about the file and features that make up each individual theme.
In this tutorial we'll:
- Explain what a Drupal theme is.
- Explain the role of a Drupal themer in the process of building a Drupal site.
- Get a high level overview of the types of files/code that themes are made of.
By the end of this tutorial you should be able to explain what a Drupal theme is, and the kind of work a Drupal theme developer will be expected to do.
Learn about resources to guide you through the process of updating a module or theme to the latest version of Drupal.
Themes provide the HTML, CSS, JavaScript, and other assets that are responsible for the look and feel of your site.