Debugging drupal themes

December 13th, 2015

I recently had some issues with the output in a Drupal project, but then I learned a new trick.

Being primarily a back end developer I get kind of stuck when it comes to output issues. I focus mostly on security, database optimization, business logic, and things like that, and leave the theming to my awesome colleagues. They are just not always available so sometimes I have to troubleshoot myself. I usually use devel_themer, but in this particular project it didn't work. It would not output anything on the page even though it was enabled. I assumed it was because php had hit the memory limit.

After some googling of alternatives to devel_themer I came across a Drupal release post. The release post for Drupal 7.33 to be exact. In it I found this note:

Added a "theme_hook_original" variable to templates and theme functions and an optional sitewide theme debug mode, to provide contextual information in the page's HTML to theme developers. The theme debug mode is based on the one used with Twig in Drupal 8 and can be accessed by setting the "theme_debug" variable to TRUE (API addition). 

This wonderful little creature will - when enabled - add comments to the HTML which in my case was immensely helpful. The comment tells you which template file was used and which other file patterns was looked for. The output looks like this:

<!-- THEME DEBUG -->
<!-- CALL: theme('panels_pane') -->
   * panels-pane--run-longest-run--run-longest-run.tpl.php
   * panels-pane--run-longest-run.tpl.php
   x panels-pane.tpl.php
<!-- BEGIN OUTPUT from 'sites/' -->
<div class="panel-pane pane-run-longest-run"  >

        <h2 class="pane-title">
      Longest run    </h2>

  <div class="pane-content">
    6.50 km  </div>


<!-- END OUTPUT from 'sites/' -->

As you can see you will get the following information:

  • What argument the theme function was called with (e.g. panels_pane).
  • A list of file name suggestions and the file name chosen is marked with x.
  • A BEGIN and END with the path to the template file used.

You can enable this feature in two ways; via Drush and the settings file. Just a reminder: Do not enable this in production, since it will show internal paths of your system, which might not be a good idea. In the settings.php file you add the following line:

$conf['theme_debug'] = TRUE;

If you have Drush installed you can enable it with this command. Remember that boolean values should be written in all caps otherwise Drush will save it as a string and not a boolean. (Note that I use an alias for my site. I you do not have drush aliases your working directory needs to be in your drupal root.)

drush @intra vset theme_debug TRUE

The day I worked on this problem I learned two things. Firstly I obviously learned how to debug Drupal theming. Secondly I learned to keep up to date with changes by reading the release notes. This does not only apply for Drupal, but also all other open source libraries and frameworks I use, including the PHP language itself.