You may know that Drupal provides utility PHP functions for manipulating and sanitizing strings. Drupal also provides JavaScript functions for the same purpose. The two most useful are Drupal.checkPlain
and Drupal.formatPlural
. Drupal.checkPlain
lets you ensure a string is safe for output into the DOM; it is useful when working with user-provided input. Drupal.formatPlural
ensures that a string containing a count of items is pluralized correctly. This tutorial will show you where you can find documentation for and example use-cases of both.
Each theme is a collection of files that define a presentation layer for Drupal. While only a THEMENAME.info.yml file is required, most themes will contain other files as well. Some are Drupal-specific, and need to follow a strict naming convention and be placed in the appropriate place for Drupal to find them. Others are standard front-end web assets like CSS, JavaScript, and image files that can be placed anywhere within the theme's code.
In this tutorial we'll learn about:
- The various types of files you can expect to find in a theme directory
- Where in the Drupal code base your theme directory should live
- Keeping the directory and all the files within organized
By the end of this tutorial you should be able to explain where a Drupal theme should be placed in a project's code base, and the types of files one can expect to find in a theme.
Custom themes in Drupal must be configured to inherit settings, templates, and other assets from a parent theme. Which base theme you use is configurable. This allows theme developers to use a different set of markup as the starting point for their theme, organize various theme assets into a more maintainable structure, and more. All of this is made possible because of how Drupal's theme layer uses a chain of inheritance when assembling all the parts of a theme.
Base themes are also a powerful way to encapsulate standards and best practices into a reusable code base. You'll find dozens of contributed base themes on Drupal.org that can serve as a great starting point, especially if you're planning to work with an existing design framework like Bootstrap or Susy Grids. Or if you want to leverage modern JavaScript bundling without setting up Webpack on your own.
In this tutorial we'll:
- Learn what base themes and subthemes are
- Look at a few examples of template inheritance and how that works
- Discuss some use cases for theme inheritance
By the end of this tutorial you'll know how to declare the base theme that your theme builds upon.
One important aspect of theme administration is the configuration of global and theme-specific settings. In this tutorial, you will learn where theme settings are configured in Drupal's administrative interface, the difference between global and theme-specific settings, and what each global setting refers to on a base installation of Drupal with a custom theme installed.
Sometimes your JavaScript needs to insert new strings into the user interface. In order to ensure that those user-facing strings can be translated into other languages, just like the rest of Drupal's user interface, you should make sure and use the Drupal.t
function anytime you output a string of text.
If you want to create a link to an internal page in a Twig template--and there's not already a variable in the template that contains the URL you want to link to--you'll need to determine the route of the thing you want to link to and then use the Twig url()
or path()
functions to generate appropriate URLs. In most cases when you want to create a link to an entity that is being output by the current template there's an existing helper variable to use. For example, in a node.html.twig template file there's a url
variable that points to the current node. For other scenarios, like hard-coding a link to the /about page, you'll need to do a little more work.
In this tutorial, we'll:
- Get the absolute URL value
- Get the relative path value
- Generate HTML for a link
- Get the URI to a file, like an image in the Media library
- Get the active theme path
By the end of this tutorial you should be able to create links to any internal page via Twig.
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
In Twig, you can modify variables using functions or filters. Twig has a bunch of built-in functions and filters. Drupal extends Twig to provide a few handy Drupal-specific functions and filters as well.
In this tutorial, we'll look at:
- What are functions and filters?
- How to use functions and filters in Twig
- Detailed information about the Drupal-specific functions and filters and their use case
To read a Twig template file, you'll need to recognize Twig's syntax delimiters. Twig has three syntax delimiters: one for printing out variables, another for performing actions or logic, and lastly, one for comments, also used for docblocks.
In this tutorial we'll:
- Explore each of Twig's 3 syntax delimiters.
- Show examples of each from Drupal's core template files.
By the end of this tutorial you should be able to recognize each of Twig's syntax delimiters and understand what the engine will do when it encounters them.
More often than not, templates in a theme share common elements: the header, footer, sidebar, or more. In Drupal, themes created with a Twig template can be decorated by another one. This template inheritance allows you to build a base "layout" template that contains all the common elements of your layout defined as blocks. A child template can extend the base layout and override any of its defined blocks. This helps prevent code duplication, and keeps your theme more organized.
This tutorial is for theme developers who want to reduce code duplication in their themes, or anyone seeking to better understand how Twig template inheritance works. We'll cover:
- What the Twig
block
andextends
tags do - An example use-case for template inheritance
- How to extend a Twig template from another theme or module
- How to include other Twig templates
Do you cringe at the sight of untidy whitespace or (gasp) no whitespace at all when you View Source? Learn how to tame whitespace in Twig template files in this tutorial. By the end of this lesson, you will be able to recognize how Twig controls whitespace and how you can do the same in your Drupal template files.
Underscore.js is a very small library which provides several utility functions and helpers to make working with JavaScript a little bit easier. In this tutorial we'll take a look at a part of the library, learn where the full library is documented, and see how we can make use of Underscore.js in a custom block on our Drupal site.
Make your theme a subtheme of a base theme, allowing it to inherit all the base theme's templates and other properties. When creating Drupal themes it is common to use the Classy theme provided with Drupal core as a base theme to jumpstart your development.
In this tutorial we'll learn how to:
- Use the
base theme
key in our theme's THEMENAME.info.yml file - Make our Ice Cream theme inherit from the Classy theme, or any other theme
By the end of this tutorial you should be able to tell Drupal that your theme is a child of another theme and should inherit all of the parent theme's features.
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.
ESLint is the linting tool of choice for JavaScript in Drupal. In this tutorial we’ll show how to install the ESLint application and then use it to verify that your JavaScript files are meeting the Drupal coding standards.
Drupal (as of version 8.4) has adopted the Airbnb JavaScript coding standards. In this tutorial, we'll walk through how to install the necessary package dependencies to run eslint on JavaScript files within your Drupal site.
An asset library is a bundle of CSS and/or JavaScript files that work together to provide a style and functionality for a specific component. They are frequently used to isolate the functionality and styling of a specific component, like the tabs displayed at the top of each node, into a reusable library. If you want to include CSS and/or JavaScript in your Drupal theme or module you'll need to declare an asset library that tells Drupal about the existence, and location, of those files. And then attach that library to a page, or specific element, so that it gets loaded when needed.
In this tutorial we’ll:
- Define what an asset library is.
- Explain why asset libraries are used to include JavaScript and CSS files.
- Look at some example asset library definitions.
By the end of this tutorial you should be able to define what asset libraries are, and when you'll need to create one.
Preprocess functions allow Drupal themes to manipulate the variables that are used in Twig template files by using PHP functions to preprocess data before it is exposed to each template. All of the dynamic content available to theme developers within a Twig template file is exposed through a preprocess function. Understanding how preprocess functions work, and the role they play, is important for both module developers and theme developers.
In this tutorial we'll learn:
- What preprocess functions are and how they work
- The use case for preprocess functions
- The order of execution for preprocess functions
By the end of this tutorial you should be able to explain what preprocess functions are and the role they play in a Drupal 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
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.
Maybe you've heard of anonymous closures but you're not quite sure how they apply in Drupal, or why using them is considered a best-practice. Anonymous closures allow you to avoid accidentally clashing with anything in the global scope, as well as to alias the jQuery object to the more commonly used $
. This is necessary because Drupal runs jQuery in no-conflict mode. This tutorial will look at the syntax used for placing your custom JavaScript code inside an anonymous closure, and why it's a good idea to do so.
In this tutorial we'll:
- Explain what a closure is (briefly), and what immediately invoked function expressions are
- Show how typically Drupal JavaScript gets wrapped in a closure
- Provide a copy/paste example you can use in your own code
By the end of this tutorial you should be able to explain what an anonymous closure is, and how to use one in your custom JavaScript for Drupal.