Twig is a template engine for PHP, which is the language used in Drupal. Twig can be used to design templates in generic PHP applications as well as Drupal themes.
By default, individual forms in Drupal are not output using Twig template files. It's possible to associate a form with a Twig template file by creating a new theme hook, and then referencing that theme hook from the $form array that defines the form. Doing so allows theme developers to customize the layout of the elements in the form using HTML and CSS.
This is useful when you want to change the layout of the entire form. For example, putting the elements into 2 columns. If you want to change individual elements in the form, you can often do so by overriding element specific Twig template files.
In this tutorial, we'll:
- Learn how to create a new theme hook that can be used to theme an element in a render array.
- Associate the
$formwe want to theme with the new theme hook we created. - Create a Twig template file for the theme hook that will allow us to lay out the form elements using custom HTML.
By the end of this tutorial, you should be able to associate a Twig template file with any form in Drupal, so that you can customize its layout using HTML and CSS.
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
#themeproperty 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.
Learn Drupal
Guide
It's a Drupal best practice to always use Drupal's internationalization utilities for any user interface strings in your code. This includes the PHP t() function and StringTranslationTrait trait, the Twig t filter, and the JavaScript Drupal.t() function. This makes it possible for our module's interface to be localized.
In this tutorial, we'll:
- Edit the
WeatherPagecontroller and use thet()method from theStringTranslationTraittrait for all UI strings. - Update the weather-page.html.twig template file to use the Twig
tfilter. - Modify the JavaScript in our forecast.js code to use the
Drupal.t()function for UI strings.
By the end of this tutorial you should be able to update the PHP, Twig, and JavaScript code in your module to ensure that any user interface strings they output are translatable.
CSS in Drupal
TopicCascading Style Sheets (CSS) files are added as an asset library through a theme’s libraries configuration file. HTML attributes, including classes and IDs, are commonly added in template files with Twig.
Template files in Drupal modules provide the default HTML markup for the visual presentation of a module's data. Be aware that themes are likely to override the template with site-specific customizations. This template should contain only minimal markup to ensure functionality, and document the variables fed into the template.
In this tutorial, we'll:
- Explain the role of Twig template files in modules.
- Show how modules declare and use template files.
- Recognize how a render array can specify a template.
By the end of this tutorial, you should be able to articulate how and when a module should define a new template file.
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
WeatherPagecontroller 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.
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
Guide
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.
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
LayoutDefaultclass 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
Learn about resources to guide you through the process of updating a module or theme to the latest version of Drupal.
Modules enable developers to customize Drupal without modifying the core software. To ensure a stable and upgradeable core system, Drupal defines integration points and patterns that developers can use to customize the system. Modules contain code (PHP, JavaScript, Twig, CSS, YAML, etc.) that can extend, alter, and enhance Drupal's features and functionality.
In this tutorial, you'll learn:
- What Drupal modules are and their role in Drupal architecture
- How modules interact with Drupal core to extend or alter site functionality
- About the types of modules: core, contributed, and custom
By the end of this tutorial, you should be able to explain what modules are in Drupal, and understand their role in defining a Drupal site's functionality.