YAML for Drupal 8, 9, and 10

YAML, which stands for YAML Ain't Markup Language, is a human-readable data serialization format that's been widely adopted in a variety of use cases in Drupal. Anyone wanting to write modules, or themes, for Drupal will need to understand YAML syntax. Even site builders are likely to encounter YAML at least in passing as YAML is the data-serialization format of choice for Drupal's configuration management system. Good thing it's pretty easy to learn even with the most basic of programming backgrounds.

This tutorial will look at the YAML data format and provide examples of how to write and read YAML. Starting with an introduction to the language's syntax and some of the strengths of YAML. Then looking at the difference between scalar data types like strings and integers, and collection data types like lists and associative arrays.

Since YAML in the Drupal world is read into PHP and ultimately becomes a PHP data structure that we can use in our own code we'll also look at how the YAML we write in a .yml file is represented in PHP data types. To do this we'll use the YAML Sandbox module that provides a handy textarea into which we can type YAML and have it parsed into PHP data structures.

Learning objectives

• Explain what YAML is and its strengths as a data serialization format
• Create scalar key/value pairs in YAML
• Create lists, and associative arrays using YAML collections
• Understand how the YAML you write is represented in PHP

Tips

• In Drupal, use the .yml extension and not .yaml
• Ensure your code editing application is configured to use spaces (preferably 2 spaces, as per Drupal coding standards), not the tab character when the TAB key is pressed. If you have tab characters in a YAML file within a Drupal environment, a fatal PHP error will be thrown and you'll see a White Screen of Death (WSOD).
• Copy and paste from an existing YAML file to ensure the formatting is correct, and edit from there.

Additional resources

• http://www.yaml.org
• YAML Sandbox module
• Find other tutorials and external resources related to YAML on our YAML topic page (Drupalize.Me)

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.

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.

New asset libraries can be defined by either modules or themes. In order to define a new asset library you need to create the requisite CSS and JavaScript files, and a new THEMENAME.libraries.yml, or MODULENAME.libraries.yml file that aggregates them together and provides metadata about the library itself and any dependencies.

In this tutorial we’ll:

• Look at the structure of a *.libraries.yml file and demonstrate how to combine a couple of CSS and JS files together into an asset library that can be used in a theme or a module
• Look at how one asset library can declare that it is dependent on another in order to ensure the assets from the dependency are loaded as well

By the end of this tutorial you should know how to define a new asset library in either a module or a theme.

Once you've defined an asset library you'll need to tell Drupal when you want to add the CSS and JavaScript that it includes to the page. Ideally you'll do so in a way that allows Drupal to only add the corresponding assets on pages where they are needed.

You can attach a library to all pages, a subset of pages, or to elements in a render array. This allows you to have some assets that are global, and others that get loaded on an as-needed basis. To attach a library you'll need to know both its name and prefix, and then use one of the techniques outlined below to let Drupal know when to include it.

In this tutorial, we'll look at attaching asset libraries:

• Globally, via your THEMENAME.info.yml file
• Conditionally, via a preprocess function using the #attached render array property
• Inside of a Twig template file

By the end of this tutorial you should be able to attach asset libraries in various different ways depending on your use case.

Drupal's Breakpoint module defines a "breakpoint" plugin type that modules or themes can implement via a breakpoints configuration file. So, in order to make their breakpoints discoverable, themes and modules define their breakpoints in a THEME-OR-MODULE.breakpoints.yml file located in the root of their directory.

In this tutorial, you'll learn about the structure of a breakpoints configuration file and why you would want to use one. We’ll cover the kinds of metadata you can include in a breakpoint file, including key, label, mediaQuery, weight, multipliers, and breakpoint group. Throughout, we'll look at some examples of breakpoint configuration files available in Drupal themes and modules.

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.

In this tutorial, we'll examine one the first files you'll need in order to create a Drupal module: the info file. Each module is required to have a MODULE.info.yml file to help Drupal identify that a bundle of code is a unique module. This specially-formatted YAML file tells Drupal about the module and provides other useful metadata. In this tutorial, we'll walk through both required and optional information you put in a module's info file.

If you've ever built or administered a Drupal site, the permissions page (/admin/people/permissions) is probably quite familiar.

If you're new to module development, you may wonder where these permissions come from, and how you can specify your own permissions. In this tutorial we'll answer those questions.

First, we'll look at how to define permissions from within a custom module. We'll examine techniques that enable you to provide specific (static) permissions as well as dynamic permissions, which depend on another piece of data, such as the name of a content type. By the end of this tutorial you will understand how to add both static and dynamic permissions to a custom module.

Drupal provides module developers several different methods for creating the different types of links we see on a typical page. In this tutorial we'll see how these different types of links relate to each other, and when you might want to make use of them.

In this tutorial we'll provide an overview of the following concepts:

• Menu links
• Action links
• Local tasks
• Contextual links

In this tutorial we will learn how to add menu links using a custom Drupal module. We will also look at the options available for configuring our new menu link. Lastly, we'll learn about using hook_menu_links_discovered_alter() that can be used to add new menu links, or alter the behavior of existing ones.

Modules can provide action links to make common operations more readily available within a particular context. For example, a site administrator visiting the content management page may be interested in adding content. If you've ever noticed the Add content button on this page, that's an example of an action link. In this tutorial we'll take a look at how custom modules can provide these action links to make it easier for users to interact with our site.

Contextual links provide yet another method for Drupal module developers to add helpful links for site administrators to quickly navigate to commonly used tasks. In this tutorial we'll learn how to implement and render contextual links from a custom module. We will also look at a pair of alter hooks that can be used to tweak existing contextual links.

Local task links are the tabs you see when logged in as an administrator viewing a node on a Drupal site. In this tutorial we'll take a look at how local tasks are added within a custom module. We'll also see how to alter local tasks provided by other modules via hook_menu_local_tasks_alter().

When you create a module for Drupal, it can be useful to provide default configuration. This can be settings for a form, the placement of a block, or something more complex like the default image styles provided by the Image module in core. A module can provide default configuration for simple configuration or configuration entities.

In this tutorial, we will cover:

• Possible locations for default configuration
• What happens with configuration when a module is installed or uninstalled
• Managing dependencies in configuration
• Where to find examples of default configuration

As we learned in Configuration Data Types, simple configuration is suitable for storing module settings as boolean values, integers, or text strings in one or more key/value pairs. In this tutorial, we'll walk through creating a schema and providing default configuration to store initial settings that a module needs to function.

In this tutorial we’re going to walk through the process of creating a custom configuration entity in Drupal in a custom module. We'll be using Drupal Console's generate:entity:config command to create and update the files in our Transcode Profile example module. After Drupal Console has generated and updated the files for our configuration entity, we'll walk through each file and see how they define data structure, metadata, an administrative interface, and menu links for a configuration entity in Drupal.

By the end of this tutorial, you should be able to:

• Use Drupal Console to generate a configuration entity
• Identify files associated with a configuration entity and summarize the purpose and function of the code inside each file
• Find other examples of configuration entities in Drupal core