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
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
$form
we 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.
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.
Twig is the default template engine for Drupal. If you want to make changes to the markup that Drupal outputs you're going to need to know at least some Twig. In this tutorial, we will outline the role that Twig now plays in Drupal, how Twig impacts the theming experience, and where to find additional resources for learning Twig.
At the end of this lesson, you'll be able to:
- Describe the role that Twig plays in creating Drupal themes
- Explain how Twig impacts the theming experience in Drupal
- Locate additional resources for learning Twig
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.
When it's time to start a custom Drupal theme from scratch (especially if you're new to Drupal theming), we recommend using Starterkit. Starterkit helps you get a new theme up and running by scaffolding a set of theme files with sensible defaults, saving you from a bunch of repetitive work.
In this tutorial we'll:
- Learn what Starterkit is
- Discuss when you should--and should not--use Starterkit
- Walk through how to use Starterkit to generate a new Drupal theme
By the end of this tutorial you should be able to explain the use case for Starterkit and understand how to use it to start a new custom theme.
Template files are responsible for the HTML markup of every page generated by Drupal. Any file ending with the .html.twig extension is a template file. These files are composed of standard HTML markup as well as tokens used by the Twig template engine to represent dynamic content that will be substituted into the HTML markup when the template is used. As a theme developer, you'll work with this a lot.
In this tutorial we’re going to learn about:
- What template files are, and how they fit into the big picture of creating a theme
- How template files are used in order to allow theme developers to modify the HTML markup output by Drupal
- Naming conventions for, and specificity of, template files
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.
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.
Now that we understand what templates are and how we can use them, let's override some templates! In this tutorial we'll copy the views wrapper template to our theme and override it so that we can customize the markup for the Baseball Players view. Then we'll modify the template so that our view's pager appears both above and below our table of players.
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.
Themes define the regions that are available for site administrators to place blocks in, creating a layout framework within which the components that compose a page can be placed. As a theme developer you'll need to determine what regions are necessary to accommodate your design's layout, while also ensuring it'll work with the way Drupal uses blocks to place content onto the page. Deciding what regions to create requires knowledge of how Drupal works and a clear vision of the design you're trying to achieve.
In this tutorial we'll:
- Explain what regions are and how they relate to themes
- Describe how regions are handled internally within Drupal
- Demonstrate things to keep in mind when planning the regions for your custom theme
By the end of this tutorial you should be able to describe what a region is, explain how Drupal themes use regions to place content, and get started dissecting your own designs into regions.
Some, but not all, themes come with administrator-configurable settings that you can change through the UI. These might allow you to upload your own logo, choose between a couple of different pre-defined layouts, or turn features of a theme on or off. In this tutorial we’ll look at where you can find these theme settings if they exist, and how to go about changing them.
As we learned in the What Is a Breakpoints YAML file? tutorial, modules and themes can expose their site's CSS breakpoints and media queries to other Drupal modules and themes by implementing a breakpoints YAML file. In that tutorial, you also learned about the structure of a breakpoints configuration file and why you'd want to create one. In this tutorial, we’ll walk through the process of creating an example breakpoints file step-by-step.
By the end of this lesson, you should be able to create a working breakpoints YAML file in a theme or module. We'll test it out by enabling Drupal's Responsive Image module, where we'll be able to see it listed in the configuration form for creating a new responsive image style.
Drupal comes with all of its caching features enabled by default. This improves response time, but can be frustrating for themers as it makes it harder to preview the changes you make to template files.
In this tutorial we'll look at:
- Why these features are enabled by default
- How the theme layer leverages Drupal's caches
- Why you should learn to disable them when doing development
This tutorial demonstrates how to locate the template file that is currently being used to render an element and override it in your own theme. This is an important skill for anyone who wants to make changes to Drupal's default HTML markup.
In this tutorial we'll:
- Override the node.html.twig template in our theme
- Make changes to the markup
- Create a content-type-specific template override like node--CONTENT_TYPE.html.twig
By the end of this tutorial you should be able to modify the HTML markup used to display a node, or any other element of the page generated using a template file.
Customizing the available regions in your theme is one of the first things you'll do when creating your own themes. Doing so gives you complete control over where content is displayed on the page, and the markup involved. Adding regions to a theme is a two-step process that involves editing your theme's THEMENAME.info.yml file and updating your page.html.twig file.
In this tutorial we'll:
- Declare one or more new regions in our themes THEMENAME.info.yml file.
- Output the content of those regions in our theme via the page.html.twig file.
By the end of this tutorial you should be able to add or edit the regions a theme provides. Also, you'll ensure that blocks placed into regions are displayed by outputting the regions in the page template.
Themes and modules can alter the list of theme hook suggestions in order to add new ones, remove existing ones, or reorder the list. This powerful feature allows for the definition of custom logic in your application that can tell Drupal to use different templates based on your own unique needs. You might for example; use a different page template for authenticated users, or a custom block template for someone's birthday.
In this tutorial we'll cover:
- Adding new theme hook suggestions from a theme using
hook_theme_suggestions_HOOK_alter()
- Altering the list of theme hook suggestions
- Removing theme hook suggestions
- Reordering the list of theme hook suggestions
Info files, aka THEMENAME.info.yml files, provide Drupal with metadata about your theme, the features it supports, and the regions that it defines. All themes are required to have a THEMENAME.info.yml file, and creating one is generally the first step you'll take when creating a new theme.
In this tutorial we'll:
- Create a new .info.yml file and define a new theme
- Review the required key/value pairs of an .info.yml file
- Enable our new theme in the Drupal UI
By the end of this tutorial you'll be able start a new theme by creating the required *.info.yml file and better understand its contents.
JavaScript is used and loaded in special ways within a Drupal site. JavaScript is loaded via asset libraries and Drupal core provides a bunch of different JavaScript libraries that you can load and use in your module or theme. This tutorial provides a brief orientation to some of the JavaScript included in core.
In this tutorial we'll:
- Preview the JavaScript ecosystem in Drupal
- Find pointers to tutorials where you can learn more about adding JavaScript to a theme or module
- Learn about examples of JavaScript in Drupal core that are useful to review for learning purposes
By the end of this tutorial you should have a good overview of how JavaScript is used throughout Drupal core.