The Drupal core Media Library module provides an enhanced user interface for locating Media entities and attaching them to an article. It's a drop-in replacement for the default entity reference widget which uses a not very intuitive autocomplete field. Using the Drupal core Media Library module requires minimal configuration.
If you want to provide content creators with a gallery-like library of Media entities that they can browse through in order to find the ones they want to add to their content, the Media Library is the easiest way to do it. It can be configured to work with both Media fields and the CKEditor powered WYSIWYG editor commonly used for editing the body field of Drupal nodes. There's really no reason not to use it.
In addition to providing a better UI for locating existing Media entities, the Media Library provides a way to create new Media entities right from the content creation form. This prevents an otherwise confusing requirement where Media entities need to be created, via a different set of forms, before they can be used.
In this tutorial we'll:
- Install and configure the Media Library module to work with Media fields
- Use the user interface provided by the Media Library to improve the experience of finding and selecting Media entities to associate with a piece of content
By the end of this tutorial you'll know how to replace the default entity reference widget used for selecting Media entities with the much improved Media Library UI.
Media entities, like any content entity, work great with all the different features Drupal provides for changing the way things are displayed: view modes, Layout Builder, theme templates, and more. We're big fans of using view modes to create a component-like design system where entity types have view modes representing the different context in which they're displayed. Then we theme the view modes. This works great for displaying Media entities associated with a page and for changing the way that Media assets are displayed within the Media Library browser.
In this tutorial we'll:
- Create Hero and Sidebar view modes for Media entities
- Configure the Image Media type to use the new view modes and style each one differently
- Use the new view modes to render Image Media assets within a Layout
- Update the Media library view mode that's used by the Media Library browser to display additional information alongside the thumbnails used when selecting Media to attach to a page
By the end of this tutorial you should be able to change the way that Media assets are displayed by using view modes and display formatters in a Drupal site.
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.
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.
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.
Set up a local development environment to practice Drupal theme development. In order to practice theme development, either on your own or following our Hands-On: Theming guide, you'll need a Drupal site up and running on your computer.
By the end of this tutorial, you should be able to:
- Install Drupal on your computer so you can modify files with a code editor of your choice.
- Generate dummy content so that you have different kinds of pages to theme.
It's time to create the bare-bones structure for a new theme on your site. You should try to complete this exercise based on the information you've learned in this chapter. The video included will walk you through the implementation of this exercise if you need some help. In this exercise you will need to:
- Create an info file that describes a custom theme to Drupal with the regions listed below (we're going to name ours "reboot").
- Enable, and view, a bare-bones custom theme.
Regions:
'Header' (header)
'Primary menu' (primary_menu)
'Secondary menu' (secondary_menu)
'Page top' (page_top)
'Page bottom' (page_bottom)
'Highlighted' (highlighted)
'Featured top' (featured_top)
'Breadcrumb' (breadcrumb)
'Content' (content)
'Sidebar first' (sidebar_first)
'Sidebar second' (sidebar_second)
'Footer first' (footer_first)
'Footer second' (footer_second)
Note: At the end of this exercise, you'll find a video walk-through of the solution.
You can accomplish a lot without needing to change any markup by adding CSS and JavaScript files to your theme. In this exercise you'll create 2 asset libraries and add them to your theme. Specifically, we want to pull in the CSS and JavaScript from the popular Bootstrap framework so that we can make use of its layout utility classes later on. We'll also add a custom CSS file that contains global styles for our site, like setting the page background color.
If you want to try and complete this on your own first you'll need to:
- Add the Bootstrap CSS and JavaScript files to your theme.
- Define an asset library using a THEMENAME.libraries.yml file in your theme.
- Tell Drupal to attach your asset library so that the CSS and JavaScript files it represents are included in the page.
Once that's done your site won't look all that different. But if you view the page source, or look closely, you should see that the Bootstrap files are included along with any CSS rules you placed into your custom style sheet.
Note: Since this course if focused on teaching the Drupal aspects of theme development, and not on writing CSS, we use the Bootstrap CSS. If you don't need it for your project though you can skip it, or add the CSS framework that you want to use instead.
You should try to complete the exercise steps on your own and use the video to help guide you if you get stuck.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
Drupal has a few handy settings you can tweak to make developing themes a little more intuitive and a lot more awesome. This includes disabling some of the caching that Drupal does so you don't need to clear the cache as frequently. We'll also turn off CSS and JS aggregation in a settings file (overriding anything set on the Performance configuration form) so you can see your changes to .js and .css files with just a page refresh. Finally, turning on the Twig debug service will give us some additional contextual information about the templates being used when we view the source code of any page on our site. Walk through the exercise steps, and if you get stuck you can watch the video to see how we implemented this.
If you want to try and complete this on your own you'll need to:
- Make changes to your site's settings.php file. Hint: check out the example.settings.local.php file included with core.
- Modify configuration via a services.yml file. Hint: check out the default.services.yml file included with core.
Once this is done, if you view the source of any page on your Drupal site you should see extra HTML comments with helpful information about which template file was used to generate a section of markup.
Example:
<!-- THEME DEBUG -->
<!-- THEME HOOK: 'node' -->
<!-- FILE NAME SUGGESTIONS:
* node--view--frontpage--page-1.html.twig
* node--view--frontpage.html.twig
* node--2--teaser.html.twig
* node--2.html.twig
* node--page--teaser.html.twig
* node--page.html.twig
* node--teaser.html.twig
x node.html.twig
-->
<!-- BEGIN OUTPUT from 'themes/icecream/templates/node.html.twig' -->
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In order to change Drupal's default markup you need to override template files. The page template controls the overall layout of your theme, including the placement of regions. You should complete the exercise just following the written instructions and you can use the video to help if you get stuck.
If you want to try and do this on your own first you'll need to:
- Override the currently used page.html.twig template file.
- Modify the content of the file to include the regions defined in the theme's .info.yml file.
- Wrap the regions in the page template file with HTML markup using CSS classes from Bootstrap to achieve the example layout below.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
The available dynamic tokens or variables vary from template to template. Each "page" is built from and uses many different templates. In this exercise, we'll continue our template overriding practice by overriding the node template. We'll override it and rename it in such a way that it will only affect article nodes on our Drupal site. We'll practice the process of overriding the template, inspecting the available variables, and customizing the markup. Along the way, we'll practice using the Twig filter without
. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the node.html.twig template file and target only Article nodes.
- Modify the template so that the content of the image field of a node is output wrapped in a
<div>
independent of the rest of the node's content.
Example:
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll continue our template overriding practice by overriding the main menu template. We'll override it and rename it with a file name suggestion so that it will only affect the main menu component of our Drupal site. We'll consult the Bootstrap documentation and add the classes from the base nav component into our overridden main menu template file. Along the way, we'll utilize a variety of methods for adding CSS classes to HTML selectors including using attributes.addClass()
and set
. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the menu.html.twig template file, using a file name suggestion to target only the main menu.
- Add CSS classes from the base nav component in Bootstrap.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll continue our template overriding practice by overriding the image field template. We'll consult the Bootstrap documentation and add a responsive image class that will apply to any images uploaded by a user to the field_image
field. Once again, we'll add this class to the classes
array in the set
Twig tag. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the image field template file.
- Add values to the
classes
array withset
.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll practice using the t
fiter in a Twig template. As a best practice, all hard-coded text in a template should be translatable. Simple text (containing no dynamic tokens) can be be passed through the t
filter to achieve this objective. Along the way, we'll also use a basic conditional if
statement with Twig. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Add a
<div class="label label-warning">
element to the article node template file that contains the string"This node is not published"
. - Use the
t
filter to make the hard-coded text translatable. - Use basic logic statements with Twig to check if the node is published or not.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
Preprocess functions allow you change existing variables, or add new variables, for a template file using PHP code. In this final exercise for the course, you'll define a PHP function that implements a preprocess hook and define a new variable using PHP and make it available for use within a specific template file. Specifically we want to create a new variable named {{ today }}
that contains the current date and gets passed to the page.html.twig template file. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
Learning objectives:
- Create a THEMENAME.theme file.
- Write a proprocess PHP function that adds variables to a page template file.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
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.
The Layout Builder Styles module extends the Drupal core Layout Builder UI to add the ability for editors to apply custom CSS classes to the blocks and sections that make up a layout. This gives layout editors more control over the look and feel of elements within a layout. It's especially useful when using Drupal's Layout Builder in conjunction with a design system like Bootstrap, Material UI, or your own predefined utility classes.
The module allows site builders to define new styles. Then, when placing a block into a layout, if there are any styles available for the block type, the user is presented with a select list where they can choose one or more to apply. When a style is applied, any CSS classes associated with the style are added to the markup. Also, a new style-specific theme hook suggestion is added to the block to allow for further customization.
In this tutorial we'll:
- Install and configure the Drupal Layout Builder Styles module
- Learn how to define new styles
- Learn how anyone editing a layout can apply the styles we defined to a block or section in the layout to change the UX
By the end of this tutorial, you should be able to use the Layout Builder Styles module to allow editors to add predefined styles to existing layouts and blocks without writing any code.
Access control for the Media entities in Drupal works in much the same way as any other content entity. The module provides fine-grained control over create, update, and delete operations, while providing only basic control over who can view Media assets. The thinking is that there are too many possible permutations of how an application may want to restrict read access to content. Therefore, rather than try and pick one setting and add it to core, it's left entirely up to the site administrator and contributed modules.
In this tutorial we'll:
- Look at the different permissions provided by the Media module for controlling access to Media entity operations
- Discuss some common misconceptions about file permissions that can lead to potentially exposing private data
By the end of this tutorial you should know how to configure access control for Media entities, and explain how access control relates to files attached to a Media entity attached to a Node.
Drupal media entities are fieldable entities, which means that you can add any custom fields you want to your Media types. These fields can be used for collecting additional metadata about a resource, categorizing and organizing resources so they're easier to find in a large media library, or for displaying information like a photo credit or transcript for a video. The possibilities are endless once you know how to add, and optionally display, fields in Drupal.
Some example use cases for adding fields to Media types:
- Collect, and display, a credit to go along with a photo. This could also be a date, a location, or any other metadata.
- Store resource width and height dimensions as custom fields so they can be referenced by display logic in the theme layer.
- Use Taxonomy reference fields to add tags or categories to help keep a large library organized.
In this tutorial we'll:
- Learn how to add fields to a Media type
- Verify our new custom field is working
By the end of this tutorial you'll know how to add custom fields to any Media type.