The Render API consists of a standard format for describing data using structured arrays and a process for converting those arrays into the HTML a user sees when interacting with a Drupal site.
Week 1: Setup
CourseWeek 2: Create a New Theme
CourseWeek 3: Add an Asset Library
CourseYAML, 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)
Hands-On Theming
GuideTheming Cheat Sheet
GuideLearn Drupal
GuideTwig is the theme template engine in Drupal as of version 8. Like any code, there are guidelines and standards that dictate both the style and the structure of the code. In this tutorial we will explain how to adhere to the Drupal code standards while implementing Twig templating.
By the end of this tutorial you will be able to adhere to Drupal's coding standards when writing Twig, and know where to find more information about the guidelines when necessary.
You've got a slick responsive theme for your Drupal site that's been implemented in CSS using media queries. But the content and images on your site will regularly be updated and you want to use the Responsive Images module to create responsive image style field formatters that you can apply to image field display settings.
In this lesson, we'll review the concepts of breakpoints and media queries so that you can better understand what's going on when you encounter them in non-CSS file contexts like configuration forms for responsive image styles or breakpoint YAML files.
By the end of this tutorial, you should have an understanding of what breakpoints are, how they are expressed in media queries, and how they are relevant in the context of Drupal.
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.
Preprocess functions are specially-named PHP functions that allow themes and modules to modify the variables passed to a Twig template file. They are commonly used by themes to alter existing variables before they are passed to the relevant template files. For example; Changing the makeup of render array so that it renders an <ol>
list instead of a <ul>
list. Or appending data to the label of a node depending on custom logic.
In this tutorial we'll:
- Define a new preprocess function in our theme's .theme file
- Use the preprocess functions to modify the content of an existing variable before it's used in Twig
By the end of this tutorial you should be able to define new preprocess functions in a theme (or module) that manipulate the variables for a specific Twig template file.
Theme developers often need to add or remove classes and other attributes from an HTML tag. Template files handle this with a special Attributes object that contains the attributes and their values, as well as a handful of powerful methods to help manage these attributes.
In this tutorial we’ll cover:
- Adding/removing classes from elements in a Twig template
- The attributes object
- Examples of common tasks using various helper methods on the attributes object
Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.
By the end of this tutorial, you should be able to:
- Set up your local Drupal site for theme development
- Prepare your local development environment for working on and debugging themes
Core Themes: Bartik
FreeBartik is a core theme in Drupal. As a default theme for Drupal, it serves as an instructive example of a well-developed responsive theme. In this tutorial, we'll tour and explore Bartik, identify its primary features, and explain the use case for the Bartik theme and what you can learn from it.
Core Themes: Stark
FreeStark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates. In this tutorial, we'll explore Stark and its primary features and discuss the various reasons for utilizing the Stark theme.
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.