Demystifying Drupal

Drupal 7 Theme Debugging

January 11, 2016 - 4:43pm

In November of 2014, Drupal 7.33 was released. This version was tagged as a maintenance release.

Drupal 7.33 Release Notes - Maintenance release of the Drupal 7 series. Includes bug fixes and small API/feature improvements only (no major new functionality); major, non-backwards-compatible new features are only being added to the forthcoming Drupal 8.0 release.

However there was a new, and fantastic feature that was quitely slipped in - theme_debug. Since it wasn't promoted much, very little was said about it for quite some time. This simple setting change can really make an impact while developing Drupal themes.

Chasing down theme template files can be a challenge, remembering all the available naming conventions can be even more difficult. Previously Devel Themer was the go-to solution to peek into the theme system for suggestions. While it was helpful, it had some draw backs. Notably it required the heavy Devel module, and the simplehtmldom API module. Markup was also altered, adding in extra attributes to sift through.

Theme Debug Output
Devel Themer Output

Sample Devel Themer markup
Devel Themer Markup

The new theme_debug mode is considerably more elegant and useful for finding template suggestions. It is enabled by setting the theme_debug variable to true in either settings.php, or in the database with Drush. To enable in settings.php, add this line:

$conf['theme_debug'] = TRUE; 

Simply comment out the line to disable.

Depending on your workflow, setting the variable in the database may be more desirable. I prefer this method, since I typically use Features to push configuration. This way the variable can easily be toggled in the local dev enviroment, but not risk getting pushed to production. To enable with Drush:

drush vset theme_debug 1

To disbable with Drush:

drush vset theme_debug 0

The output with theme_debug is embedded into the DOM as comments.

Theme Debug Output
Theme_debug Output

While theme_debug does an awesome job with template suggestions, it unfortunately does not provide preprocess suggestions, like Devel Themer does.

For  more information on working with templates suggestions in Drupal 7 or 8, see Working with template suggestions on drupal.org.