Up and Theming with Drupal 8

Creating a Theme##

The steps for setting up a basic site theme are fairly simple: create a custom/THEMENAME directory in web/themes, and then add a THEMENAME.info.yml file with the following:

name: THEMENAME Theme
description: 'D8 theme for THEMENAME site.'
package: Custom
# base theme: classy
type: theme
version: 1.0
core: 8.x
regions:
  header: Header
  content: Content # required!
  sidebar_first: 'Sidebar first'
  footer: Footer

Then you can enable your theme (administer » themes) in the interface. Note that uncommenting base theme: classy will cause you to set Classy as a parent theme. We feel that Classy is great if you want a lot of useful examples, but really clutters up the markup, so use at your own discretion. After rc1, the default theme will be ‘stable,’ and you may want to pull all of the core templates into your theme to ensure you’re working from the latest updated template code.

Also, the theme name must not contain hyphens. So /theme-name/ is invalid (it won’t even show up!), but /theme_name/ is fine.

Now we’ll want to start customizing our theme. Let us say we have a content type called ‘blog’ (machine name: blog), with a field type called ‘Publish Date’ (machine name: field_publish_date).

Despite setting the label of field_publish_date to ‘inline,’ it’s wrapping to a new line due to the fact that it’s a simple, unstyled <div>.

Worse, it has no classes to specifically style it. Let’s set ourselves some goals:

1. Add the inline styling class(s).
2. Change the markup for this field, so that we have a class for the label.
3. Add CSS to style the label, but ONLY for the ‘Blog’ content type.

The documentation for this seemingly simple task is obfuscated and evolving right now, but we were able to get it working correctly using the following steps:

Step 1: Turn on twig debug mode. We also found it helpful at this point to make a copy of web/sites/example.settings.local.php in web/sites/default/ and uncomment the following in settings.php:

if (file_exists(__DIR__ . '/settings.local.php')) {
  include __DIR__ . '/settings.local.php';
}

This will allow you to disable caching during development, which is no longer a simple checkbox in the performance section. Note that disabling caching can be tricky; the drush cr (cache rebuild) command is the most reliable way to ensure the cache is really cleared. You’ll also have to rebuild the cache at least once after turning caching off, so the new cache settings are applied.

Step 2: Make a custom field template.

In this case, the suggested debug fields are:

<!-- FILE NAME SUGGESTIONS:
   * field--node--field-publish-date--blog.html.twig
   * field--node--field-publish-date.html.twig
   * field--node--blog.html.twig
   * field--field-publish-date.html.twig
   * field--datetime.html.twig
   x field.html.twig
-->
<!-- BEGIN OUTPUT from 'core/modules/system/templates/field.html.twig' -->

The highlighted line above shows the template currently being used, suggestions for increased specificity, and the file location (core/modules/system/templates/).

We want to update field_publish_date globally, so we’ll create a template called field--field-publish-date.html.twig

>