3.2 Demonstrate knowledge of theming concepts

Review Yml syntax. Review how to add libraries to your code base.

A theme is a collection of files that define the presentation layer. You can also create one or more "sub-themes" or variations on a theme. drupal.org/docs/8/theming

The big change from Drupal 7 to Drupal 8 for theming is the change from PHP templates to twig and the use of yml "YAML" files. (See more about twig in the next few pages.)

CSS file organization

Drupal 8 follows the SMACSS-style categorization. (SMACSS = Scalable and modular architecture for css)

  1. Base — CSS reset/normalize plus HTML element styling.

  2. Layout — macro arrangement of a web page, including any grid systems.

  3. Component — discrete, reusable UI elements.

  4. State — styles that deal with client-side changes to components.

  5. Theme — purely visual styling (“look-and-feel”) for a component

More information about separation of concerns.

CSS file naming conventions

CSS files should be placed in a css/ directory and broken down by module, theme, and admin files.

Note: Modules should never have any base styles. Drupal core's modules do not have any base styles. Instead Drupal core uses the Normalize.css library augmented with a drupal.base.css library.

If a module attaches a CSS file to a template file, the CSS file should be named the same as the template file, e.g. the system-plugin-ui-form.html.twig CSS file should be named system-plugin-ui-form.css


Yaml is a "human readable" markup language designed for data serialization for all programing languages.

  • Syntax for yml is key : value

  • Use a colon as a separator

  • Tabs are NOT allowed. Use spaces ONLY.

  • Properties and lists MUST be indented by two (2) spaces.

  • Yaml files end in the .yml file extension.

    In Drupal 7, modules needed a MODULE_NAME.info file. Now, in Drupal 8 requires a MODULE_NAME.info.yml

  • Use yaml lint to find syntax errors.

  • BLT can validate yml with blt validate:yaml

Key/Value pairs

Key value pairs provide meta-data about your theme.

For example

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x


Sometimes a site will require an external library. Libraries can be defined 3 different ways, within a theme, on a single page, or on a subset of pages with a preprocess function.

Define library within a theme:

Each asset/library needs to be defined in the root of your module folder or in your theme root directory. For example the Drupal contrib module slick requires the external slick library. Inside of the theme directory docroot/themes/custom/MY_THEME there needs to be a MY_THEME.libraries.yml file.

  version: 1.0.0
      stylesheets/ui/slick-rotator.css: {}

In the above example the theme key is for visual styling for a component. You can assign weights, or specify a theme. Therefore, in this example the asset/library slick has defined a css file included inside of the slick module directory.

Another example would be core's classy.libraries.yml file.

Define a library on a single template:

External libraries can increase the weight of a project and slow down a site's performance. If a custom javaScript library only needs to load on a single template, it might make sense to attach the library to only that template. For example, if you add attach_library to the top of twig template file, the library will only load whenever that twig template is used.

{# Place attach_library in a twig template. #}

{{ attach_library('THEME_NAME/library-name') }}

Define a library on a subset of pages:

There can also be instances where you only need to add a library to a specific set of pages instead of every page. You can accomplish this with a preprocess function added the THEME_NAME.theme file.

function MY_THEME_page_attachments(array &$attachments) {
  if (!\Drupal::currentUser()->hasPermission('access contextual links')) {

  $attachments['#attached']['library'][] = 'contextual/drupal.contextual-links';

This is comparable to the Drupal 7 method of adding preprocess functions to the template.php file.

Other Resources

Last updated