Drupal 8 Theming - Debugging


How many times in Drupal 7 do you find yourself looking up the naming conventions for page or node templates? In Drupal 8 they've also added the ability to create templates per field! Yes, you can go to Google, run a search and start reading through the results, or you can enable Twig Debugging.First and foremost this is not the devel module. There isn't an external module to install either. In the sites/default/ directory you want to locate the "default.services.yml" file, duplicate it and rename to "services.yml". Within the newly created services file you want to paste the following code at the bottom:

  debug : true
  auto_reload: true
  cache: false

Once you've added the code to the new file clear the cache. Then refresh the page and view the page source. The pages within your Drupal 8 website now include extra information such as:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'html' -->
* html--node--39.html.twig
* html--node--%.html.twig
* html--node.html.twig
x html.html.twig-->

The "x" signifies the template in use, and the "*"'s give alternative template options. This is especially useful when needing to create field specific templates:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'field' -->
* field--default--node--title--page.html.twig
* field--default--node--page.html.twig
* field--default--node--title.html.twig
* field--default--title--page.html.twig
* field--default--page.html.twig
* field--default--title.html.twig
* field--default.html.twig
* field--theme-ds-field-default.html.twig
* field--node--title--page.html.twig
x field--node--title.html.twig
* field--node--page.html.twig
* field--title.html.twig
* field--string.html.twig
* field.html.twig

Organization is key when theming for Drupal 8. Inside your theme's directory create a "templates" folder, and within that create as many folders as needed for your projects. You'll most likely want one for layouts (housing your page templates), fields (if you need field specific templates), etc. I created one called "ds", short for Display Suite, to house all layouts I want available within the Drupal UI.

The next debugging tool for templating assists in finding out the available variables within the file. For instance the variables available on the page template will be different than that within the node, field or blocks. Paste the following code into your template to find the options:

{% for key, value in _context %}
  <li>{{ key }}</li>
{% endfor %}

You can also add the Devel module to your Drupal 8 development site. Enable kint with the module, then add the following code to your template:

{{ kint([variable]) }}

The above produces the clickable array structure allowing you to look through the variables and locate the content you wish to output. The devel module isn't stable for a production site and should only be used in a development environment. 

While theming went through a massive overhaul it's great to know there are wonderful debugging tools to help us learn and understand the new structure and API of Drupal 8.

Subscribe to Our Newsletter

Stay In Touch