Drupal 8 Theming: Setting up theme debugging

We’re certainly not strangers to Drupal training. Chapter Three has a long history of instructing community members, old and new, on the various ways to theme Drupal. One of our more prominent training courses is a head-to-toe walkthrough of Drupal 7 theming. With Drupal 8’s release candidate, we created a new training series: “Drupal 8 Theming for Drupal 7 Themers”. The following information is based on an exercise from our new training series:

Exercise 1: Theme debugging

Theming in Drupal is taking processed data from Drupal, and outputting it in an HTML structure so that web browsers can display the content as designed. Themes make Drupal websites beautiful, and can make the difference between a user-friendly site and a difficult-to-use site. A good theme will show off the best parts of your website, while maintaining the speed and flexibility that Drupal offers. 

Just as you can't successfully build a house without knowing what a hammer is or where to find lumber and materials, you can't successfully theme a site if you don't know about its variables, settings and data. To help with this, we will be enabling Drupal's built-in theme debugging and adding/editing some settings for local theme development. We will also be downloading and enabling the Devel module, to give us even more information about what's going on under the Drupal hood.

Enable theme debugging and other local settings:

1. Using your terminal, or through your display, locate your settings.php file. The file is usually found at MYDRUPAL/sites/default/settings.php.

2. Change permissions for the sites/default folder (if needed) using the following terminal command:

   MYDRUPAL should be the path to your drupal sites root directory. Make sure to adjust your terminal commands accordingly.

   
   $ chmod -Rf 775 MYDRUPAL/sites/default/

3. Open up the settings.php file in your preferred code editor and uncomment the following lines (~ lines 682-684):

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

4. Copy the file MYDRUPAL/sites/example.settings.local.php to MYDRUPAL/sites/default/settings.local.php using the following terminal command, or through your display:

   
       $ cd MYDRUPAL
       $ cp sites/example.settings.local.php sites/default/settings.local.php

5. Locate the following line in default/settings.local.php:

   
   $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

   Change it to:

   
   $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/default/local.services.yml';

6. Create the local.services.yml file from default.services.yml. Copy the default file and rename it using the following terminal command, or through your display.

   
       $ cd MYDRUPAL
       $ cp sites/default/default.services.yml sites/default/local.services.yml

   Inside local.services.yml, locate the debug line in the twig configuration (line 58) and change it to true

   Parameters:

   
         [...]
         twig.config:
         [...]
             debug: true

   Remember spaces are significant in .yml files. If something doesn't work after updating a yml file, check for errant spaces.

7. Clear registry and visit your site. View the source code. You should now see template suggestions in the source code of your local site. Since everything in Drupal is now output by a template file via Twig, we can see exactly what templates are outputting every part of our webpage. Beats the heck out of trying to track down a theme function or look through template directories to find a potential match.

   Below is an example of the potential output. The line item beginning with an "x" is the twig template that is used for this element. The rest are registered file naming suggestions that you can use as an override.

   
   <!-- THEME DEBUG -->
   <!-- THEME HOOK: 'node' -->
   <!-- FILE NAME SUGGESTIONS:
      * node--article--teaser.html.twig
      * node--article.html.twig
      * node--teaser.html.twig
      x node.html.twig
   -->
   <!-- BEGIN OUTPUT from 'core/themes/classy/templates/content/node.html.twig' -->
   

Enable Devel and kint debugging:

1. Download the Devel module and install Devel. For information on installing a Drupal 8 module, please see Drupal 8 Module Installation. Kint comes with Drupal core, so it's already enabled… Good job! UPDATE: Around the release of 8.0, devel_kint module is now required to be enabled in order to run kint().

2. No additional settings are needed after installation. At the time of publishing (RC-2), these modules were mostly functional, but did have some issues when trying to view their administration pages. If any issues pop up with installation, please check the modules project page for any updates or patches.

As we work on the exercises, you can use kint('$VARIABLE_NAME') or ksm('$VARIABLE_NAME') to see what data you have available to you inside of a function. You replace $VARIABLE_NAME with the actual variable that you want to view the contents. Since kint() prints out its information only when its called, it can sometimes be difficult to see where its at. It may be in the sidebar, content, or even the footer depending on what element you are kinting. To bring your of your kints into the message area, use ksm() intead of kint().

Additional:

Often when we make a change on the theme layer, it won't always appear immediately. Always remember that twig and templates like to be cached, and won't show any changes until cache is cleared. To clear the registry (aka "Clear Cache") use $ drush cr or go to Configuration > Performance and Clear All Caches.